Exploring Hyperledger Composer (Part 3): A primer to Playground

In a previous article we explored the concept of a business network and how it is mapped to modelling technologies used by Hyperledger Composer. Now it is time to apply our knowledge to build our first business network! To do that, we will leverage Composer Playground, an easy-to-use interface for rapid prototyping of ideas. Basically, Composer Playground will allow us to simulate the entire blockchain network within the browser by providing a sandbox environment to define, test and explore business networks. Once we complete the prototyping process, we can then deploy a ready Business Network Archive (a .bna file, to be precise) onto an existing Hyperledger Fabric instance. We will deal with that case later on but first, let's focus on Playground and what advantages it brings to us. The good news is that it is available online and does not need any prerequisites. Simply type https://composer-playground.mybluemix.net/ in your browser and enjoy the ride!

Exploring Hyperledger Composer Playground

Open Composer Playground in your browser: https://composer-playground-next.mybluemix.net/ If this is your first time to open Playground in this browser, you should see the following page:

You may now start by clicking "Let's blockchain" button and Composer will take you to the Playground interface.

If you already played around with this tool, there might occur a situation that you receive the following error:

In this situation, it is enough that you clik on the "Clear local storage" button.

The next step is to deploy a new business network.

In the deployment wizard, we define properties, such as a name, and an optional description. You can also choose to base a new business network on an existing template, or import your own template.

The new business network needs a name, let's call it artwork-network.

We will also import an existing template by using empty-business-network from the list.

Now that our network is defined, click Deploy.

As the connection is ready, we are now ready to connect to our business network:

The main Composer interface will become available. Let's take a short look at it now.

• On the top left corner there is a list of files used to form a business model : a model file (.cto), a business logic file (.js) and an access control file (.acl).
• On the bottom left there are three buttons: "Add a file" to add a new model file, "Export" to export the business model to the Business Network Archive (.bna) and "Deploy Changes", used whenever we made changes to the business network by editing any of files mentioned above.
• In the centre we see the window in which all edition actions will take place.
• On the top, there are two tabs "Define" to edit the business model and "Test" to test it.
• On the top right corner there is a drop-down list to switch between different users and profiles within Composer Playground.

Deployment of a sample network

We now have an empty business network that we can test against our scenario. Before we do that, you may want to try out a short "hello world" developer tutorial from Hyperledger Composer community or we can go through it together as per instructions below. You do not have focus too much on the code itself as we will be going through that part of the process together later on. Remember to keep your deployed business network for our scenario and deploy a separate network for that tutorial. Have fun!

Creating a new business network

Firstly, we want to create a new business network from scratch. A business network has a couple of defining properties; a name, and an optional description. You can also choose to base a new business network on an existing template, or import your own template.

1.    Click Deploy a new business network under the Web Browser heading to get started.

2.    The new business network needs a name, let's call it tutorial-network.

3.    Optionally, you can enter a description for your business network.

4.    Next we must select a business network to base ours on, because we want to build the network from scratch, click empty-business-network.

5.    Now that our network is defined, click Deploy.

Connecting to the business network

Now that we've created and deployed the business network, you should see a new business network card called admin for our business network tutorial-network in your wallet. The wallet can contain business network cards to connect to multiple deployed business networks.

To connect to our business network click Connect now under our business network card.

Adding a model file

As you can see, we're in the Define tab right now, this tab is where you create and edit the files that make up a business network definition, before deploying them and testing them using the Test tab.

As we selected an empty business network template, we need to modify the template files provided. The first step is to update the model file. Model files define the assets, participants, transactions, and events in our business network.

1.    Click the Model file to view it.

2.    Delete the lines of code in the model file and replace it with this:

Copy

/**
 * My commodity trading network
 */
namespace org.example.mynetwork
asset Commodity identified by tradingSymbol {
    o String tradingSymbol
    o String description
    o String mainExchange
    o Double quantity
    --> Trader owner
}
participant Trader identified by tradeId {
    o String tradeId
    o String firstName
    o String lastName
}
transaction Trade {
    --> Commodity commodity
    --> Trader newOwner
}

Adding a transaction processor script file

Now that the domain model has been defined, we can define the transaction logic for the business network. Composer expresses the logic for a business network using JavaScript functions. These functions are automatically executed when a transaction is submitted for processing.

1.    Click the Add a file button.

2.    Click the Script file and click Add.

3.    Delete the lines of code in the script file and replace it with the following code:

Copy

/**
 * Track the trade of a commodity from one trader to another
 * @param {org.example.mynetwork.Trade} trade - the trade to be processed
 * @transaction
 */
async function tradeCommodity(trade) {
    trade.commodity.owner = trade.newOwner;
    let assetRegistry = await getAssetRegistry('org.example.mynetwork.Commodity');
    await assetRegistry.update(trade.commodity);
}

Testing the business network definition

Next, we need to test our business network by creating some participants (in this case Traders), creating an asset (a Commodity), and then using our Trade transaction to change the ownership of the Commodity. Before doing that, it is necessary to click on “Deploy Changes” button which will deploy our test scenario to the sandbox network.

Then, click the Test tab to get started.

Creating participants

The first thing we should add to our business network is two participants.

1.    Ensure that you have the Trader tab selected on the left, and click Create New Participant in the upper right.

2.    What you can see is the data structure of a Trader participant. We want some easily recognizable data, so delete the code that's there and paste the following:

Copy

{
  "$class": "org.example.mynetwork.Trader",
  "tradeId": "TRADER1",
  "firstName": "Jenny",
  "lastName": "Jones"
}
 

3.    Click Create New to create the participant.

4.    You should be able to see the new Trader participant you've created.

5.    We need another Trader to test our Trade transaction though, so create another Trader, but this time, use the following data:

Copy

{
  "$class": "org.example.mynetwork.Trader",
  "tradeId": "TRADER2",
  "firstName": "Amy",
  "lastName": "Williams"
}

Make sure that both participants exist in the Trader view before moving on!

Creating an asset

Now that we have two Trader participants, we need something for them to trade. Creating an asset is like creating a participant. The Commodity we're creating will have an owner property indicating that it belongs to the Trader with the tradeId of TRADER1.

1.    Click the Commodity tab under Assets and click Create New Asset.

2.    Delete the asset data and replace it with the following:

Copy

{
  "$class": "org.example.mynetwork.Commodity",
  "tradingSymbol": "ABC",
  "description": "Test commodity",
  "mainExchange": "Euronext",
  "quantity": 72.297,
  "owner": "resource:org.example.mynetwork.Trader#TRADER1"
}
 

3.    After creating this asset, you should be able to see it in the Commodity tab.

Transferring the commodity between the participants

Now that we have two Traders and a Commodity to trade between them, we can test our Trade transaction.

Transactions are the basis of all change in a Hyperledger Composer business network, if you want to experiment with your own after this tutorial, try creating another business network from the My Business Network screen and using a more advanced business network template.

To test the Trade transaction:

1.    Click the Submit Transaction button on the left.

2.    Ensure that the transaction type is Trade.

3.    Replace the transaction data with the following, or just change the details:

Copy

{
  "$class": "org.example.mynetwork.Trade",
  "commodity": "resource:org.example.mynetwork.Commodity#ABC",
  "newOwner": "resource:org.example.mynetwork.Trader#TRADER2"
}
 
 

4.    Click Submit.

5.    Check that our asset has changed ownership from TRADER1 to TRADER2, by expanding the data section for the asset. You should see that the owner is listed as resource:org.example.mynetwork.Trader#TRADER2.

6.    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. You can see that certain actions we performed using the UI, like creating the Trader participants and the Commodity asset, are recorded as transactions, even though they're not defined as transactions in our business network model. These transactions are known as 'System Transactions' and are common to all business networks, and defined in the Hyperledger Composer Runtime.

Conclusion

We now understand how to use Hyperledger Composer Playground and we got some practical experience in functionalities embedded in this tool. The next step is to prepare for a real-time scenario which we will be jointly developing together. See you there!