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

For a company with shareholders enabling voting for every shareholder is a task and has associated costs. Enabling e-voting for all users via blockchain will help reduce the cost and also give the regulators and other parties a clear and tamper proof trail of the events thus helping reduce malpractices in voting.

1) In this use case we will create a company and then create some shares for this company, all these shares will be common shares and will have equal voting rights (1 vote per share). 2) These shares will be issues to shareholders, who can then vote on a particular proposal. 3) The proposal will pass or get rejected based on the total vote majority 4) The shareholders can also transfer the shared to another user

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 here)
  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.

5) Create the participants

In this step we will create the company and its shareholders. These are the participants that are required of the e-voting process to be demonstrated end to end.

Under the Participants tab to the left, the type of participants will be displayed. There should be two participant called Company and Shareholder.

Each participant tab will display list of users registered as 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 Company. Click the company tab on the left. and click Create New Participant in the upper right corner.

Let us create a company c1 with its name as XYZ Corp having its shares represented by s1, with a turnover of 100 crores and be a public compnay. The input JSON to create a company is provided below

            
  {
    "$class": "com.algorythmix.base.Company",
    "registrationId": "c1",
    "companyName": "XYZ Corp",
    "shareId": "s1",
    "turnover": 100,
    "type": "Public"
  }
            
          

The company tab now shows a company with the data that we had used as input. This can be edited by clicking the edit button if needed.

Similarly for the shareholders we need to click the shareholder tab followed by Create New.

Let us create a share holder with name as Shareholder One and shareHolderId as s001 and his nationalId as 111222333001. A sample JSON for the shareholder is provided below

          
  {
    "$class": "com.algorythmix.base.ShareHolder",
    "shareHolderId": "s001",
    "name": "Shareholder One",
    "NationalIdNo": "111222333001"
  }
        
      
demo image one

demo image two

demo image three

6) Create shares for a company

To create shares for the company that we had created earlier we need to execute the CreateShare transaction.

Click on the Submit transaction button and select CreateCompanyShare from the dropdown.

A sample JSON is provided below, the fields required are as follows

  1. Specify a unique shareId s1 for the share type getting created, we are assuming that these are common / equity shares with 1 vote per share.
  2. These shares are for the company with companyRegistrationId c1
  3. And c1 can issue upto totalAuthorizedShares for which we set the value as 100000
            
  {
    "$class": "com.algorythmix.base.CreateCompanyShare",
    "shareId": "s1",
    "companyRegistrationId": "c1",
    "totalAuthorizedShares": 100000
  }
            
          
demo image four

7) Issue shares

Once the shares are created these can be issued to shareholders. For the simplification of the use case we are going to issue shares to the shareholders directly via a transaction and there will not be any monetary transaction in this example.

To issue shares to shareholder click on Submit Transaction and select IssueShares from the drop down.

  1. Let us issue shares with shareId s1
  2. The numberOfShares that we are issueing is set to 125
  3. These 125 shares are being issues to the share holder with the ID s1

Let's issue shares to shareholders sh2 and sh3 as well

Sample JSON is provided below with the required fields

            
  {
    "$class": "com.algorythmix.base.IssueShares",
    "shareId": "s1",
    "numberOfShares": 125,
    "to": "sh1"
  }

  {
    "$class": "com.algorythmix.base.IssueShares",
    "shareId": "s1",
    "numberOfShares": 150,
    "to": "sh2"
  }

  {
    "$class": "com.algorythmix.base.IssueShares",
    "shareId": "s1",
    "numberOfShares": 975,
    "to": "sh3"
  }
            
          

demo image five

Verify the new distribution of shares by checking the details on the Company Shares under the assets tab

            
  {
    "$class": "com.algorythmix.base.CompanyShare",
    "shareId": "s1",
    "companyRegistrationId": "c1",
    "totalAuthorizedShares": 10000,
    "totalIssuedShares": 1250,
    "shares": [
      {
        "$class": "com.algorythmix.base.Shares",
        "shareHolderId": "sh1",
        "numberOfShares": 125,
        "createdAt": "2019-05-07T06:22:04.900Z",
        "lastModified": "2019-05-07T06:22:51.256Z"
      },

        "$class": "com.algorythmix.base.Shares",
        "shareHolderId": "sh2",
        "numberOfShares": 150,
        "createdAt": "2019-05-07T06:22:19.859Z",
        "lastModified": "2019-05-07T06:22:19.859Z"
      },
      {
        "$class": "com.algorythmix.base.Shares",
        "shareHolderId": "sh3",
        "numberOfShares": 975,
        "createdAt": "2019-05-07T06:22:34.152Z",
        "lastModified": "2019-05-07T06:22:34.152Z"
      }
    ],
    "listedOn": "2019-05-07T06:21:37.608Z"
  }
            
          

8) Create a new proposal

Now that we have shares allocated to shareholders we can create a test proposal for vote. To create a proposal, click Submit Transaction and select CreateProposal.

Lets say that this proposal is for appointment for a new director.

  1. The unique proposalId for the proposal being created is set to p1.
  2. This is for the company with companyRegistrationId c1
  3. The proposal statement is for Appointment of a new director
  4. A sample JSON is provided below

            
  {
    "$class": "com.algorythmix.base.CreateProposal",
    "proposalId": "p1",
    "companyRegistrationId": "c1",
    "statement": "Appoint new director"
  }

            
          
demo image seven

9) Vote on a proposal

Shareholders can start voting on the proposal created above. Every shareholder who has shares at the time the proposal was created may vote. For this example voting is done via closed ballot method.

  1. The share holders vote for the proposalId p1
  2. Share holder with shareHolderId sh1 votes
  3. The vote of sh1 is of voteType FOR, in favor of the proposal

In our example, shareholder sh1 and sh2 vote in favor of the proposal, whereas shareholder sh3 votes against it.

A sample JSON for all three votes is provided below

            
  {
    "$class": "com.algorythmix.base.VoteOnProposal",
    "proposalId": "p1",
    "shareHolderId": "sh1",
    "voteType": "FOR"
  }
  {
    "$class": "com.algorythmix.base.VoteOnProposal",
    "proposalId": "p1",
    "shareHolderId": "sh2",
    "voteType": "FOR"
  }

  {
    "$class": "com.algorythmix.base.VoteOnProposal",
    "proposalId": "p1",
    "shareHolderId": "sh3",
    "voteType": "AGAINST"
  }
            
          
demo image eight

After submitting the votes, verify they have been reflected in the proposal asset. Based on the shares(votes) of each shareholder, the proposal will automatically be approved or rejected.


demo image nine

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