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.
- 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.
- 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.
- xcode - only required for OS X users
- nvm - if you want to use the nvm install command to retrieve a node version
- Download the docker images and get the code for hyperledger fabric V1 node sdk
- Edit the configuration
- Start your network
- Use the Node SDK
- Run the todo list fabric server
- Run the todo list fabric client
- Using the todo list application
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.shNow 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.shOnce 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 GBClone the repo for fabric node sdk:
git clone https://github.com/hyperledger/fabric-sdk-node.gitFirst, checkout the alpha branch of the fabric-sdk-node repository:
cd fabric-sdk-node
git checkout v1.0.0-alphaEnsure that you are on the correct branch:
git branchYou should see the following:
Ishans-MacBook-Pro:fabric-sdk-node ishan$ git branch
* (HEAD detached at v1.0.0-alpha)
masterNow 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/fixturesStill 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.
Update the config.json and instantiate-chaincode.js files in the fabric-sdk-node directory:
cd fabric-sdk-node/test/integration/e2eUse 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'],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 -dOnce 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
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 gulpFinally, build the fabric-ca client:
gulp caRemove the key value stores and hfc artifacts that may have cached during previous runs:
rm -rf /tmp/hfc-*
rm -rf ~/.hfc-key-storeUpdate the chaincode version from v0 to v1 in util.js present in test/unit
module.exports.END2END = {
channel: 'mychannel',
chaincodeId: 'end2end',
chaincodeVersion: 'v1'
};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.jsPass the genesis block - mychannel.block - to the ordering service and join the peers to your channel:
node test/integration/e2e/join-channel.jsInstall the todo list source code on the peer's filesystems:
node test/integration/e2e/install-chaincode.jsSpin up the todo list containers:
node test/integration/e2e/instantiate-chaincode.jsNavigate to the root of the todo-list-fabric-server directory.
Install node modules in your fabric server repo.
npm installRun the server:
node server.jsIssue a get request to /enrollAdmin endpoint, to the Enroll the admin on chaincode:
You should see the following response:
{
"message": "Admin Enrolled! "
}
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:8081On windows, you can use XAMPP
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.
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
- If you see a
containerID already existsupon 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 statingprivate 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.
- This example is based on to-do list application using Hyperledger Fabric V0.6 Hyperledger Fabric V0.6.