OBSOLETE: This code pattern is obsolete

This repository will not be updated. We will keep the repository available for folks interested in some of the technical details.

Read this in other languages: 中国.

Implementing Common Transactions on IBM Blockchain - Hyperledger Fabric V1

This project is focused on helping a developer to migrate from Hyperledger Fabric V.6 to V1. It shows how to perform traditional data store transactions on IBM Blockchain. This surfaces as a web-based, to-do list application, allowing browse, read, edit, add, and delete (BREAD) operations.

The to-do list application presented here is designed to help developers understand how common transactions needed by business processes can be adapted to use Blockchain. Blockchain != Bitcoin. It might be said that Bitcoin is the first Blockchain application. As a distributed ledger, the distinct characteristics such as decentralization, consensus, and encryption have broad-reaching implications to many business verticals including finance, transportation, health care, and others.

Application Communication Workflow

• User will interact with the Todos client application, in their browser.
• When the user performs any action, the client application calls the server application API where the registered admin interacts with the Hyperledger Blockchain Network.
• Reading or writing the ledger is known as a proposal. This proposal is built by Todos Server (via the SDK) and then sent to a blockchain peer.
• The peer will communicate to its Todos chaincode container. The chaincode will run/simulate the transaction. If there are no issues it will endorse the transaction and send it back to our Todos application.
• Todos (via the SDK) will then send the endorsed proposal to the ordering service. The orderer will package many proposals from the whole network into a block. Then it will broadcast the new block to peers in the network.
• Finally the peer will validate the block and write it to its ledger. The transaction has now taken effect and any subsequent reads will reflect this change.

Prerequisite

• Go - most recent version
• Docker - v1.13 or higher
• Docker Compose - v1.8 or higher
• Node.js & npm - node v6.2.0 - v6.10.0 (v7+ not supported); npm comes with your node installation.
• nvm - if you want to use the nvm install command to retrieve a node version

Steps

1. Download the docker images and get the code for hyperledger fabric V1 node sdk
2. Edit the configuration
3. Start your network
4. Use the Node SDK
5. Run the todo list fabric server
6. Run the todo list fabric client
7. Using the todo list application

1. Download the docker images and get the code for hyperledger fabric V1 node sdk

download-dockerimages.sh contains the code for downloading the docker images required to setup the network for running Hyperledger Fabric V1.

From your workspace, make the shell script an executable:

chmod +x download-dockerimages.sh

Now run the script. Make sure you have docker running before executing this script. This process will take a few minutes so be patient:

./download-dockerimages.sh

Once the script has completed, you should see the following in your terminal:

===> List out hyperledger docker images
hyperledger/fabric-ca          latest               35311d8617b4        3 weeks ago         240 MB
hyperledger/fabric-ca          x86_64-1.0.0-alpha   35311d8617b4        3 weeks ago         240 MB
hyperledger/fabric-couchdb     latest               f3ce31e25872        3 weeks ago         1.51 GB
hyperledger/fabric-couchdb     x86_64-1.0.0-alpha   f3ce31e25872        3 weeks ago         1.51 GB
hyperledger/fabric-kafka       latest               589dad0b93fc        3 weeks ago         1.3 GB
hyperledger/fabric-kafka       x86_64-1.0.0-alpha   589dad0b93fc        3 weeks ago         1.3 GB
hyperledger/fabric-zookeeper   latest               9a51f5be29c1        3 weeks ago         1.31 GB
hyperledger/fabric-zookeeper   x86_64-1.0.0-alpha   9a51f5be29c1        3 weeks ago         1.31 GB
hyperledger/fabric-orderer     latest               5685fd77ab7c        3 weeks ago         182 MB
hyperledger/fabric-orderer     x86_64-1.0.0-alpha   5685fd77ab7c        3 weeks ago         182 MB
hyperledger/fabric-peer        latest               784c5d41ac1d        3 weeks ago         184 MB
hyperledger/fabric-peer        x86_64-1.0.0-alpha   784c5d41ac1d        3 weeks ago         184 MB
hyperledger/fabric-javaenv     latest               a08f85d8f0a9        3 weeks ago         1.42 GB
hyperledger/fabric-javaenv     x86_64-1.0.0-alpha   a08f85d8f0a9        3 weeks ago         1.42 GB
hyperledger/fabric-ccenv       latest               91792014b61f        3 weeks ago         1.29 GB
hyperledger/fabric-ccenv       x86_64-1.0.0-alpha   91792014b61f        3 weeks ago         1.29 GB

Clone the repo for fabric node sdk:

git clone https://github.com/hyperledger/fabric-sdk-node.git

First, checkout the alpha branch of the fabric-sdk-node repository:

cd fabric-sdk-node
git checkout v1.0.0-alpha

Ensure that you are on the correct branch:

git branch

You should see the following:

Ishans-MacBook-Pro:fabric-sdk-node ishan$ git branch
* (HEAD detached at v1.0.0-alpha)
  master

Now hop back to your workspace directory:

cd ..

From your workspace, move the docker-compose-networksetup.yaml to the test/fixtures folder in the fabric-sdk-node directory:

mv docker-compose-networksetup.yaml fabric-sdk-node/test/fixtures

Still from your workspace, empty the example chaincode source from the fabric-sdk-node directory:

rm -rf fabric-sdk-node/test/fixtures/src/github.com/example_cc/*

Now copy the todo list chaincode to the same folder:

cp todo-list-fabric-server/chaincode/* fabric-sdk-node/test/fixtures/src/github.com/example_cc/

Note: If you want to run your own code on hyperledger fabric V1, just copy the chaincode code in fabric-sdk-node/test/fixtures/src/github.com/example_cc directory.

2. Edit the configuration

Update the config.json and instantiate-chaincode.js files in the fabric-sdk-node directory:

cd fabric-sdk-node/test/integration/e2e

Use an editor to open the config.json and replace all instances of grpcs with grpc.

Use an editor to open instantiate-chaincode.js and replace line 147 with:

args: ['init'],

3. Start your network

docker-compose-networksetup.yaml contains the configuration to setup the network.

Navigate to the test/fixtures folder in the fabric-sdk-node directory and run the docker-compose file:

cd fabric-sdk-node/test/fixtures
docker-compose -f docker-compose-networksetup.yaml up -d

Once complete, issue a docker ps command to view your currently running containers. You should see the following:

CONTAINER ID        IMAGE                        COMMAND                  CREATED             STATUS                       PORTS                                            NAMES
e61cf829f171        hyperledger/fabric-peer      "peer node start -..."   3 minutes ago       Up 2 minutes           0.0.0.0:7056->7051/tcp, 0.0.0.0:7058->7053/tcp   peer1
0cc1f5ac24da        hyperledger/fabric-peer      "peer node start -..."   3 minutes ago       Up 2 minutes        0.0.0.0:8056->7051/tcp, 0.0.0.0:8058->7053/tcp   peer3
7ab3106e5076        hyperledger/fabric-peer      "peer node start -..."   3 minutes ago       Up 3 minutes        0.0.0.0:7051->7051/tcp, 0.0.0.0:7053->7053/tcp   peer0
2bc5c6606e6c        hyperledger/fabric-peer      "peer node start -..."   3 minutes ago       Up 3 minutes        0.0.0.0:8051->7051/tcp, 0.0.0.0:8053->7053/tcp   peer2
513be1b46467        hyperledger/fabric-ca        "sh -c 'fabric-ca-..."   3 minutes ago       Up 3 minutes        0.0.0.0:8054->7054/tcp                           ca_peerOrg2
741c363ba34a        hyperledger/fabric-orderer   "orderer"                3 minutes ago       Up 3 minutes        0.0.0.0:7050->7050/tcp                           orderer0
abaae883eb13        couchdb                      "tini -- /docker-e..."   3 minutes ago       Up 3 minutes        0.0.0.0:5984->5984/tcp                           couchdb
2c2d51fe88c0        hyperledger/fabric-ca        "sh -c 'fabric-ca-..."   3 minutes ago       Up 3 minutes        0.0.0.0:7054->7054/tcp                           ca_peerOrg1

4. Use the Node SDK

Go back to the root of the fabric-sdk-node directory and add grpc dependency "grpc": "1.1.2" to package.json

Install node modules in your SDK repo.

npm install
npm install -g gulp
# if you get a "permission denied" error, then try with sudo
sudo npm install -g gulp

Finally, build the fabric-ca client:

gulp ca

Remove the key value stores and hfc artifacts that may have cached during previous runs:

rm -rf /tmp/hfc-*
rm -rf ~/.hfc-key-store

Update the chaincode version from v0 to v1 in util.js present in test/unit

module.exports.END2END = {
	channel: 'mychannel',
	chaincodeId: 'end2end',
	chaincodeVersion: 'v1'
};

Create channel

A Hyperledger Fabric channel is a private “subnet” of communication between two or more specific network members, for the purpose of conducting private and confidential transactions. A channel is defined by members (organizations), anchor peers per member, the shared ledger, chaincode application(s) and the ordering service node(s). Each transaction on the network is executed on a channel, where each party must be authenticated and authorized to transact on that channel. Each peer that joins a channel, has its own identity given by a membership services provider (MSP), which authenticates each peer to its channel peers and services.

Now, leverage the SDK test program to create a channel named mychannel. From the fabric-sdk-node directory:

node test/integration/e2e/create-channel.js

Join channel

Pass the genesis block - mychannel.block - to the ordering service and join the peers to your channel:

node test/integration/e2e/join-channel.js

Install chaincode

Install the todo list source code on the peer's filesystems:

node test/integration/e2e/install-chaincode.js

Instantiate chaincode

Spin up the todo list containers:

node test/integration/e2e/instantiate-chaincode.js

5. Run the todo list fabric server

Navigate to the root of the todo-list-fabric-server directory.

Install node modules in your fabric server repo.

npm install

Run the server:

node server.js

Issue a get request to /enrollAdmin endpoint, to the Enroll the admin on chaincode:

You should see the following response:

{
  "message": "Admin Enrolled! "
}

6. Run the todo list fabric client

In a new terminal, navigate to the root of the todo-list-fabric-client/web directory.

In order for the web-based to-do list application to work, it must be run from a web server. This server does not need to be publicly available in order for the application to function.

On Mac, a common approach is to use the built-in PHP installation to run an in-place web server. Run the PHP web server:

php -S localhost:8081

On windows, you can use XAMPP

7. Using the todo list application

Use the link http://localhost:8081 to load the web application in browser. You will be presented with a login screen. The login dialog contains an IBM logo. Alt+Click on that logo to preload data into the blockchain. The only indication that this operation has been completed is a transaction ID in the developer console.

While not extremely verbose, transaction IDs from IBM Blockchain are presented in the developer console of the browser for every change made at the blockchain itself. It may be useful to have the developer console open when you are using the to-do list application.

There are three accounts created in the default data. In the form of username:password, those accounts are ...

• krhoyt:abc123
• abtin:abc123
• peter:abc123

You can login with any of these accounts to browse, read, edit, add, and delete to-do items.

• To create a to-do list item, click on the red button labeled "+". Hovering over this button will present the additional button to create a "location".
• To edit a to-do list item, click on the item you are interested in editing and modify the fields to match your desired values. There is no "save" button as all changes are immediately committed to the blockchain.
• To delete a to-do list item, move your mouse over any item, and click on the trash can icon.
• To forward the to-do list item to another person, move your mouse over any item and click on the arrow icon that appears. A list of other users in the system will be presented. Select a name.
• To logout of the application, click the icon that is a box with an arrow inside of it. This is located in the upper-righthand corner of the screen.
• Using the above account information, log into the application again using a different account to see to-do items forwarded on to other users in the system.

Additional resources

Following is a list of additional blockchain resources:

• Fundamentals of IBM Blockchain
• Hyperledger Fabric Documentation
• Hyperledger Fabric code on GitHub
• Hyperledger Fabric Composer
• How to migrate your Fabric v0.6-based chaincode to run on the latest Fabric v1.0

Troubleshooting

• If you see a containerID already exists upon running docker-compose up, then you need to remove the existing container. This command will remove all containers; NOT your images:

docker rm -f $(docker ps -aq)

• When running create-channel.js, if you see an error stating private key not found, then try clearing your cached key value stores:

rm -rf /tmp/hfc-*
rm -rf ~/.hfc-key-store

• The developer console in the browser is your key to troubleshooting any problems that may arise while running the client application. The first place to look for errors is in checking the values of the chaincode ID and url in the "/web/script/blockchain.js" file.

References

• This example is based on to-do list application using Hyperledger Fabric V0.6 Hyperledger Fabric V0.6.

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