Digital Developer Conference on Data and AI: Essential data science, machine learning, and AI skills and certification Register for free

Join a Fabric peer to a channel on the IBM Blockchain Platform

This tutorial is the second in a series on how to connect nodes deployed on the IBM Blockchain Platform with other Hyperledger Fabric networks. The first tutorial provides instructions on how to join a peer on the IBM Blockchain Platform to a channel that was created using open source Hyperledger Fabric. This tutorial provides instructions on how to complete the opposite task: joining a Hyperledger Fabric peer to a channel that was created on the IBM Blockchain Platform. Organizations on the IBM Blockchain Platform can add other Hyperledger Fabric peers to their channels and allow organizations outside the platform to participate in the process of transferring assets and endorsing transactions.

Because we are going to use open source tooling to join the peer to the channel, the instructions in this tutorial can be used by organizations that have deployed their peers using open source Hyperledger Fabric or Hyperledger Fabric networks that were deployed by another cloud provider. The underlying assumption is that all nodes in the network are based on unaltered code provided by the Linux Foundation Hyperledger Fabric Project.

We are going to assume that the network on the IBM Blockchain Platform consists of an ordering service operated by a single ordering organization and a set of peer organizations that have deployed at least one channel. The peer organizations want to add an organization to the channel that has deployed their peer using open source Hyperledger Fabric.

IBM Blockchain Platform network
Note: The steps in this tutorial cover how to join the Hyperledger Fabric peer run by Org2 to a channel that was created by Org1 and the ordering service organization on the IBM Blockchain Platform.

The orderer organization and peer organizations on the IBM Blockchain Platform can use their console to add the new organization to the channel. The Hyperledger Fabric peer organization can then use the Hyperledger Fabric tools to join the channel. This tutorial demonstrates the steps that would need to be completed by each organization:

If you are running a distributed Hyperledger Fabric network, this tutorial can be used by all of the organizations that need to participate in the process, with each organization following the relevant steps. If you are using this tutorial for development and education, you can also run through each step yourself to test the process.

Considerations

Managing nodes with Hyperledger Fabric tooling is considerably more challenging than using the IBM Blockchain console. This topic is meant for experienced Hyperledger Fabric users.

Prerequisites

  • An existing IBM Blockchain Platform network that includes an ordering service and at least one application channel. If you have not deployed an IBM Blockchain Platform network and are following this tutorial for development or testing, you can complete this Build a network tutorial to create a network with a single node ordering service, a peer organization, and one channel.

  • An organization that has deployed at least one Hyperledger Fabric peer using the open source Hyperledger Fabric binaries or another cloud provider.

  • To avoid compatibility issues, we recommend that you use the same version of Hyperledger Fabric on both networks. You can use your console to find the Hyperledger Fabric version of your node on the IBM Blockchain Platform. Look in the upper-left corner of the peer node that you want to join to the Hyperledger Fabric channel:

    IBM Blockchain Platform console version

  • The Hyperledger Fabric organization has installed the Hyperledger Fabric prerequisites.

  • Install the jq tool.

  • The IBM Blockchain Platform is available in two offerings: one for IBM Cloud and a second that allows you to deploy blockchain components on open source Kubernetes, Openshift Container Platform, and IBM Cloud Private. The instructions in this tutorial work with both offerings.

Limitations

  • Support: Open source Hyperledger Fabric components are not supported by IBM even if they are connected to an IBM Blockchain Platform network. If you want to run your own Hyperledger Fabric network and get support from IBM, you need to purchase the IBM Blockchain Platform images offering.

  • Node management: A gRPC web proxy provided by the IBM Blockchain Platform is required for the console to communicate with Hyperledger Fabric nodes. Because the gRPC web proxy is not included with open source Hyperledger Fabric, you need to manage the nodes using open source Hyperledger Fabric tooling. You need to complete the following operations using Hyperledger Fabric tools instead of the console:

    • Tracking nodes and organizations: Users have to track the nodes and organizations of other members.

    • Signature management: The IBM Blockchain console collects the signatures that are required to submit a channel update request. If you are using Hyperledger Fabric, you need to understand which organizations are required by the channel policies to sign a channel update. The administrators need to coordinate the sharing and signing of the channel configuration update artifact with the administrators of the channel out of band, through email or another manual process.

In this tutorial, you use the IBM Blockchain console to add the new peer organization to the channel. However, you cannot use the console to operate a Hyperledger Fabric peer without the gRPC web proxy. The peer organization needs to use the Hyperledger Fabric tools to operate their peer.

Create the MSP JSON file

Each member of the IBM Blockchain Platform has an organization MSP definition. The MSP definition is a JSON file that contains the certificates that are used by Hyperledger Fabric nodes to identify an organization’s root of trust. The easiest way to join a channel that was created on the IBM Blockchain Platform is to create an MSP JSON file using the certificates from your Hyperledger Fabric network. The organizations on the platform can then import the file into their console and use the console to add your organization to the channel.

Hyperledger Fabric uses an MSP folder structure to define users, nodes, and organizations. Find the MSP folder that you used to create your organization channel MSP. When you examine the organization MSP using a tree command, you should see a structure similar to the following:

msp
├── admincerts
│   └── cert.pem
├── cacerts
│   └── cacert.pem
├── config.yaml
├── keystore
│   └── key.pem
├── signcerts
│   └── cert.pem
└── tlscacerts
    └── tlscacert.pem

While your MSP might not have all of these folders, the following are required to create the MSP JSON file:

  • cacerts: Contains the root certificate of your organization CA and defines your organization’s root of trust.

  • tlscacerts: Contains the root certificate of your TLS CA.

  • admincerts: If Node OUs are not enabled for your network, the admincerts folder needs to include the signing certificates of your organization administrators.

Save the following JSON file in the same directory as your MSP folder. This file is used to define your organization on the IBM Blockchain Platform.

{
    "display_name": "Org1 MSP",
    "msp_id": "<MSP ID>",
    "type": "msp",
    "admins": [
        "<admin_certs_base64>"
    ],
    "root_certs": [
        "<ca_root_base64>"
    ],
    "tls_root_certs": [
        "<tls_root_base64>"
    ],
    "fabric_node_ous": {
        "admin_ou_identifier": {
            "certificate": "<ca_root_base64>",
            "organizational_unit_identifier": "admin"
        },
        "client_ou_identifier": {
            "certificate": "<ca_root_base64>",
            "organizational_unit_identifier": "client"
        },
        "enable": true,
        "orderer_ou_identifier": {
            "certificate": "<ca_root_base64>",
            "organizational_unit_identifier": "orderer"
        },
        "peer_ou_identifier": {
            "certificate": "<ca_root_base64>",
            "organizational_unit_identifier": "peer"
        }
    },
    "host_url": "url.com"
}

Replace <MSP ID> with your organization’s MSP ID. The "host_url" field is required to import the file into the console, but the value of the field is only used for organizations on the IBM Blockchain Platform. To complete the MSP file, you need to transfer the certificates from your MSP folder into the JSON file. While the certificates consumed by Hyperledger Fabric need to be in pem format, the certificates that are uploaded to the IBM Blockchain Platform need to be encoded in base64 format.

  1. Run the following command to convert your CA root certificate into base64 format:

    export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
    cat msp/cacerts/* | base64 $FLAG
    

    Use the output of the command to replace <ca_root_base64>.

  2. Use the following command to base64 encode the root cert of your TLS CA:

     cat msp/tlscacerts/* | base64 $FLAG
    

    Use the output of the command to replace <tls_root_base64>.

  3. If you have an admincerts folder in your MSP, you can use the following command to encode your administrator certificate. You can modify this command if you have multiple organization admins:

    cat msp/admincerts/* | base64 $FLAG
    

    Use the output of the command to replace <admin_certs_base64>. If you have enabled node OUs for your network, you do not need to provide an administrator certificate to replace <admin_certs_base64>. If you do not have node OUs enabled, remove the "fabric_node_ous" section from the file.

After you have completed the organization MSP JSON file, you can send the file to the ordering service administrators and peer organizations on the IBM Blockchain Platform.

Import the Hyperledger Fabric organization MSP

You can use the organization MSP JSON file that was sent to you by the Hyperledger Fabric organization to import the new organization into the IBM Blockchain console. You should import this file into your console if you are an administrator of the ordering service or the channel.

Add the fabric organization using the Organizations tab

Log in to your console and navigate to the Organizations tab. You can then use the Import MSP definition button to import the file into your console.

Add the Hyperledger Fabric organization to consortium

In order to join channels that are created on the IBM Blockchain Platform, the Hyperledger Fabric organization needs to be added to the consortium of peer organizations hosted by the ordering service. The new organization needs to be added to the consortium by an administrator of the ordering service.

Add Org2 to the consortium

Log in to your IBM Blockchain console. Navigate to the Nodes tab and go to the overview page of your ordering service. Scroll down to the list of consortium members under the set of ordering service administrators. You can use the Add organization button to add the Hyperledger Fabric organization to the list of consortium members.

Add the Hyperledger Fabric organization to the channel

After you import the organization MSP file into your console, you can use the console to add the new organization to a channel.

Add Org2 to the channel

Log in to your console and navigate to the Channel tab. Open the channel that the new organization will be added to and click Settings under the channel name. In the Update Channel flow, use the Organizations tab to select the MSP of the Hyperledger Fabric organization and add them as a channel member. You can add the new organization as a channel reader, writer, or operator:

  • A reader can only query the channel ledger.

  • A writer can update the ledger by invoking a smart contract. A writer can also instantiate a smart contract on a channel.

  • An operator is the equivalent of being made an administrator of a Hyperledger Fabric channel. Channel operators have permission to create and sign channel updates.

You can use the Policies page to add the Hyperledger Fabric organization to the set of channel members that need to approve a channel update. Note that the channel update process used by the IBM Blockchain console is not interchangeable with open source Hyperledger Fabric tooling. As a result, the members of the channel have two options if they want to add a Hyperledger Fabric organization:

  • Make the new organization a writer or reader on the channel. Channel members can then continue to use the console to create and sign channel updates.

  • Make the Hyperledger Fabric organization a channel operator and add them to the channel update policy. If you select this option, every channel administrator, including the peer organizations on the IBM Blockchain Platform, needs to use the Hyperledger Fabric tools to create and sign a channel update. For more information on how to update a channel using Hyperledger Fabric tooling, see the Updating a Channel Configuration tutorial in the Hyperledger Fabric documentation.

If the members of your network are unfamiliar with how to use Hyperledger Fabric tools, it is recommended that you make any organizations that are not using the IBM Blockchain Platform a writer or reader of the channel and continue to use the console to make any channel updates.

Export your ordering service information

To connect to the channel, the Hyperledger Fabric organization needs the endpoint url and TLS certificate from one of the ordering service nodes. The easiest way to provide this information to the new organization is to export the ordering service JSON file from your console.

Export the ordering service from the console

Log in to your console and navigate to your ordering service from the Nodes tab. You can use the Export button under the ordering service name to download the JSON file onto your file system. You can then send this file to the new Hyperledger Fabric peer organization in an out of band operation, through email, or other ways of manually sharing the file.

Set up the Hyperledger Fabric tools

Because the Hyperledger Fabric peer does not have the gRPC web proxy used to communicate with the IBM Blockchain console, the new organization needs to use the Hyperledger Fabric tools to join the peer to the channel. If you do not already have the Hyperledger Fabric CLI binaries on your local machine, you can use these instructions to download the binaries on the machine of your choice. For simplicity, we use the environment created in this step to join your peer to the channel and set anchor peers. Organizations can also deploy the Hyperledger Fabric tools container on their cluster and follow the steps in this tutorial from inside the container.

Create a new directory to store the Hyperledger Fabric binaries. You also use this directory to store all the MSP material and the artifacts that you use to complete this tutorial. Use the following commands to create and then navigate to the new directory:

mkdir interop
cd interop

The Hyperledger Fabric documentation provides a command that you can use to download the binaries. To make life easy, we provide the command in this tutorial for you. You need to install cURL first. You can then run the following command from the interop directory:

curl -sSL https://bit.ly/2ysbOFE | bash -s -- 1.4.6 -d -s

The cURL command installs the binaries in a bin folder that is created in the interop directory. It also downloads a config directory that contains configuration files that are required to use the peer CLI.

Set the following environment variables to add the binaries in the bin folder to your path, and set the FABRIC_CFG_PATH to the configuration files:

export PATH=${PWD}/bin:${PWD}:$PATH
export FABRIC_CFG_PATH=${PWD}/config/

You can run the peer version command to confirm that the binaries have been downloaded and successfully added to your path. The command also confirms that you are using the same version as your Hyperledger Fabric network.

Usage:
  peer [command]

Available Commands:
  chaincode   Operate a chaincode: install|instantiate|invoke|package|query|signpackage|upgrade|list.
  channel     Operate a channel: create|fetch|join|list|update|signconfigtx|getinfo.
  help        Help about any command
  logging     Logging configuration: getlevel|setlevel|getlogspec|setlogspec|revertlevels.
  node        Operate a peer node: start|status|reset|rollback.
  version     Print fabric peer version.

Flags:
  -h, --help   help for peer

Use "peer [command] --help" for more information about a command.

Join your peer to the channel

After your organization has been added to an application channel on the IBM Blockchain Platform, you can use the Hyperledger Fabric tooling to join the channel with your peer. To connect with your peer using the peer CLI binaries, you need to use the MSP folder of your organization admin and the TLS certificate of your peer node. Run the following commands in the interop directory to create a new folder for the MSP folder and the TLS certificate.

mkdir admin
mkdir -p peer/tls

Move the TLS certificate of your peer node into the peer/tls folder. Move the MSP folder of your organization admin identity into the admin directory. This identity needs to have permission to fetch blocks from the ordering service and permission to interact with your peer. The MSP folder of your organization admin can be the same MSP folder that you used to create the organization MSP JSON file, but it does not need to be depending on your network setup. This folder needs to contain the private key of the administrator identity.

You also need the endpoint URL and TLS certificate of an ordering node on the IBM Blockchain Platform in order to fetch the channel configuration. Create a folder that you can use to store the orderer TLS certificate:

mkdir orderer

Change into the orderer directory. Copy the ordering service JSON file that was exported from the IBM Blockchain Platform into this folder. Rename the file orderer.json to make the file easier to work with. You can get the orderer URL and TLS certificate from the orderer file:

  1. Run the following command to decode the orderer TLS certificate from base64 format and convert it into PEM format:

    export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
    cat orderer.json | jq --raw-output '.[0].pem' | base64 --decode $FLAG > tls.pem
    
  2. You can use the following command to print an ordering node URL:

    cat orderer.json | jq --raw-output '.[0].api_url' | sed 's~grpcs*://~~g'
    

You need to use the TLS certificate that is associated with each ordering node URL. These commands retrieve the TLS certificate and URL of the first ordering node in the orderer.json file. If you have a multinode ordering service and would like to target a specific node with your command, you can update [0] in the commands above to reference another node in the file.

We now have the information that we need to join your peers to the channel. Set the following environment variables to operate the peer CLI. Navigate back to the interop folder and set the following environment variables:

export CORE_PEER_TLS_ENABLED=true
export CORE_PEER_LOCALMSPID="<IBP_MSP_ID>"
export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/peer/tls/<tls_cert>.pem
export CORE_PEER_MSPCONFIGPATH=${PWD}/admin/msp
export CORE_PEER_ADDRESS=<peer_address>
  • Replace <IBP_MSP_ID> with the MSP ID of your organization.
  • Replace <peer_address> with the URL of the peer that you will join to channel.
  • Replace <tls_cert>.pem with the name of your peer TLS certificate.

To join the channel, you need to fetch the channel genesis block from the ordering service on the IBM Blockchain Platform and then provide the block to your peer. Your peer then retrieves the other blocks in the channel from the ordering service.

You can retrieve the channel genesis block using the peer channel fetch command. Replace <orderer_address> with the value that was returned from the orderer.json file. Replace <channel_name> with the name of the application channel that you are joining. The --cafile flag needs to point to the location of the TLS certificate of the ordering node.

peer channel fetch 0 genesis.block -c <channel_name> -o <orderer_address> --tls --cafile ${PWD}/orderer/tls.pem

The command returns the channel genesis block as a file named genesis.block. You can now join your peer to the channel by passing the block to the peer channel join command.

peer channel join -b genesis.block

If you are joining multiple peers to the channel, you need to set the CORE_PEER_ADDRESS and CORE_PEER_TLS_ROOTCERT_FILE run for each peer.

Set anchor peers

After you have joined your peers to the channel, you need to select one of your peers to become an anchor peer. Anchor peers lead communication with other peers on the channel using gossip. With anchor peers, you can take advantage of important Hyperledger Fabric features such as service discovery and private data.

You need to select an anchor peer by updating the channel configuration. Because we are going to follow the steps outlined in the updating a channel configuration tutorial, we go through the steps quickly and do not provide much context. We assume that the environment variables are still set from when you joined your peer to the channel.

We use the peer channel fetch command to retrieve the most recent channel configuration. Replace <channel_name> with the name of the channel:

peer channel fetch config config_block.pb -o <orderer_address> -c <channel_name> --tls ${PWD}/orderer/tls.pem

You can then decode and copy the configuration block:

configtxlator proto_decode --input config_block.pb --type common.Block --output config_block.json
jq .data.data[0].payload.data.config config_block.json > config.json
cp config.json config_copy.json

You can use jq to add your anchor peer to the channel configuration. Replace <peer_url> and <peer_port> with the url and port of the peer that you would like to be the anchor peer. Replace <MSP_ID> with the value of your MSP ID:

jq '.channel_group.groups.Application.groups.<MSP_ID>.values += {"AnchorPeers":{"mod_policy": "Admins","value":{"anchor_peers": [{"host": "<peer_url>","port": <peer_port>}]},"version": "0"}}' config_copy.json > modified_config.json

Now that we have updated the channel configuration, we can convert both the original and modified channel configurations back into protobuf format and calculate the difference between them. Replace <channel_name> with the name of the application channel and run the following commands:

configtxlator proto_encode --input config.json --type common.Config --output config.pb
configtxlator proto_encode --input modified_config.json --type common.Config --output modified_config.pb
configtxlator compute_update --channel_id <channel_name> --original config.pb --updated modified_config.pb --output config_update.pb

The new protobuf named channel_update.pb contains the anchor peer update that we need to apply to the channel configuration. We can now create the final configuration update that we can use to update the channel:

configtxlator proto_decode --input config_update.pb --type common.ConfigUpdate --output config_update.json
echo '{"payload":{"header":{"channel_header":{"channel_id":"<channel_name>", "type":2}},"data":{"config_update":'$(cat config_update.json)'}}}' | jq . > config_update_in_envelope.json
configtxlator proto_encode --input config_update_in_envelope.json --type common.Envelope --output config_update_in_envelope.pb

You can now set the anchor peer by submitting the update to the channel. Because this update only effects your organization, the update does not need to be signed by other members of the channel. The --cafile flag needs to point to the location of the TLS certificate of the ordering node:

peer channel update -f config_update_in_envelope.pb -c <channel_name> -o <orderer_address> --tls --cafile ${PWD}/orderer/tls.pem

Next steps

After you join the application channel, you can start transacting with the organizations on the IBM Blockchain Platform. If you have not updated your applications to take advantage of service discovery, you need to get the endpoint information of the peers joined to the channel and update your connection profile. To get this information, have the peer organizations on the IBM Blockchain Platform export the peer node JSON files from their console and send it to you out of band.

While you can participate in a channel on the IBM Blockchain Platform using any Hyperledger Fabric peer, the channel update process used by the IBM Blockchain console is not interchangeable with Hyperledger Fabric tooling. As a result, if the Hyperledger Fabric organization is required to approve an update to the channel, all of the channel administrators need to use the Hyperledger Fabric tools to create and sign any updates to the channel configuration. For more information on how to update a channel using Hyperledger Fabric tooling, see the Updating a Channel Configuration tutorial in the Hyperledger Fabric documentation.

Some updates that are made to the channel configuration using open source tools might not be visible in the IBM Blockchain console.