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) We have a network of Coffee Bean Growers(participant one) and Processors(participant two). The system is designed to track transformation of Coffee Beans(asset one) to Instant Coffee(asset two) ready for consumption 2) The coffee growers claim consignments of coffee beans and dispatch them to the processor. While the consignment is in transit, humidity level is monitored and recorded continuously via sensors. This is very crucial for quality of the processed coffee. 3) The processor accepts the delivery of the coffee beans and subsequently uses them as input to make to make Instant Coffee.

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.

4) Create the participants

Under the Participants tab to the left, the type of participants will be displayed. There should be two participant types as defined by you. For our case the participant types are Coffee Grower and Processor

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 Coffee Grower. Depending on your inputs, select the name tag given to participant one.

  1. Select the Coffee Grower 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 registration 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 registration ID field cannot be changed.

A sample JSON is provided below. This creates a Coffee Grower with registration ID 001, country of operation as India, reputation score S and GPS coordinates (19.08, 72.87).

            
  {
    "$class": "com.algorythmix.base.CoffeeGrower",
    "registrationId": "001",
    "country": "India",
    "gps": {
      "$class": "com.algorythmix.base.Gps",
      "latitude": 19.08,
      "longitude": 72.87
    },
    "repScore": "S"
  }
          
        

You should be able to see the new Coffee Grower participant you've created. Let's register a Processor (participant two). Select the Processor tab on the left and click Create New Participant in the upper right.

The steps to create a new Processor are identical to the ones above. A sample JSON for the Processor is provided below

          
  {
    "$class": "com.algorythmix.base.Processor",
    "registrationId": "002",
    "country": "India",
      "gps": {
        "$class": "com.algorythmix.base.Gps",
        "latitude": 18.4,
        "longitude": 72.876
      },
    "repScore": "A"
  }
        
      

Click both the participant tabs on the left and verify the participant data for the ones we have created just now. The data can be edited by clicking the edit button on the top right of the participant data card. If all the data seems fine we can move to the next step.




5) Create the assets

Now that we have both our participants, we need something for them to transact with. Remember asset one (Coffee beans) must only be created by a participant one (Coffee Grower), while asset two (Instant Coffee) must only be created by participant two (Processor).

Creating an asset is very similar to creating a participant. Each asset has a createdBy property that must be the registration ID of the appropriate participant. This serves as an access control layer. Let's start by creating a new consignment of Coffee Beans

Click the Coffee Beans tab under Assets and click Create New Asset. The popup will show all the properties available based on your customization. You may fill in the fields or simply click on generate random data. However, ensure that

  1. createdBy has the registration ID of participant one (Coffee Grower)
  2. stateOfProduct stays as PREPARED - This tracks the movement of the product
  3. buyerId remains blank - This is filled when the sale of the asset is initiated
  4. isConsumed remains false - This is used to represent if the Processor has used the coffee beans
  5. humidity array remains blank. This will be autopopualted via sensor data

The sample JSON provided will creates a new consignment of coffee beans with following details-

  1. Tracking ID cb001
  2. Created by Coffee Grower with registration ID 001
  3. Price of 100 (your choice of currency)
  4. Made by a grower with an Organic certificate
  5. Expiry date of 10 days
            
  {
    "$class": "com.algorythmix.base.CoffeeBeans",
      "trackingId": "cb001",
      "daysBeforeExpiry": 10,
      "certifications": ["Organic"],
      "price": 1000,
      "isConsumed": false,
      "createdBy": "002",
      "stateOfProduct": "PREPARED",
      "buyerId": "",
      "humidiy": []
  }
          
        

Note, Instant Coffee can only be made by using coffee beans, so it must be made through a transformation function. More on that below.






6) Submit Transactions

Now that we have created the participants and the asset, we can proceed to testing out the transactions for our example. Start by clicking the Submit Transaction button at the bottom of the left sidebar. You should see 4 transaction types in the dropdown.

  1. Dispatch Product
  2. Send Reading
  3. Receive Product
  4. Create Finished Product

Do note, you will not see the Send Reading transaction unless you have defined a delivery condition for asset one. The very first transaction will be DispatchProduct transaction to send the harvested beans to the processor. Lets dispatch coffee bean consignment cb001 to the Processor. The following JSON is the transaction data for DispatchProduct. "trackingId": "cb001" is the id that is used to track this very lot of beans till the end and buyer and seller Ids are respective participant Ids

            
  {
    "$class": "com.algorythmix.base.DispatchProduct",
    "trackingId": "cb001",
    "buyerId": "002",
    "sellerId": "001",
  }
            
          

Once you click Submit, notice the stateOfProduct of coffee bean cb001 has been changed to DISPATCHED.

While the beans are in transit we monitor and record the relative humidity level. This is accomplished by the Send Reading transaction. In a real world scenario there can be IoT sensors recording and sending data as needed. We will send one reading and see how it works in our example.

Goto Submit transaction and this time select SendReading transaction. This transaction send the relative humidity value captured via a device / sensor with deviceId d1 along with the timestamp and tags it to the trackingId of our coffee beans cb001 in transit. This sendReading transaction may be called several times till the beans are in transit. If the humidity goes outside the band defined, it is flagged and all parties are immediately notificed of it.

            
  {
    "$class": "com.algorythmix.base.SendReading",
    "trackingId": "cb001",
    "deviceId": "d1",
    "value": 11
  }
            
          

Once the beans are received at the processors facility, the processor has to be confirm the receipt of the beans. For that we have the ReceiveProduct transaction.

            
  {
    "$class": "com.algorythmix.base.ReceiveProduct",
    "trackingId": "cb001",
    "buyerId": "002",
    "action": "ACCEPTED"
  }
            
          

Once this transaction is executed, check that our CoffeBeans cb001 stateOfProducthas changed from DISPATCHED to RECEIVED

Now that our processor have received the beans, he can make the Instant Coffee for the coming season. The trackingId in this case will be the new trackingid for the batch of Instant coffee being made using the beans in cb001. This ensures that the output is tagged to the right input. Goto Submit transaction and select CreateFinishedProduct.

            
  {
    "$class": "com.algorythmix.base.CreateFinishedProduct",
     "trackingId": "ic001",
     "name": "Instant coffee",
     "daysBeforeExpiry": 90,
     "certifications": [“Organic”],
     "price": 20,
     "createdBy": "002",
     "inputId": "cb001"
  }
            
          

To view the full transaction history of our business network, click All Transactions on the left. Here is a list of each transaction as they were submitted. There are some extra transactions known as 'System Transactions' and are common to all business networks, and defined in the Hyperledger Composer Runtime along with our transactions.

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