Create-BlockchainNetwork-IBPV20

Creating a basic Blockchain network using the IBM Blockchain Platform V2.0

Welcome to the first in a series of building a Blockchain application using the IBM Blockchain Platform V2.0. Part 1 will show you how to set up your Blockchain network on the IBM Cloud. This will be the "Hello World" of Hyperledger samples using the IBM Blockchain Platform V2.0. - so beginner developers should be able to manage this. This pattern shows you how to test your network by packaging your smart contract using the IBM Blockchain Platform extension on VS Code and then deploy it onto the network. The network uses Hyperledger Fabric V1.4.

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 on the Cloud.

When you have completed this code pattern, you will understand how to:

• Package the smart contract using IBM Blockchain Platform Extension for VS Code
• Setup a Hyperledger Fabric network on IBM Blockchain Platform 2.0
• Install and instantiate smart contract package onto the IBM Blockchain Platform 2.0
• Interact with the contract and execute transactions using the SDK.

Architecture flow

1. The developer develops a smart contract using Node.js
2. Use the IBM Blockchain Platform Extension for VS Code to package the smart contract.
3. Setup and launch the IBM Blockchain Platform 2.0 service
4. The IBM Blockchain Platform 2.0 enables the creation of a network onto a IBM Kubernetes Service, enabling installation and instantiation of the smart contract on the network
5. The Node.js application uses the Fabic SDK to interact with the deployed network on IBM Blockchain Platform 2.0 and issues transactions.

Included components

• IBM Blockchain Platform 2.0 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 gcreates 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.

Featured technologies

• 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.

Prerequisites

• IBM Cloud account
• Node v8.x or greater and npm v5.x or greater
• VSCode version 1.26 or greater
• IBM Blockchain Platform Extension for VSCode

Running the application

Follow these steps to set up and run this code pattern. The steps are described in detail below.

Steps

1. Clone the repo
2. Package the smart contract
3. Create IBM Cloud services
4. Build a network
5. Deploy Blockchain-network Smart Contract on the network
6. Connect application to the network
7. Run the application

1. Clone the repo

Clone this repository in a folder your choice:

git clone https://github.com/IBM/Create-BlockchainNetwork-IBPV20

2. Package the smart contract

We will use the IBM Blockchain Platform extension on VS Code to package the smart contract.

If you have not done so already, you will need to install the IBM Blockchain Platform VSCode extension — you’ll also need to install the latest version of VSCode to do this. To see if you have the latest version go to Help -> Check for updates. If VSCode exits at this point, it likely means you don’t have the latest version. If so, update your VSCode (using the link provided earlier) and once you’re done, click on extensions in the sidebar on the left side of your screen. At the top, search the extensions marketplace for IBM Blockchain Platform and click on Install. You should see a status of “Installing” and eventually “Installed” — then click on reload.

• Open Visual Studio code and open the contract folder from Create-BlockchainNetwork repository that was cloned earlier.
  It is important that you are opening the contract folder and not the entire Create-BlockchainNetwork 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. Choose IBM Blockchain Platform: Package a Smart Contract 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 .cds file. We will use this packages smart contract later to deploy on the IBM Blockchain Platform 2.0 service.

Now, we will start setting up and configuring our Hyperledger Fabric network on the IBM Cloud.

3. Create IBM Cloud services

• Create the IBM Cloud Kubernetes Service. You can find the service in the Catalog. For this code pattern, we can use the Free cluster, and give it a name. Note, that the IBM Cloud allows one instance of a free cluster and expires after 30 days. Note: it could take 20 minutes for the Kubernetes Service setup to complete.

• Create the IBM Blockchain Platform 2.0 service on the IBM Cloud. You can find the service in the Catalog, and give 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.

4. Build a 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.

Create your organization and your entry point to your blockchain

• Create your peer organization CA

  • Click Add Certificate Authority.
  • Click IBM Cloud under Create Certificate Authority and Next.
  • Give it a Display name of Org1 CA.
  • Specify an Admin ID of admin and Admin Secret of adminpw.

• Use your CA to register identities

  • Select the Org 1 CA Certificate Authority that we created.
  • First, we will register an admin for our organization "org1". Click on the Register User button. Give an Enroll ID of org1admin, and Enroll Secret of org1adminpw. Click Next. Set the Type for this identity as client and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.
  • 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 of peer1pw. Click Next. Set the Type for this identity as peer and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.

• Create the peer organization MSP definition

  • Navigate to the Organizations tab in the left navigation and click Create MSP definition.
  • Enter the MSP Display name as Org1 MSP and an MSP ID of org1msp.
  • 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 and org1adminpw. Then, give the Identity name, Org1 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.

• Create a peer
  • On the Nodes page, click Add peer.
  • Click IBM Cloud under Create a new peer and Next.
  • Give your peer a Display name of Peer Org1.
  • On the next screen, select Org1 CA as your Certificate Authority. Then, give the Enroll ID and Enroll secret for the peer identity that you created for your peer, peer1, and peer1pw. Then, select the Administrator Certificate (from MSP), Org1 MSP, from the drop-down list and click Next.
  • Give the TLS Enroll ID, admin, and TLS Enroll secret, adminpw, the same values are the Enroll ID and Enroll secret that you gave when creating the CA. Leave the TLS CSR hostname blank.
  • The last side panel will ask you to Associate an identity and make it the admin of your peer. Select your peer admin identity Org1 Admin.
  • Review the summary and click Submit.

Create the node that orders transactions

• Create your orderer organization CA

  • Click Add Certificate Authority.
  • Click IBM Cloud under Create Certificate Authority and Next.
  • Give it a unique Display name of Orderer CA.
  • Specify an Admin ID of admin and Admin Secret of adminpw.

• Use your CA to register orderer and orderer admin identities

  • In the Nodes tab, select the Orderer CA Certificate Authority that we created.
  • First, we will register an admin for our organization. Click on the Register User button. Give an Enroll ID of ordereradmin, and Enroll Secret of ordereradminpw. Click Next. Set the Type for this identity as client and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.
  • 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 of orderer1pw. Click Next. Set the Type for this identity as peer and select from any of the affiliated organizations from the drop-down list. We will leave the Maximum enrollments and Add Attributes fields blank.

• Create the orderer organization MSP definition

  • Navigate to the Organizations tab in the left navigation and click Create MSP definition.
  • Enter the MSP Display name as Orderer MSP and an MSP ID of orderermsp.
  • 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 and ordereradminpw. Then, give the Identity name, Orderer 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.

• Create an orderer

  • On the Nodes page, click Add orderer.
  • Click IBM Cloud and proceed with Next.
  • Give your peer a Display name of Orderer.
  • On the next screen, select Orderer CA as your Certificate Authority. Then, give the Enroll ID and Enroll secret for the peer identity that you created for your orderer, orderer1, and orderer1pw. Then, select the Administrator Certificate (from MSP), Orderer MSP, from the drop-down list and click Next.
  • Give the TLS Enroll ID, admin, and TLS Enroll secret, adminpw, the same values are the Enroll ID and Enroll secret that you gave when creating the CA. Leave the TLS CSR hostname blank.
  • The last side panel will ask to Associate an identity and make it the admin of your peer. Select your peer admin identity Orderer Admin.
  • Review the summary and click Submit.

• Add organization as Consortium Member on the orderer to transact

  • 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 Org1 MSP, as this is the MSP that represents the peer's organization org1.
  • Click Submit.

Create and join channel

• Create the channel

  • Navigate to the Channels tab in the left navigation.
  • Click Create channel.
  • Give the channel a name, mychannel.
  • Select the orderer you created, Orderer from the orderers drop-down list.
  • Select the MSP identifying the organization of the channel creator from the drop-down list. This should be Org1 MSP (org1msp).
  • Associate available identity as Org1 Admin.
  • Click Add next to your organization. Make your organization an Operator.
  • Click Create.

• Join your peer to the channel

  • Click Join channel to launch the side panels.
  • Select your Orderer and click Next.
  • Enter the name of the channel you just created. mychannel and click Next.
  • Select which peers you want to join the channel, click Peer Org1 .
  • Click Submit.

5. Deploy Blockchain Network Smart Contract on the network

• Install a smart contract

  • Click the Smart contracts tab to install the smart contract.
  • Click Install smart contract to upload the Blockchain-Network smart contract package file (it is probably named [email protected]), which you packaged earlier using the Visual Studio code extension.
  • Click on Add file and find your packaged smart contract.
  • Once the contract is uploaded, click Install.

• Instantiate smart contract

  • On the smart contracts tab, find the smart contract from the list (Note: yours is called blockchain-network) installed on your peers and click Instantiate from the overflow menu on the right side of the row.
  • On the side panel that opens, select the channel, mychannel to instantiate the smart contract on. Click Next.
  • Select the organization members to be included in the policy, org1msp. Click Next.
  • Give Function name of instantiate and leave Arguments blank. Note: instantiate is the method in the my-contract.js file that initiates the smart contracts on the peer. Some may name this initLedger.
  • Click Instantiate.

6. Connect application to the network

• Connect with sdk through connection profile

  • Under the Instantiated Smart Contract, click on Connect with SDK from the overflow menu on the right side of the row.
  • Choose from the dropdown for MSP for connection, org1msp.
  • Choose from Certificate Authority dropdown, Org1 CA.
  • Download the connection profile by scrolling down and clicking Download Connection Profile. This will download the connection json which we will use soon to establish connection.
  • You can click Close once the download completes.

• Create an application admin

  • Go to the Nodes tab on the left bar, and under Certif Authorities, choose your organization CA, Org1 CA.
  • Click on Register user.
  • Give an Enroll ID and Enroll Secret to administer your application users, app-admin and app-adminpw.
  • Choose client as Type and any organization for affiliation. We can pick org1 to be consistent.
  • You can leave the Maximum enrollments blank.
  • Under Attributes, click on Add attribute. Give attribute as hf.Registrar.Roles = *. This will allow this identity to act as registrar and issues identities for our app. Click Add-attribute.
  • Click Register.

• Update application connection

  • Copy the connection profile you downloaded into application 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 and app-adminpw.
    • The orgMSP ID, which we provided as org1msp.
    • The caName, which can be found in your connection json file under "organization" -> "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 IBP.

 {
    "connection_file": "mychannel_blockchain-network_profile.json",
    "channel_name": "mychannel",
    "smart_contract_name": "blockchain-network",
    "appAdmin": "app-admin",
    "appAdminSecret": "app-adminpw",
    "orgMSPID": "org1msp",
    "caName": "169.46.208.151:30404",
    "userName": "user1",
    "gatewayDiscovery": { "enabled": true, "asLocalhost": false }
 }

7. Run the application

• Enroll admin

  • First, navigate to the application directory, and install the node dependencies.

    cd application
    npm install

  • Run the enrollAdmin.js script

    node 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 invoke-transactions.js script to execute the transactions on the smart contract

    node invoke-transactions.js

  • You should see the following in the terminal:

    Wallet path: /Users/laurabennett/2019/patterns/Create-BlockchainNetwork-IBPV20/application/wallet
    2019-03-05T05:17:59.823Z - error: [Client.js]: Channel not found for name mychannel
    
    Submit AddTrader transaction.
    2019-03-05T05:18:02.253Z - info: [TransactionEventHandler]: _strategySuccess: strategy success for transaction "1c63161c4b86abbe6bcc9b243635cf9c2303b5dfa4b024fa6f5aba726ab2c05e"
    
    addTraderAResponse: 
    "{\"traderId\":\"traderA\",\"firstName\":\"Carlos\",\"lastName\":\"Roca\"}"
    addTraderAResponse_JSON.parse: {"traderId":"traderA","firstName":"Carlos","lastName":"Roca"}
    
    Submit AddTrader transaction.
    2019-03-05T05:18:03.488Z - info: [TransactionEventHandler]: _strategySuccess: strategy success for transaction "d64ffa66c6461265474095606020bebcf0077d8be9ee4e6a4791313d6dea6fa1"
    
    addTraderBResponse: 
    "{\"traderId\":\"traderB\",\"firstName\":\"Lisa\",\"lastName\":\"Smith\"}"
    addTraderBResponse_JSON.parse: {"traderId":"traderB","firstName":"Lisa","lastName":"Smith"}
    
    Submit AddCommodity transaction.  
    2019-03-05T05:18:04.724Z - info: [TransactionEventHandler]: _strategySuccess: strategy success for transaction "e2af5bf3a93355927a7a3afc72443228cfdd2efcc499de36a37cb73cb689581a"
    
    addCommodityResponse: 
    "{\"tradingSymbol\":\"commodityA\",\"description\":\"farm-commodity\",\"traderId\":\"traderA\"}" 
    addCommodityResponse_JSON.parse: {"tradingSymbol":"commodityA","description":"farm-commodity","traderId":"traderA"}
    
    Submit Commodity trade transaction.
    2019-03-05T05:18:05.964Z - info: [TransactionEventHandler]: _strategySuccess: strategy success for transaction "9146776c552bb4374920a2e511d8b4d2fb243e3938560f4aa87ceb8480a84a8e"
    
    commodityTradeResponse: 
    "{\"description\":\"farm-commodity\",\"traderId\":\"traderB\",\"tradingSymbol\":\"commodityA\"}"
    commodityTradeResponse_JSON.parse: {"description":"farm-commodity","traderId":"traderB","tradingSymbol":"commodityA"}
    

Troubleshooting

• If you receive the following error on submitting transaction: error: [Client.js]: Channel not found for name mychannel

  It is safe to ignore this error because the ibp2.0 beta has service discovery enabled. (In order to use service discovery to find other peers please define anchor peers for your channel in the ui). If you really want the message to go away you can add the channels section to the connection profile, but it is a warning rather than a true error telling the user the channel is found but not in the connection profile

  As an example you can manually add the following json and updated the IP address and ports manually:

  "channels": {
          "mychannel": {
              "orderers": [
                  "169.46.208.151:32078"
              ],
              "peers": {
                  "169.46.208.151:31017": {}
              }
          }
      },
  

Extending the code pattern

This application can be expanded in a couple of ways:

• Create a wallet for every member and use the member's wallet to interact with the application.
• Add a UI application in place of the invoke.js node application to execute the transactions.

Links

• Hyperledger Fabric Docs
• Zero to Blockchain
• IBM Code Patterns for Blockchain

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