NOTE: This developer pattern creates a blockchain network on IBM Blockchain Platform version 2.5 using the Hyperledger Fabric version 1.4.
In this code pattern, we will be extending the global-financing-blockchain code pattern by deploying the smart contract on a Hyperledger Fabric Network created on IBM Blockchain Platform instead of a local instance of the Hyperledger Fabric. This use case is inspired by the RedBook tutorial by Bob Dill and uses the same application interface. It employs a Node.js smart contract and a Node.js web application.
The Global Finance use case involves various members such as the Buyer, Seller, Provider, Shipper and Finance Company which perform many actions. Some of these actions are:
- Buyer creates the order.
- Seller contacts a provider for the items in the order.
- Provider provides the items in the order.
- Shipper delivers the items in the order.
- Finance company processes payments to the seller.
The number of participants in this use case, as well as the different types of transactions that can be executed show how this is the perfect use case to demonstrate dispute resolution using the smart contracts and distributed ledgers provided by Blockchain. Blockchain also enables faster settlement of such disputes as opposed to the traditional approaches employed for such a use case.
We will start by packaging the Node.js smart contract using the IBM Blockchain Platform Extension for VS Code. Next, we will create a Hyperledger Fabric Network on IBM Blockchain Platform where we will install and instantiate the smart contract. Finally, the Node.js web application, which makes use of the Hyperledger Fabric SDK, can be used to interact with the network.
When you have completed this code pattern, you will understand how to:
- Package a blockchain smart contract using the IBM Blockchain Platform Extension for VS Code.
- Set up a Hyperledger Fabric network on IBM Blockchain Platform.
- Install and instantiate a smart contract package through IBM Blockchain Platform.
- Test the blockchain network by executing a Node.js application with the Hyperledger Fabric SDK to interact with the deployed network by issuing transactions.
- The Blockchain Operator clones the GitHub repo to obtain the Global Finance on Blockchain smart contract.
- The Blockchain Operator uses the IBM Blockchain Platform Extension for VS Code to package the smart contract.
- The Blockchain Operator sets up and launches the IBM Blockchain Platform service.
- The IBM Blockchain Platform enables the creation of a Hyperledger Fabric network onto a IBM Cloud Kubernetes Service, enabling installation and instantiation of the Global Finance on Blockchain smart contract on the network.
- The Users (Buyers, Sellers, Providers, Shippers and Finance Companies) use the Node.js application which in turn uses the Fabric SDK to interact with the deployed network on IBM Blockchain Platform and issue transactions.
- IBM Blockchain Platform gives you total control of your blockchain network with a user interface that can simplify and accelerate your journey to deploy and manage blockchain components on the IBM Cloud Kubernetes Service.
- IBM Cloud Kubernetes Service creates a cluster of compute hosts and deploys highly available containers. A Kubernetes cluster lets you securely manage the resources that you need to quickly deploy, update, and scale applications.
- IBM Blockchain Platform Extension for VS Code is designed to assist users in developing, testing, and deploying smart contracts - including connecting to Hyperledger Fabric environments.
- Node.js is an open source, cross-platform JavaScript run-time environment that executes server-side JavaScript code.
- Bootstrap is an open source toolkit for developing with HTML, CSS, and JavaScript.
- IBM Cloud account
- Node v8.x or v10.x and npm v6.x or greater
- VSCode version 1.38.0 or greater
- IBM Blockchain Platform Extension for VSCode
Note: Click on the image below to view the video on YouTube. For Google Chrome, press the Ctrl key + the left mouse button and say Open link
.
Note: Click on the image below to view the video on YouTube. For Google Chrome, press the Ctrl key + the left mouse button and say Open link
.
Follow these steps to set up and run this code pattern. The steps are described in detail below.
- Clone the repo
- Package the smart contract
- Create IBM Cloud services
- Build a network
- Deploy Global Finance Smart Contract on the network
- Connect application to the network
- Run the application
Clone this repository in a folder your choice:
git clone https://github.com/IBM/Global-Finance-on-Blockchain.git
We will use the IBM Blockchain Platform extension on VS Code to package the smart contract.
-
Open Visual Studio code and open the
contract
folder fromGlobal-Finance-on-Blockchain
repository that was cloned earlier. It is important that you are opening thecontract
folder and not the entireGlobal-Finance-on-Blockchain
directory; otherwise you will see an error that states that it doesn't understand what programming language you are using. -
Press the
F1
key to see the different VS code options. ChooseIBM Blockchain Platform: Package Open Project
.
- Click the
IBM Blockchain Platform
extension button on the left. This will show the packaged contracts on top and the blockchain connections on the bottom.
-
Next, right click on the packaged contract (in this case, select [email protected]) to export it and choose
Export Package
. -
Choose a location on your machine and save the
.cds
file. We will use this packaged smart contract later to deploy on the IBM Blockchain Platform service.
Now, we will start setting up the different services required for configuring our Hyperledger Fabric network on the IBM Cloud and for running our application using this network.
- Create the IBM Cloud Kubernetes Service. You can find the service in the
Catalog
. For this code pattern, we can use theFree
cluster, and give it a name. Note, that the IBM Cloud allows one instance of a free cluster which expires after 30 days. Note: it could take 20 minutes for the Kubernetes Service setup to complete.
- Create the IBM Blockchain Platform service on the IBM Cloud. You can find the service in the
Catalog
, and give it a name.
- After your kubernetes cluster is up and running, you can deploy your IBM Blockchain Platform on the cluster. Again - wait for the Kubernetes service to indicate it was deployed. The IBM Blockchain Platform service walks through few steps and finds your cluster on the IBM Cloud to deploy the service on.
- Once the Blockchain Platform is deployed on the Kubernetes cluster, you can launch the console to start configuring your blockchain network.
We will build a network as provided by the IBM Blockchain Platform documentation. This will include creating a channel with a single peer organization with its own MSP and CA (Certificate Authority), and an orderer organization with its own MSP and CA. We will create the respective identities to deploy peers and operate nodes.
- Navigate to the Nodes tab in the left navigation and click Add Certificate Authority +.
- Click Create a Certificate Authority + and click Next.
- Give it a CA display name of
Org1 CA
, a CA administrator enroll ID ofadmin
and a CA administrator enroll secret ofadminpw
, then click Next. - Review the summary and click Add Certificate Authority.
- In the Nodes tab, select the Org1 CA once it is running (indicated by the green box in the tile).
- Click Associate identity on the CA overview panel.
- On the side panel, select the Enroll ID tab.
- Provide an Enroll ID of
admin
and an Enroll secret ofadminpw
. Use the default value ofOrg1 CA Admin
for the Identity display name. - Click Associate identity to associate the
admin
identity with the Org1 CA.
- Select the Org1 CA Certificate Authority and ensure the
admin
identity that was created for the CA is visible in the table. - The next step is to register an admin for the organization "Org1". Click on the Register User + button. Give an Enroll ID of
org1admin
and an Enroll secret oforg1adminpw
. Set the Type for this identity asadmin
. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next. - Skip the section to add attributes to this user and click Register user.
- Repeat the process to create an identity of the peer. Click on the Register User + button. Give an Enroll ID of
peer1
and an Enroll secret ofpeer1pw
. Set the Type for this identity aspeer
. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next. - Skip the section to add attributes to this user and click Register user.
- Navigate to the Organizations tab in the left navigation and click Create MSP definition +.
- Enter the MSP display name as
Org1MSP
and the MSP ID asOrg1MSP
. Click Next. - Specify
Org1 CA
as the Root Certificate Authority. Click Next. - Select the New identity tab. Give the Enroll ID and Enroll secret for your organization admin, i.e.
org1admin
andorg1adminpw
respectively. Then, give the Identity name asOrg1 Admin
. - Click the Generate button to enroll this identity as the admin of your organization and add the identity to the wallet. Click Export to export the admin certificates to your file system. Click Next.
- Review all the information and click Create MSP definition.
- Navigate to the Nodes tab in the left navigation and click Add peer +.
- Click Create a peer + and then click Next.
- Give the Peer display name as
Peer Org1
and click Next. - On the next screen, select
Org1 CA
as the Certificate Authority. Then, give the Peer enroll ID and Peer enroll secret aspeer1
andpeer1pw
respectively. Select the Organization MSP asOrg1MSP
. Leave the TLS CSR hostname blank and select the highest value available in the drop-down for Fabric version, i.e.2.1.1-0
. Click Next. - Provide
Org1 Admin
as the Peer administrator identity and click Next. - Review the summary and click Add peer.
- Navigate to the Nodes tab in the left navigation and click Add Certificate Authority +.
- Click Create a Certificate Authority + and click Next.
- Give it a CA display name of
Orderer CA
, a CA administrator enroll ID ofadmin
and a CA administrator enroll secret ofadminpw
, then click Next. - Review the summary and click Add Certificate Authority.
- In the Nodes tab, select the Orderer CA once it is running (indicated by the green box in the tile).
- Click Associate identity on the CA overview panel.
- On the side panel, select the Enroll ID tab.
- Provide an Enroll ID of
admin
and an Enroll secret ofadminpw
. Use the default value ofOrderer CA Admin
for the Identity display name. - Click Associate identity to associate the
admin
identity with the Orderer CA.
- Select the Orderer CA Certificate Authority and ensure the
admin
identity that was created for the CA is visible in the table. - The next step is to register an admin for the organization "Orderer". Click on the Register User + button. Give an Enroll ID of
ordereradmin
and an Enroll secret ofordereradminpw
. Set the Type for this identity asadmin
. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next. - Skip the section to add attributes to this user and click Register user.
- Repeat the process to create an identity of the orderer. Click on the Register User + button. Give an Enroll ID of
orderer
and an Enroll secret ofordererpw
. Set the Type for this identity asorderer
. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next. - Skip the section to add attributes to this user and click Register user.
- Navigate to the Organizations tab in the left navigation and click Create MSP definition +.
- Enter the MSP display name as
OrdererMSP
and the MSP ID asOrdererMSP
. Click Next. - Specify
Orderer CA
as the Root Certificate Authority. Click Next. - Select the New identity tab. Give the Enroll ID and Enroll secret for your organization admin, i.e.
ordereradmin
andordereradminpw
respectively. Then, give the Identity name asOrderer Admin
. - Click the Generate button to enroll this identity as the admin of your organization and add the identity to the wallet. Click Export to export the admin certificates to your file system. Click Next.
- Review all the information and click Create MSP definition.
- Navigate to the Nodes tab in the left navigation and click Add ordering service +.
- Click Create an ordering service + and then click Next.
- Give the Ordering service display name as
Orderer
and click Next. - On the next screen, select
Orderer CA
as the Certificate Authority. Then, give the Ordering service enroll ID and Ordering service enroll secret asorderer
andordererpw
respectively. Select the Organization MSP asOrdererMSP
. Leave the TLS CSR hostname blank and select the highest value available in the drop-down for Fabric version, i.e.2.1.1-0
. Click Next. - Provide
Orderer Admin
as the Orderer administrator identity and click Next. - Review the summary and click Add ordering service.
- Navigate to the Nodes tab, and click on the Orderer that was created.
- Under Consortium Members, click Add organization +.
- Select the Existing MSP ID tab. From the drop-down list, select
Org1MSP (Org1MSP)
, as this is the MSP that represents the peer's organization "Org1". - Click Add organization.
- Navigate to the Channels tab in the left navigation and click Create channel +.
- Click Next.
- Give the Channel name as
mychannel
. SelectOrderer
from the Ordering service drop-down list. Click Next. - Under Organizations, select
Org1MSP (Org1MSP)
from the drop-down list to add the organization "Org1" as a member of this channel. Click the Add button. Set the permissions for this member as Operator. Click Next. - Leave the Policy as the default value i.e.
1 out of 1
. Click Next. - Select the Channel creator MSP as
Org1MSP (Org1MSP)
and the Identity asOrg1 Admin
. Click Next. - Review the summary and click Create channel.
- Click on the newly created channel mychannel.
- In the side panel that opens, under Choose from available peers, select
Peer Org1
. Once the peer is selected, a check mark will be displayed next to it. Ensure that Make anchor peer(s) is marked asYes
. Click Join channel.
- Navigate to the Smart contracts tab in the left navigation and click Install smart contract +.
- Click on Add file.
- Browse to the location of the Global Finance smart contract package file (it is probably named
[email protected]
), which we packaged earlier using the IBM Blockchain Platform extension for Visual Studio code. - Once the contract is uploaded, click Install smart contract.
- Under Installed smart contracts, find the smart contract from the list (Note: ours is called globalfinancing) installed on our peer and click Instantiate from the overflow menu on the right side of the row.
- On the side panel that opens, select the channel,
mychannel
on which to instantiate the smart contract. Click Next. - Select
Org1MSP
as the organization member to be included in the endorsement policy. Click Next. - Skip the Setup private data collection step and simply click Next.
- Provide the Function name as
instantiate
and leave the Arguments blank. - Click Instantiate smart contract.
- Navigate to the Organizations tab in the left navigation, and click on Org1MSP.
- Click on Download Connection Profile.
- In the side panel that opens up, select
Yes
as the response for Include Org1 CA for user registration and enrollment?. Under Select peers to include, selectPeer Org1
. Then click Download connection profile. This will download the connection json which we will use to establish a connection between the Node.js web application and the Blockchain Network.
- Next, we need to obtain the information to connect to the Orderer.
- Navigate to the Organizations tab in the left navigation, and click on OrdererMSP.
- Click on the Orderer tile.
- Go to the Ordering nodes tab, then click on the Orderer_1 tile.
- Click the Export button to download the
Orderer
's details.
- Navigate to the Nodes tab in the left navigation, and under Certificate Authorities, choose Org1 CA.
- Click on the Register User + button. Give an Enroll ID of
app-admin
and an Enroll secret ofapp-adminpw
. Set the Type for this identity asclient
. Specify to Use root affiliation. Leave the Maximum enrollments field blank. Click Next. - Click on Add attribute +. Enter the attribute name as
hf.Registrar.Roles
and the attribute value as*
. Click Register user.
- Copy the
Orderer
's file you downloaded into the fabric folder. - Copy the
Org1MSP
connection profile you downloaded into the fabric folder. - Update the config.json file with:
- The connection_file, which is the name of the
Org1MSP
connection profile you downloaded. - The orderer_file, which is the name of the
Orderer
file that you download. - The enroll id and enroll secret for your app admin, which was earlier provided as
app-admin
andapp-adminpw
. - The orgMSPID, which was provided as
Org1MSP
. - The caName, which can be found in the
Org1MSP
connection json file under "organization" -> "Org1MSP" -> "certificateAuthorities". This would be like an IP address and a port. - The peerName, which can be found in the
Org1MSP
connection json file under "organization" -> "Org1MSP" -> "peers". This would be like an IP address and a port. - Ensure gateway discovery is set to
{ enabled: true, asLocalhost: false }
to connect to IBM Blockchain Platform.
- The connection_file, which is the name of the
On completing the updates as mentioned above, the contents of your config.json file should look something like this:
{
"channel_name": "mychannel",
"smart_contract_name": "globalfinancing",
"connection_file": "Org1MSP_profile.json",
"orderer_file": "Orderer_1_orderer.json",
"appAdmin": "app-admin",
"appAdminSecret": "app-adminpw",
"orgMSPID": "Org1MSP",
"caName": "184.172.229.220:31844",
"peerName": "184.172.229.220:30884",
"gatewayDiscovery": { "enabled": true, "asLocalhost": false }
}
In a new terminal, navigate to the web-app
directory:
cd Global-Finance-on-Blockchain/web-app/
npm install
Note: This creates public and private key files for the app-admin in the _idwallet folder inside the fabric folder. If a folder named "app-admin" exists in the "_idwallet" folder, then the following command will not enroll the app-admin as it already exists in the wallet. Remove the app-admin folder and then run the following command.
node enrollAdmin.js
npm start
Main page of application:
Unified member's view:
This application can be extended by:
- Creating a wallet for every member and using the member's wallet to interact with the application.
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.