Developer Tutorial for creating a Hyperledger Composer solution
This tutorial will walk you through building a Hyperledger Composer blockchain solution from scratch. In the space of a few hours you will be able to go from an idea for a disruptive blockchain innovation, to executing transactions against a real Hyperledger Fabric blockchain network and generating/running a sample Angular 2 application that interacts with a blockchain network.
This tutorial gives an overview of the techniques and resources available to apply to your own use case.
Note: This tutorial was written against the latest Hyperledger Composer build on Ubuntu Linux running with Hyperledger Fabric v1.0 where referenced below and also tested for a Mac environment.
Prerequisites
Before beginning this tutorial:
- Set up your development environment
- Install an editor e.g. VSCode or Atom
Step One: Creating a business network structure
The key concept for is the business network definition (BND). It defines the data model, transaction logic and access control rules for your blockchain solution. To create a BND, we need to create a suitable project structure on disk.
The easiest way to get started is to use the Yeoman generator to create a skeleton business network. This will create a directory containing all of the components of a business network.
Create a skeleton business network using Yeoman. This command will require a business network name, description, author name, author email address, license selection and namespace.
yo hyperledger-composer:businessnetwork
Enter
tutorial-network
for the network name, and desired information for description, author name, and author email.Select
Apache-2.0
as the license.Select
org.acme.biznet
as the namespace.
Step Two: Defining a business network
A business network is made up of assets, participants, transactions, access control rules, and optionally events and queries. In the skeleton business network created in the previous steps, there is a model (.cto
) file which will contain the class definitions for all assets, participants, and transactions in the business network. The skeleton business network also contains an access control (permissions.acl
) document with basic access control rules, a script (logic.js
) file containing transaction processor functions, and a package.json
file containing business network metadata.
Modelling assets, participants, and transactions
The first document to update is the model (.cto
) file. This file is written using the Hyperledger Composer Modelling Language. The model file contains the definitions of each class of asset, transaction, participant, and event. It implicitly extends the Hyperledger Composer System Model described in the modelling language documentation.
Open the
org.acme.biznet.cto
model file.Replace the contents with the following:
/** * My commodity trading network */ namespace org.acme.biznet 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 }
Save your changes to
org.acme.biznet.cto
.
Adding JavaScript transaction logic
In the model file, a Trade
transaction was defined, specifying a relationship to an asset, and a participant. The transaction processor function file contains the JavaScript logic to execute the transactions defined in the model file.
The Trade
transaction is intended to simply accept the identifier of the Commodity
asset which is being traded, and the identifier of the Trader
participant to set as the new owner.
Open the
logic.js
script file.Replace the contents with the following:
/** * Track the trade of a commodity from one trader to another * @param {org.acme.biznet.Trade} trade - the trade to be processed * @transaction */ function tradeCommodity(trade) { trade.commodity.owner = trade.newOwner; return getAssetRegistry('org.acme.biznet.Commodity') .then(function (assetRegistry) { return assetRegistry.update(trade.commodity); }); }
Save your changes to
logic.js
.
Adding access control
Create a
permissions.acl
file in thetutorial-network
directory.Add the following access control rules to
permissions.acl
:/** * Access control rules for tutorial-network */ rule Default { description: "Allow all participants access to all resources" participant: "ANY" operation: ALL resource: "org.acme.biznet.*" action: ALLOW } rule SystemACL { description: "System ACL to permit all access" participant: "ANY" operation: ALL resource: "org.hyperledger.composer.system.**" action: ALLOW }
Save your changes to
permissions.acl
.
Step Three: Generate a business network archive
Now that the business network has been defined, it must be packaged into a deployable business network archive (.bna
) file.
Using the command line, navigate to the
tutorial-network
directory.From the
tutorial-network
directory, run the following command:composer archive create -t dir -n .
After the command has run, a business network archive file called tutorial-network@0.0.1.bna
has been created in the tutorial-network
directory.
Step Four: Deploying the business network
After creating the .bna
file, the business network can be deployed to the instance of Hyperledger Fabric. Normally, information from the Fabric administrator is required to create a PeerAdmin
identity, with privileges to deploy chaincode to the peer. However, as part of the development environment installation, a PeerAdmin
identity has been created already.
After the runtime has been installed, a business network can be deployed to the peer. For best practice, a new identity should be created to administrate the business network after deployment. This identity is referred to as a network admin.
Retrieving the correct credentials
A PeerAdmin
business network card with the correct credentials is already created as part of development environment installation.
Deploying the business network
Deploying a business network to the Hyperledger Fabric requires the Hyperledger Composer chaincode to be installed on the peer, then the business network archive (.bna
) must be sent to the peer, and a new participant, identity, and associated card must be created to be the network administrator. Finally, the network administrator business network card must be imported for use, and the network can then be pinged to check it is responding.
To install the composer runtime, run the following command:
composer runtime install --card PeerAdmin@hlfv1 --businessNetworkName tutorial-network
The
composer runtime install
command requires a PeerAdmin business network card (in this case one has been created and imported in advance), and the name of the business network.To deploy the business network, from the
tutorial-network
directory, run the following command:composer network start --card PeerAdmin@hlfv1 --networkAdmin admin --networkAdminEnrollSecret adminpw --archiveFile tutorial-network@0.0.1.bna --file networkadmin.card
The
composer network start
command requires a business network card, as well as the name of the admin identity for the business network, the file path of the.bna
and the name of the file to be created ready to import as a business network card.To import the network administrator identity as a usable business network card, run the following command:
composer card import --file networkadmin.card
The
composer card import
command requires the filename specified incomposer network start
to create a card.To check that the business network has been deployed successfully, run the following command to ping the network:
composer network ping --card admin@tutorial-network
The composer network ping
command requires a business network card to identify the network to ping.
Step Five: Generating a REST server
Hyperledger Composer can generate a bespoke REST API based on a business network. For developing a web application, the REST API provides a useful layer of language-neutral abstraction.
To create the REST API, navigate to the
tutorial-network
directory and run the following command:composer-rest-server
Enter
admin@tutorial-network
as the card name.Select never use namespaces when asked whether to use namespaces in the generated API.
Select No when asked whether to secure the generated API.
Select Yes when asked whether to enable event publication.
Select No when asked whether to enable TLS security.
The generated API is connected to the deployed blockchain and business network.