Hyperledger Fabric sample Fabcar on IBM Blockchain Platform
This code pattern demonstrates setting up a network on the IBM Blockchain Platform and deploying the Fabcar smart contract on the network. Next, we setup our application to interact with the network including identities to submit transactions on the smart contract. The application is setup with a Node.js server using the Fabric Node SDK to process requests to the network, and an Angular client to bring up a web interface.
When the reader has completed this code pattern, they will understand how to:
- Setup a Hyperledger Fabric network on IBM Blockchain Platform
- Install and instantiate smart contract through the IBM Blockchain Platform
- Develop a Node.js server with the Hyperledger Fabric SDK to interact with the deployed network
- Create an Angular frontend for the web app to interface with the network
- The Blockchain Operator sets up the IBM Blockchain Platform service.
- The IBM Blockchain Platform enables to create a Hyperledger Fabric network onto a IBM Cloud Kubernetes Service, allowing to install and instantiate the Fabcar smart contract on the network.
- The Node.js application server uses the Fabric SDK to interact with the deployed network on IBM Blockchain Platform and creates APIs for a web client.
- The Angular client uses the Node.js application API to interact with the network.
- The User interacts with the Fabcar Angular web interface to update and query the blockchain ledger and state.
- 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.
- Hyperledger Fabric v1.4 is a platform for distributed ledger solutions, underpinned by a modular architecture that delivers high degrees of confidentiality, resiliency, flexibility, and scalability.
- Node.js is an open source, cross-platform JavaScript run-time environment that executes server-side JavaScript code.
- Express.js is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications.
- Angular.io is a front-end framework for building web applications.
- 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
Follow these steps to set up and run this code pattern. The steps are described in detail below.
To run a local network, you can find steps here
- Clone the repo
- Package the smart contract
- Create IBM Cloud services
- Build a network
- Deploy FabCar 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/fabcar-blockchain-sample.git
cd fabcar-blockchain-sample
We will use the IBM Blockchain Platform extension on VS Code to package the Fabcar smart contract.
-
Open Visual Studio code and open the
contract
folder fromfabcar-blockchain-sample
repository that was cloned earlier. It is important that you are opening thecontract
folder and not the entirefabcar-blockchain-sample
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 fabcar@1.0.0) 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 IBM Cloud 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 IBM Cloud 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 an IBM Cloud Certificate Authority and Next.
- Give it a CA display name of
Org1 CA
and click Next. - Specify an CA Administrator Enroll ID of
admin
and 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 Enroll ID.
- Provide an Enroll ID of
admin
and an Enroll secret ofadminpw
. Use the default value ofOrg1 CA Identity
for the Identity display name. - Click Associate identity to add the identity into your wallet and 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. - We will register an admin for our organization "org1". Click on the Register User button. Give an Enroll ID of
org1admin
, and Enroll Secret oforg1adminpw
. Set the Type for this identity asclient
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. - We will not be adding any attributes to this user. Click Register user.
- We will repeat the process to create an identity of the peer. Click on the Register User button. Give an Enroll ID of
peer1
, and Enroll Secret ofpeer1pw
. Set the Type for this identity aspeer
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. Click Next. - We will not be adding any attributes to this user. 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 an MSP ID ofOrg1MSP
. - Under Root Certificate Authority details, specify the peer CA that we created
Org1 CA
as the root CA for the organization. - Give the Enroll ID and Enroll secret for your organization admin,
org1admin
andorg1adminpw
. Then, give the Identity name asOrg1 Admin
. - Click the Generate button to enroll this identity as the admin of your organization and export the identity to the wallet. Click Export to export the admin certificates to your file system. Finally click Create MSP definition.
- Navigate to the Nodes tab in the left navigation and click Add peer.
- Click Create an IBM Cloud 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 for the peer identity that you created for your peer, that is,peer1
, andpeer1pw
. Select the Organization MSP asOrg1MSP
, from the drop-down list. Leave the TLS CSR hostname blank. Click Next. - The next step is to Associate an identity with this peer to make it the admin of your peer. Select your peer admin identity
Org1 Admin
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 an IBM Cloud Certificate Authority and Next.
- Give it a CA display name of
Orderer CA
and click Next. - Specify an CA Administrator Enroll ID of
admin
and 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 Enroll ID.
- Provide an Enroll ID of
admin
and an Enroll secret ofadminpw
. Use the default value ofOrderer CA Identity
for the Identity display name. - Click Associate identity to add the identity into your wallet and 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. - We will register an admin for the "orderer" organization. Click on the Register User button. Give an Enroll ID of
ordereradmin
, and Enroll Secret ofordereradminpw
. Set the Type for this identity asclient
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. - We will not be adding any attributes to this user. Click Register user.
- We will repeat the process to create an identity of the orderer. Click on the Register User button. Give an Enroll ID of
orderer1
, and Enroll Secret oforderer1pw
. Set the Type for this identity asorderer
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. Click Next. - We will not be adding any attributes to this user. 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 an MSP ID ofOrdererMSP
. - Under Root Certificate Authority details, specify the peer CA that we created
Orderer CA
as the root CA for the organization. - Give the Enroll ID and Enroll secret for your organization admin,
ordereradmin
andordereradminpw
. Then, give the Identity name asOrderer Admin
. - Click the Generate button to enroll this identity as the admin of your organization and export the identity to the wallet. Click Export to export the admin certificates to your file system. Finally click Create MSP definition.
- Navigate to the Nodes tab in the left navigation and click Add ordering service.
- Click Create an IBM Cloud 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 for the peer identity that you created for your orderer, that is,orderer1
, andorderer1pw
. Select the Organization MSP asOrdererMSP
, from the drop-down list. Leave the TLS CSR hostname blank. Click Next. - The next step is to Associate an identity with this peer to make it the admin of your peer. Select your peer admin identity
Orderer Admin
and click Next. - Review the summary and click Add ordering service.
- Navigate to the Nodes tab, and click on the Orderer that we created.
- Under Consortium Members, click Add organization.
- From the drop-down list, select
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.
- Give the Channel name as
mychannel
. - Select the orderer you created,
Orderer
from the Ordering service drop-down list. - Under Organizations, select
Org1MSP (Org1MSP)
from the drop-down list to add the organization "Org1" as a member of this channel. Click Add button. Set the permissions for this member as Operator. - Scroll down to the Channel creator organization section and select
Org1MSP (Org1MSP)
from the dropdown as the Channel creator MSP and selectOrg1 Admin
from the dropdown under Identity. - Click Create channel.
- Click Join channel to add a peer to the channel.
- Select your
Orderer
as the Ordering service and click Next. - Enter the name of the Channel as
mychannel
and click Next. - Next we need to select which peers should be added to the channel. In our case, we just want to add the peer we created under "Org1". Select
Peer Org1
. - Click Join channel.
- Navigate to the Smart contracts tab in the left navigation and click Install smart contract.
- Browse to the location of the Blockchain for maintaining Digital Assets smart contract package file (it is probably named
fabcar@1.0.0.cds
), which we packaged earlier using the IBM Blockchain Platform extension for Visual Studio code. - Click on Add file and find your packaged smart contract.
- Once the contract is uploaded, click Install smart contract.
- Under Installed smart contracts, find the smart contract from the list (Note: ours is called fabcar) 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 the organization members to be included in the endorsement policy. In our case, we need to select
Org1MSP
. Click Next. - We can skip the Setup private data collection step and simply click Next.
- Give Function name of
initLedger
and leave Arguments blank. - Click Instantiate.
- Scroll down to the Instantiated smart contracts section and find the "fabcar" contract in the list. Click on
Connect with SDK
from the overflow menu on the right side of the row. - From the dropdown for MSP for connection choose
Org1MSP
. - From the dropdown for Certificate Authority choose
Org1 CA
. - Download the connection profile by scrolling down and clicking 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.
- You can click Close once the download completes.
- Navigate to the Nodes tab in the left navigation, and under Certificate Authorities, choose your organization CA, Org1 CA.
- Click on Register user.
- Give an Enroll ID of
app-admin
and Enroll Secret ofapp-adminpw
. Set the Type for this identity asclient
. We can specify to Use root affiliation or uncheck this field and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments field blank. Click Next. - Under Attributes, click on Add attribute. Give attribute as
hf.Registrar.Roles
=*
. This will allow this identity to act as a registrar and issue identities for our app. Click Add attribute. - Click Register user.
- Copy the connection profile you downloaded into the server folder.
- Update the config.json file with:
- The connection json file name you downloaded.
- The enroll id and enroll secret for your app admin, which we earlier provided as
app-admin
andapp-adminpw
respectively. - The orgMSP ID, which we provided as
Org1MSP
. - The caName, which can be found in your connection json file under "organizations" -> "Org1MSP" -> certificateAuthorities". This would be like an IP address and a port.
- The username you would like to register.
- Update gateway discovery to
{ enabled: true, asLocalhost: false }
to connect to IBM Blockchain Platform.
the current default contents of the config.json are to connect to a local fabric instance from VS Code.
{
"connection_file": "mychannel_fabcar_profile.json",
"appAdmin": "app-admin",
"appAdminSecret": "app-adminpw",
"orgMSPID": "Org1MSP",
"caName": "169.46.208.151:30404",
"userName": "user1",
"gatewayDiscovery": { "enabled": true, "asLocalhost": false }
}
-
First, navigate to the
web-app
directory, and install the node dependencies.cd web-app/server npm install
-
Run the
enrollAdmin.js
scriptnode enrollAdmin.js
-
You should see the following in the terminal:
msg: Successfully enrolled admin user app-admin and imported it into the wallet
-
Run the
registerUser.js
script.node registerUser.js
-
You should see the following in the terminal:
Successfully registered and enrolled admin user user1 and imported it into the wallet
-
From the
server
directory, start the server.npm start
-
In a new terminal, open the web client folder and install the dependencies.
cd web-app/client npm install
-
Start the client:
npm start
You can find the app running at http://localhost:4200/
You can go to the IBM Blockchain Platform console to monitor your users and get information on your channel including the blocks added.
-
If you encounter an error
discover error: access denied
, you need to set thegatewayDiscovery
properly in yourconfig.json
file. This is REQUIRED You must set it as follows to connect to IBP:`"gatewayDiscovery": {"enabled": true, "asLocalhost": false }`
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.