BlockchainNetwork-CompositeJourney

by IBM

Part 1 in a series of patterns showing the building blocks of a Blockchain application

215 Stars 171 Forks Last release: Not found Apache License 2.0 63 Commits 0 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

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

Application Workflow

  1. Install the Network Dependencies a) cryptogen b) configtxgen c) configtxlator d) peer
  2. 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

  1. Installing Hyperledger Composer Development Tools
  2. Starting Hyperledger Fabric
  3. Generate the Business Network Archive (BNA)
  4. Deploy the Business Network Archive using Composer Playground
  5. 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-cli
    contains all the command line operations for developing business networks. To install
    composer-cli
    run the following command:
    npm install -g [email protected]
    
  • The

    generator-hyperledger-composer
    is 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 install
    generator-hyperledger-composer
    run the following command:
    npm install -g [email protected]
    
  • The

    composer-rest-server
    uses 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 install
    composer-rest-server
    run the following command:
    npm install -g [email protected]
    
  • When combining

    Yeoman
    with the
    generator-hyperledger-composer
    component, it can interpret business networks and generate applications based on them. To install
    Yeoman
    run 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 [email protected] 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-CompositeJourney

Then, start the Fabric and create a Composer profile using the following commands:

bash
./downloadFabric.sh
./startFabric.sh
./createPeerAdminCard.sh

No 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:

bash
npm install
You should see the following output: ```bash 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 succeeded ```

The

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: ```bash

[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 [email protected] --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 [email protected] --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 [email protected]

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:
bash
cd ..
composer-rest-server

Answer 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

[email protected]
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
No
when asked whether to enable authentication with Passport. * Select
No
when asked if you want to enable the explorer test interface. * Select
No
when asked if you want to enable dynamic logging. * Select
Yes
when asked whether to enable event publication. * Select
No
when 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.

Apache Software License (ASL) FAQ

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.