Deployment Guide

In this step by step tutorial we will walk you through setting up a business network and testing your smart contract by creating and submitting transactions to change the ownership of the asset from one to another.

You will learn how to register new participants, create assets and call the transaction functions as defined.

For the purpose of this tutorial we have taken a specific use case. Based on your selection, your participant and asset parameters may be different, but the basic principles remain the same.

Use Case

1) Tokenization is a method that converts rights to an asset into a digital token. Suppose there is an appartment worth $1,000,000. 2) Tokenization can transform this apartment into 1000,000 tokens (the number is totally arbitrary, we could have created 2 million tokens). 3) These tokens can be bought for actual money by multiple interested parties and they will co own the asset in the proportion of the tokens they own. 4) To buy the tokens the users / buyers will need money or some form of prevalent currency, which we have defined as coin. 5) Coins can be treated as real world money to buy the asset tokens. On selling the tokens the seller gets back the equivalent number of coins. 6) For the sake of simplicity the asset token price is considered to be fixed in this scenario.

The .bna file for this use case can be downloaded by clicking here.

1) Load the test environment

We will use Composer Playground as the environment to test the smart contract. Click here to open Composer Playground. If it does not load, you can try this.

There are no prerequisite to running this tutorial. The blockchain network will be loaded within your browser. Pretty cool, isn't it?

2) Create a new business network

A business network represents a smart contract installed on Hyperledger Fabric using Hyperledger Composer.

The My Business Network page shows you a summary of the business networks you can connect to, and the identities you can use to connect to them. You can also choose to create a new business network using any of the provided templates, or import your own template. Feel free to explore the templates provided by IBM at your leisure.

  1. Click Deploy a new business network under the Web Browser heading to get started.
  2. Step 1. displays the name, a brief description and a name assigned to the admin card. This is auto-generated based on the bna file, ignore it for now.
  3. Go to step 2. and click the Drop here to upload button. Browser to where you downloaded your bna file and select it. (The bna file for this example can be found above)
  4. Once the file is uploaded the card on the right side will show the details of the business network - network name, description, connection profile, number of participants, assets and transaction.
  5. Notice Composer updated the basic information section based on your the bna file. Click the deploy button under the card. This will deploy the business network.

3) Connect to the business network

After deploying the business network, you will be redirected to the home page. You should see a new card named after the project name filled in by you. This allows us to connect to the new business network

A default Composer Card with the user ID - admin will be auto generated and used for all subsequent transactions. A Composer Card holds the public certificate and private key reuired to uniquely identity a participant. You may access the in-browser wallet and issue your own identities, but that is out of the scope of this tutorial

  1. To connect to our business network click Connect Now at the bottom of the business network card.
  2. You will be redirected to a page that allows you to test and alter the smart contract, all within your browser

4) Business Network Editor

Once redirected, you will see a page with a lot of options. Let's go through them one by one.

In the top part of the screen you will see two tabs - Define and Test. Make sure Define tab is selected. To the left there will be four options - About, Model File, Script File and Access Control.These define the parameters of the asset, participants and functions used.

The Test tab allows you to submit transactions to the blockchain, view the world state and view the block explorer. Click on the Test tab to get started.

4) Create the participants

Under the Participants tab to the left, the type of participants will be displayed. There should be one participant type called User

Each user will be displayed as a separate cards. As no participants have been created, this will be an empty list. You may click on each card to view its details displayed in a JSON format. The data structure depends on the parameters defined by you. The parameters beginning with a $ represent reserved namespaces and should be ignored

Let's start by registering a User. You may want to create multiple users for the transactions later on.

  1. Select the User tab on the left, and click Create New Participant in the upper right corner.
  2. You will see a popup asking you to fill in the details of the new participant. You may fill in any values, or simply click on Generate Random Data. The only caveat is each user must have a unique user ID
  3. The details of the new participant will now be visible. To edit any details select the edit button to the right of the participant card and enter your new values. Do note, the user ID field cannot be changed.

A sample JSON is provided below. This creates a User with user ID 001 and a national ID 112201.

            
  {
    "$class": "com.algorythmix.base.User",
    "userId": "001",
    "nationalId": "112201"
  }
          
        

You should be able to see the new User participant you've created. Try creating two more users with id 002 and 003. We will need these later.

demo image one

5) Create a coin

Now that we have our participants, we need some coin for them to buy the asset tokens, which we will create in the next step. We have a transaction called CreateCoin to create the coins for this use case.

Click on transactions and select CreateCoin from the drop down. The sample JSON provided will create a new coin with the following specifications.

  1. Unique identification string for the coin as coinID. Multiple coins each with unique coinID can be created.
  2. Defines how many of a particular type of coin are created by setting a value for totalSupply.
  3. Give this coin a nice name, in our case lets call it CUR for currency

The sample JSON provided will creates a new coin with a total supply of 1000000 units and currency name CUR

            
  {
    "$class": "com.algorythmix.base.CreateCoin",
      "coinId": "c1",
      "totalSupply": 1000000,
      "currency": "CUR"
  }
          
        
demo image two

6) Tokenize an asset

For our example we will tokenize a lavish apartment worth 1,000,000 in CUR into 1,000,000 tokens, thus each token costing 1 CUR to buy. Again for the sake of simplicity we are going to keep the token price constant. In a real world scenario, the token price may vary based on market demand and supply

Click on transactions and select CreateTokenizedAsset from the drop down. Following information needs to be specified in the input to create the Asset Tokens.

  1. Unique assetID for this asset as appartment.
  2. The coinID, C1 of the coin or currency that will be used to buy this token.
  3. Lets make user with userId 001 the owner of this asset by defining OwnerID of the asset owner as 001.
  4. Set the totalSupply as 1,000,000. This is the maximum number of units the asset (appartment) is being split into.
  5. Set a description of the asset. In our case a lavish appartment.
  6. Now for the asset token to be tradeable we let us define that it can be traded for tokens amount equal to the rate specified for a particular coinID, lets say 1 CUR coin which is having the ID c1 can be exchanged for 1 asset token.
            
  {
    "$class": "com.algorythmix.base.CreateTokenizedAsset",
    "assetId": "appartment",
    "coinId": "c1",
    "ownerId": "001",
    "totalSupply": 1000000,
    "assetType": "lavish apartment 4 bedroom",
    "pricePerUnit": {
      "$class": "com.algorythmix.base.PricePerUnit",
      "rate": 1,
      "coinId": "c1"
    }
  }
            
          
demo image three

7) Issue coins

Now that we have created the coins and the asset, token we can proceed to testing out the transactions for issuance of coins and buying of asset tokens

First we need to issue some coins to our users so that they can buy tokens.

Click on transactions and select IssueCoin from the drop down. Following information needs to be specified in the input to issue coins to the users. Let us distribute some of the coins to the users that we have created.

  1. We are issuign coin with coinID C1 to the users
  2. Let us issue 10000 C1 to user with userID 002 and another 10000 to user with userID 003
            
  {
    "$class": "com.algorythmix.base.IssueCoin",
     "coinId": "c1",
     "to": "002",
     "amount": 10000
  }
            
          

Lets issue some coin to user c3

            
  {
    "$class": "com.algorythmix.base.IssueCoin",
     "coinId": "c1",
     "to": "003",
     "amount": 10000
  }
            
          

You can check the coin ownership statistics by clicking the Coin tab on the left. Of the total supply of 1000000 CUR coins , user 002 has 10000 CUR coins and user 003 has 20000 CUR coins as issued in the previous transactions.

            
 {
   "$class": "com.algorythmix.base.Coin",
   "coinId": "c1",
   "totalSupply": 1000000,
   "circulatingSupply": 30000,
   "currency": "CUR",
   "holdings": [
     {
       "$class": "com.algorythmix.base.Holdings",
       "amount": 10000,
       "ownerId": "002"
     },
     {
       "$class": "com.algorythmix.base.Holdings",
       "amount": 20000,
       "ownerId": "003"
       }
     ],
     "listedOn": "2019-05-07T09:27:48.171Z"
 }
            
          
demo image four

8) Trade asset tokens

So we have users, we created coins and issued these coins to users, we also tokenized the lavish apartment, now let us buy those asset tokens.

Click on transactions and select TradeTokenizedAsset from the drop down.

In this transaction we need to specify the asset, buyer, seller and the amount of tokens that are being traded.

  1. The appartment asset token assetId a1
  2. The buying user's userId 002
  3. The selling user's userId 001
  4. And the amount of 5000 for the tokens which are being traded in this transaction

The sample JSON provided will creates a new coin with a total supply of 1000000 units and currency type CUR

            
  {
    "$class": "com.algorythmix.base.TradeTokenizedAsset",
    "assetId": "a1",
    "buyer": "002,
    "seller": "001",
    "Amount": "5000"
  }
          
        
demo image five

Cross check if the participant and asset values have changed as per the transactions submitted above

demo image six

demo image seven

Did you enjoy it?

Thank you for taking the time to go through the prototype and test environment guide.

Can you spare a few minutes to help us be better?

Note: All fields are completely optional

1) Did you complete the tutorial

2) Choose the appropriate option

Strongly Disagree Disgree Neutral Agree Strongly Agree
The smart contract generator was easy to use and understand
The deployment guide was easy to understand and follow
There is a need for such prototyping tools to drive mass adoption by enabling the lay-man to build dApps
A third party security audit of the template(s) is required to build sufficient trust to use them
The template is flexible enough to satify most use cases in supply-chain
You would be comfortable in using a "Wordpress for blockchain" type platform in production/ with real money
3) Loved or disliked a feature? Let us know so we can improve 4) We want to add more templates. Do you have ideas in mind? 5) Email Address Note: This is entirely optional. A single email will be sent to follow up on any ideas/ suggestions