DISCLAIMER:
As of August 2018, IBM will not be contributing new features to Hyperledger Composer and will only be maintaining it through Fabric 2.x releases. IBM recommends using Hyperledger Composer solely for demos and proof-of-concepts. IBM does not provide support for networks using Hyperledger Composer in production (this includes the CLI, JavaScript APIs, REST server, and Web Playground).
This pattern has been upgraded to Fabric V2.0
Read this in other languages: 한국어, 日本.
BlockchainNetwork-CompositeJourney
Build Your First Network (BYFN)
Welcome to the first in a series of building a Blockchain application. Part 1 will show you how to create a Hyperledger Composer Business Network Archive (BNA) file for Commodity trade and deploy it on a Hyperledger Fabric. This will be the "Hello World" of Hyperledger Composer samples so beginner developers should be able to manage this. This pattern has been updated to support Hyperledger Composer V0.20.5, Hyperledger Fabric V1.2.
Hyperledger Fabric is a blockchain framework implementation and one of the Hyperledger projects hosted by The Linux Foundation. Intended as a foundation for developing applications or solutions with a modular architecture, Hyperledger Fabric allows components, such as consensus and membership services, to be plug-and-playIn
Part 2, we will explore more about creating a complex network with multiple participants and using Access Control Rules (ACL) to provide them network access permissions. In this journey, you will run Hyperledger Fabric locally.
You can use Hyperledger Composer to quickly model your current business network, containing your existing assets and the transactions related to them. Assets are tangible or intangible goods, services, or property. As part of your business network model, you define the transactions which can interact with assets. Business networks also include the participants who interact with them, each of which can be associated with a unique identity, across multiple business networks. A business network definition consists of model(.cto), script(.js) and ACL(.acl) files packaged and exported as an archive(.bna file). The archive file is then deployed to a Hyperledger Fabric network.
Included Components
- Hyperledger Fabric v1.2
- Hyperledger Composer for v20.5
- Docker v1.13
Application Workflow Diagram
- Install the Network Dependencies a) cryptogen b) configtxgen c) configtxlator d) peer
- Configure the network a) generating the network artifacts b) Starting up the network
Prerequisites
We find that Blockchain can be finicky when it comes to installing Node. We want to share this StackOverflow response - because many times the errors you see with Composer are derived in having installed either the wrong Node version or took an approach that is not supported by Composer:
- Docker - v1.13 or higher
- Docker Compose - v1.8 or higher
- NPM - v5.6.0 or higher
- nvm - v8.11.3 (use to download and set what node version you are using)
- Node.js - node v8.11.3 ** don't install in SUDO mode
- Git client - v 2.9.x or higher
- Python - 2.7.x
Steps
- Installing Hyperledger Composer Development Tools
- Starting Hyperledger Fabric
- Generate the Business Network Archive (BNA)
- Deploy the Business Network Archive using Composer Playground
- Deploy the Business Network Archive on Hyperledger Composer running locally
1. Installing Hyperledger Composer Development Tools
Note: Check your node version nvm --version . If you are not using node version 8.11 some of the composer commands won't run correctly. Switch node versions using nvm use 8.
Note: You will be installing the latest version of composer-cli (0.20.5). If you have an older versions installed, go ahead and remove it by using the command:
npm uninstall composer-cli
npm uninstall generator-hyperledger-composer
npm uninstall composer-rest-server
npm uninstall yo
- The
composer-clicontains all the command line operations for developing business networks. To installcomposer-clirun the following command:
npm install -g [email protected]
- The
generator-hyperledger-composeris a Yeoman plugin that creates bespoke (e.g. customized) applications for your business network. Yeoman is an open source client-side development stack, consisting of tools and frameworks intended to help developers build web applications. To installgenerator-hyperledger-composerrun the following command:
npm install -g [email protected]
- The
composer-rest-serveruses the Hyperledger Composer LoopBack Connector to connect to a business network, extract the models and then present a page containing the REST APIs that have been generated for the model. To installcomposer-rest-serverrun the following command:
npm install -g [email protected]
- When combining
Yeomanwith thegenerator-hyperledger-composercomponent, it can interpret business networks and generate applications based on them. To installYeomanrun the following command:
npm install -g [email protected]
2. Starting Hyperledger Fabric
** Note: **
If you have previously used an older version of Hyperledger Composer and are now setting up a new install, you may want to kill and remove all previous Docker containers, which you can do with these commands:
docker kill $(docker ps -q)
docker rm $(docker ps -aq)
docker rmi -f $(docker images -q)
First download the docker files for Fabric in preparation for creating a Composer profile. Hyperledger Composer uses Connection Profiles to connect to a runtime. A Connection Profile is a JSON document that lives in the user's home directory (or may come from an environment variable) and is referenced by name when using the Composer APIs or the Command Line tools. Using connection profiles ensures that code and scripts are easily portable from one runtime instance to another.
The PeerAdmin card is a special ID card used to administer the local Hyperledger Fabric. In a development installation, such as the one on your computer, the PeerAdmin ID card is created when you install the local Hyperledger Fabric.
The form for a PeerAdmin card for a Hyperledger Fabric v1.0 network is PeerAdmin@hlfv1. In general, the PeerAdmin is a special role reserved for functions such as:
- Deploying business networks
- Creating, issuing, and revoking ID cards for business network admins*
First, clone the contents of this repo locally and cd into the project folder by running these commands:
git clone https://github.com/IBM/BlockchainNetwork-CompositeJourney
cd BlockchainNetwork-CompositeJourneyThen, start the Fabric and create a Composer profile using the following commands:
./downloadFabric.sh
./startFabric.sh
./createPeerAdminCard.shNo need to do it now; however as an fyi - you can stop and tear down Fabric using:
./stopFabric.sh
./teardownFabric.sh
3. Generate the Business Network Archive (BNA)
This business network defines:
Participant
Trader
Asset
Commodity
Transaction
Trade
Commodity is owned by a Trader, and the owner of a Commodity can be modified by submitting a Trade transaction.
The next step is to generate a Business Network Archive (BNA) file for your business network definition. The BNA file is the deployable unit -- a file that can be deployed to the Composer runtime for execution.
Use the following command to generate the network archive:
npm installYou should see the following output:
Creating Business Network Archive
Looking for package.json of Business Network Definition
Input directory: /Users/ishan/Documents/git-demo/BlockchainNetwork-CompositeJourney
Found:
Description: Sample Trade Network
Name: my-network
Identifier: [email protected]
Written Business Network Definition Archive file to
Output file: ./dist/my-network.bna
Command succeededThe composer archive create command has created a file called my-network.bna in the dist folder.
You can test the business network definition against the embedded runtime that stores the state of 'the blockchain' in-memory in a Node.js process. This embedded runtime is very useful for unit testing, as it allows you to focus on testing the business logic rather than configuring an entire Fabric.
From your project working directory (BlockchainNetwork-CompositeJourney), run the command:
npm test
You should see the following output:
> [email protected] test /Users/laurabennett/2017-NewRole/Code/BlockchainNetwork-CompositeJourney
> mocha --recursive
Commodity Trading
#tradeCommodity
✓ should be able to trade a commodity (198ms)
1 passing (1s)4. Deploy the Business Network Archive using Composer Playground
Open Composer Playground, by default the Basic Sample Network is imported.
If you have previously used Playground, be sure to clear your browser local storage by running localStorage.clear() in your browser Console.
Now import the my-network.bna file and click on deploy button. If you don't know how to import, take a tour of Composer Playground
You can also setup Composer Playground locally.
You will see the following:
To test your Business Network Definition, first click on the Test tab:
Click on the Create New Participant button
Create Trader participants:
{
"$class": "org.acme.mynetwork.Trader",
"tradeId": "traderA",
"firstName": "Tobias",
"lastName": "Funke"
}
{
"$class": "org.acme.mynetwork.Trader",
"tradeId": "traderB",
"firstName": "Simon",
"lastName": "Stone"
}
Highlight the Commodity tab on the far left hand side and
create a Commodity asset with owner as traderA:
{
"$class": "org.acme.mynetwork.Commodity",
"tradingSymbol": "commodityA",
"description": "Sample Commodity",
"mainExchange": "Dollar",
"quantity": 100,
"owner": "resource:org.acme.mynetwork.Trader#traderA"
}
Click on the Submit Transaction button on the lower left-hand side and submit a Trade transaction to change the owner of Commodity commodityA:
{
"$class": "org.acme.mynetwork.Trade",
"commodity": "resource:org.acme.mynetwork.Commodity#commodityA",
"newOwner": "resource:org.acme.mynetwork.Trader#traderB"
}
You can verify the new owner by clicking on the Commodity registry. Also you can view all the transactions by selecting the All Transactions registry.
Example of transaction view:
5. Deploy the Business Network Archive on Hyperledger Composer running locally (alternative deployment approach)
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.
Change directory to the dist folder containing my-network.bna file.
The composer network 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 install the composer runtime, run the following command:
cd dist
composer network install --card PeerAdmin@hlfv1 --archiveFile my-network.bna
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 deploy the business network, run the following command:
composer network start --networkName my-network --networkVersion 0.0.1 --networkAdmin admin --networkAdminEnrollSecret adminpw --card PeerAdmin@hlfv1 --file networkadmin.card
The composer card import command requires the filename specified in composer network start to create a card. To import the network administrator identity as a usable business network card, run the following command:
composer card import --file networkadmin.card
You can verify that the network has been deployed by typing:
composer network ping --card admin@my-network
You should see the the output as follows:
The connection to the network was successfully tested: my-network
Business network version: 0.0.1
version: 0.20.5
participant: org.hyperledger.composer.system.Identity#82c679fbcb1541eafeff1bc71edad4f2c980a0e17a5333a6a611124c2addf4ba
Command succeeded
To integrate with the deployed business network (creating assets/participants and submitting transactions) we can either use the Composer Node SDK or we can generate a REST API. To create the REST API we need to launch the composer-rest-server and tell it how to connect to our deployed business network. Now launch the server by changing directory to the project working directory and type:
cd ..
composer-rest-serverAnswer the questions posed at startup. These allow the composer-rest-server to connect to Hyperledger Fabric and configure how the REST API is generated.
- Enter
admin@my-networkas the card name. - Select
never use namespaceswhen asked whether to use namespaces in the generated API. - Select
Nowhen asked whether to secure the generated API. - Select
Nowhen asked whether to enable authentication with Passport. - Select
Nowhen asked if you want to enable the explorer test interface. - Select
Nowhen asked if you want to enable dynamic logging. - Select
Yeswhen asked whether to enable event publication. - Select
Nowhen asked whether to enable TLS security.
If the composer-rest-server started successfully you should see these output lines:
Discovering types from business network definition ...
Discovered types from business network definition
Generating schemas for all types in business network definition ...
Generated schemas for all types in business network definition
Adding schemas for all types to Loopback ...
Added schemas for all types to Loopback
Web server listening at: http://localhost:3000
Browse your REST API at http://localhost:3000/explorer
Open a web browser and navigate to http://localhost:3000/explorer
You should see the LoopBack API Explorer, allowing you to inspect and test the generated REST API. Follow the instructions to test Business Network Definition as mentioned above in the composer section.
Ready to move to Step 2!
Congratulations - you have completed Step 1 of this Composite Journey - move onto Step 2.
Additional Resources
License
This code pattern is licensed under the Apache Software License, Version 2. Separate third party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.