fabricasdk 0.2.0

fabrica sdk

installation

The Fabrica SDK can be installed directly from PyPi with:

pip install fabricasdk

configuration

The Fabrica SDK uses a config file to determine which network, network settings and accounts should be used when calling the SDK's methods.

Below is an example of a config file that uses the Rinkeby test network.

#rinkeby-config.json

{
  "private_key":"<user_private_key>",
  "cosigner_address": "<cosigner_address",
  "fabrica_api_url": "https://4hcsqf7aw0.execute-api.us-west-1.amazonaws.com/production",
  "fabrica_api_key": "hMieYmc2ewr@#E2!c8==3evb",
  "ipfs_endpoint": null,
  "ipfs_port": null,
  "network_url": "https://rinkeby.infura.io/j0RAOpI99Wf54yIYxNB6",
  "local_state_path": null
}

Config Arguments

private_key: defaults to None, represents the private key of the sender; if this parameter is None all contract functions will be called with the transact method instead of a signed sendRawTransaction. This address/private key should be thought of as the primary user of the SDK.

cosigner_address: defaults to None, represents the public eth address of the cosigner. This address should be different than the address associated with the private_key above.

fabrica_api_url: defaults to None, represents the Fabrica API url

fabrica_api_key: defaults to None, represents the Fabrica API key

ipfs_endpoint: defaults to https://ipfs.infura.io

ipfs_port: defaults to 5001

network_url: defaults to http://localhost:8545 represents the blockchain network to use;

local_state_path: defaults to ~/fabrica-state.db, represents the path to the local state file and will be used if no state plugins are provided to the SDK constructor ` To instantiate the SDK with the above config file you can do the following:

from fabricasdk import FabricaSdk

fabrica = FabricaSdk(os.path.join(dirname, "rinkeby-config.json"))

Multisig Wallet Overview

The Fabrica SDK can be used with either a single ethereum account private/public key pair or with a multisig wallet that is generated by the SDK. The multisig wallet requires signing from 2 of 3 ethereum accounts before a transaction is executed.

A typical multisig wallet will consist of the following three signers:

1. The user_address which is best thought of as the SDK user address.

2. The cosigner_address which initially will be Fabrica's address.

3. The customer_address which represents the account address of the end user.

The sender_address and cosigner_address are specified in the above mentioned config file.

To generate a multisig wallet for a new user you must do the following:

from fabricasdk import FabricaSdk

fabrica = FabricaSdk(os.path.join(dirname, "rinkeby-config.json"))

customer_address = "0x94bebe960a5de83911e901b309bd7dfb1cd7a679"

# multisig wallet created here

receipt = fabrica.factory.create(customer_address)

print(receipt)

Multisig Transaction vs Non-Multisig Transaction

All core methods in the Fabrica SDK can be called either via a multisig wallet or with a "non-multisig" wallet. In the case that you choose not to use a multisig wallet the SDK will atempt to execute the transaction using the sender_address and private_key specified the config file.

All core methods in the Fabrica SDK accept optional parameters cosign and customer_address. By default cosign=True. When cosign=True you must also include the customer_address which is the public account associated with the user that is 1 of the 3 signers of the multsig wallet.

Example:

from fabricasdk import FabricaSdk

fabrica = FabricaSdk(os.path.join(dirname, "rinkeby-config.json"))

token_id = int(time.time())

customer_address = "0x94bebe960a5de83911e901b309bd7dfb1cd7a679"

# mints a token using a multisig wallet associated with the customer_address

fabrica.token.mint(token_id, "geoHash", "holdingEntity", "ipfs:/ipfs/whatever", customer_address=customer_address)

# mints a token using the sender_address and private_key specified in the config file

fabrica.token.mint(token_id, "geoHash", "holdingEntity", "ipfs:/ipfs/whatever", cosign=False)

Creating Token Metadata with the mint method

Metadata associated with a Fabrica Token is stored in a json object. The Fabrica SDK mint function allows you to either pass a dictionary of values that are used to create a metadata object which is stored on IPFS and referenced from the token or pass a URL to the method which points to an existing metadata object or.

Below is an example of minting a token using a) a dictionary of values and b) a metadata URL

from fabricasdk import FabricaSdk

fabrica = FabricaSdk(os.path.join(dirname, "rinkeby-config.json"))

token_id = int(time.time())

# mint a token passing a dictionary of values to create a metadata object

receipt = fabrica.token.mint(
      token_id,
      "geoHash",
      "holdingEntity",
      {"name": "this is the name", "description": "this is the description"},
      cosign=bool(customer_address),
      customer_address=customer_address
  )

# mint a token passing a dictionary of values to create a metadata object including legal document creation (final legal document values TBD)

receipt = fabrica.token.mint(
      token_id,
      "geoHash",
      "holdingEntity",
      {
          "name": "this is the name",
          "description": "this is the description",
          "document": {
              "day": "19",
              "month": "08",
              "year": "2018",
              "grantor": "Steven Smith",
              "entity_id": "321123",
              "smartcontract_address": "0x00202020202",
              "property_legal_description": "this is a cool house",
              "trustee": "John Smith",
              "county": "Orange"
          }

      },
      cosign=bool(customer_address),
      customer_address=customer_address
  )




# mint a token using a URL that points to an existing metadata object

receipt = fabrica.token.mint(token_id, "geoHash", "holdingEntity", "ipfs:/ipfs/QmaFWUrRKHbNqKcZfUmnVMB38sb8XWJiJ27S5vH1NsaEai", customer_address=customer_address)

The get_token() method can be used to verify and view the token that you just created

example:

from fabricasdk import FabricaSdk

fabrica = FabricaSdk(os.path.join(dirname, "rinkeby-config.json"))

print(fabrica.token.get_token("1"))

the return value should include both the core token data stored in the smart contract and the associated metadata.

example:

{'token_id': 1, 'geohash': '9q8zn2ez3uev', 'holding_entity': 'Fabrica 1', 'token_uri': 'https://ipfs.io/ipfs/Qmbh7EHR9EfPdWfwWB6tuKXjSGHWzVX36kp6e3TNmMfX3M', 'metadata': {'name': '1707 Jones Street', 'description': 'awesome property', 'formationDocURI': 'https://ipfs.io/ipfs/QmRnE2rQqKdE2Zus59ourBuEKy3BtHg7SYf9wyi9QdTnN8'}}

Usage non-multisig

Below are examples of how do perform the following basic functions with the sdk: minting a token, updating a token and transferring a token without a multisig wallet.

#minting a token

#create a unique token id
token_id = int(time.time())

customer_address = "0x94bebe960a5de83911e901b309bd7dfb1cd7a679"


#call the mint method of the SDK with a token id, geohash(string), holding entity(string), tokenuri (string)

#NOTE: the tokenURI points to a metadata object for the property(address, legal description and link to the formation legal document). Creation of the metadata object will be included in the next version of the SDK, along with conversion of lat/lng geocords to geohash.

receipt = fabrica.token.mint(token_id, "geoHash", "holdingEntity", "ipfs:/ipfs/whatever", cosign=False)

#verify that the token was successfully minted
token = fabrica.get_token(token_id)
print("token: {}".format(token))

#call the update method of the SDK with a token id, holding entity (string), and tokenuri (string)

receipt = fabrica.token.update_token(token_id, "otherEntity", "otherUri", cosign=False)
print(receipt)

#verify that the token was successfully updated
token = fabrica.token.get_token(token_id)
print("token: {}".format(token))

#call the transfer_from method of the SDK with the address of the existing token holder(your address), the address that you are sending the token to and the token_idself.

receipt = fabrica.token.transfer_from(<from_address>, <to_address>, token_id, cosign=False)
print(receipt)

token=fabrica.token.get_token(token_id)
print("token: {}".format(token))

Usage multisig

Below are examples of how do perform the following basic functions with the sdk: minting a token, updating a token and transferring a token with a multisig wallet (including creation of the multisig wallet).

#minting a token

#create a unique token id
token_id = int(time.time())

#set customer address. note: this should be a valid ethereum address

customer_address = "0x94bebe960a5de83911e901b309bd7dfb1cd7a679"

#create multisig wallet

receipt = fabrica.factory.create(customer_address)

print(receipt)


#call the mint method of the SDK using cosign with a token id, geohash(string), holding entity(string), tokenuri (string)

#NOTE: the tokenURI points to a metadata object for the property(address, legal description and link to the formation legal document). Creation of the metadata object will be included in the next version of the SDK, along with conversion of lat/lng geocords to geohash.

receipt = fabrica.token.mint(token_id, "geoHash", "holdingEntity", "ipfs:/ipfs/whatever", customer_address=customer_address )

#verify that the token was successfully minted
token = fabrica.get_token(token_id)
print("token: {}".format(token))

#call the update method of the SDK using cosign with a token id, holding entity (string), and tokenuri (string)

receipt = fabrica.token.update_token(token_id, "otherEntity", "otherUri", customer_address=customer_address)
print(receipt)

#verify that the token was successfully updated
token = fabrica.token.get_token(token_id)
print("token: {}".format(token))

#call the transfer_from method of the SDK using cosign with the address of the existing token holder(your address), the address that you are sending the token to and the token_idself.

receipt = fabrica.token.transfer_from(<from_address>, <to_address>, token_id, customer_address=customer_address)
print(receipt)

token=fabrica.token.get_token(token_id)
print("token: {}".format(token))