Connect the IBM Blockchain Platform to Hyperledger Fabric components

Connecting IBM Blockchain Platform and Hyperledger Fabric components

Blockchain networks require many different organizations to work together, and network members often use different cloud platforms to host their data and applications. The IBM Blockchain Platform provides the ability to deploy and connect components across multiple clouds. However, organizations might want to join IBM Blockchain Platform networks from nodes that were deployed using open source Hyperledger Fabric or a different service provider. One of the core tenets of the IBM Blockchain Platform is to preserve interoperability by not modifying the core components of Hyperledger Fabric. Customers that use the IBM Blockchain Platform to deploy and operate their blockchain nodes can still connect to other Fabric networks.

This tutorial is the first in a series of topics on how to connect nodes deployed using the IBM Blockchain Platform with other networks using the tooling provided by Hyperledger Fabric. Because we are using open source tooling, you can use the instructions in this tutorial to connect the IBM Blockchain platform peers to networks that were deployed 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.

Joining a Hyperledger Fabric network from the IBM Blockchain platform

Organizations with peers deployed on the IBM Blockchain Platform can participate in channels created using other Hyperledger Fabric networks. This tutorial goes over the steps required to add a peer organization to the system channel hosted by a Hyperledger Fabric ordering service and a Hyperledger Fabric channel. After completing these steps, the peer organization on the IBM Blockchain Platform can query data and endorse transactions on an existing channel and join any new channels created on the network.

We are going to assume that the Hyperledger Fabric network consists of an ordering service operated by a single ordering organization and peers deployed by separate peer organizations. The organization on the IBM Blockchain Platform consists of an organization that has deployed peers but does not operate any ordering nodes.

The steps in this tutorial cover how to join the peer run by Org2 on the IBM Blockchain Platform to a channel that was created by Org1 and the Ordering Service Organization. Both Peer Org1 and the ordering service nodes were deployed using open source Hyperledger Fabric.

Adding the IBM Blockchain organization to the Hyperledger Fabric network requires steps from both the orderer organization and the peer organizations of the Hyperledger Fabric network. The peer organization IBM Blockchain Platform also needs to use Hyperledger Fabric tools to complete the process. This tutorial demonstrates the steps that each organization would need to complete:

• The IBM Blockchain Platform peer organization: Export your organization MSP definition from the IBM Blockchain Platform console
• All organizations: Set up the Hyperledger Fabric tools
• The Hyperledger Fabric orderer organizations: Add the new organization to the Orderer system channel
• The Hyperledger Fabric peer organizations: Add the new organization to the application channel
• The IBM Blockchain Platform peer organization: Join your peer to the channel

If you are running a distributed Hyperledger Fabric network, the tutorial can be used by all organizations 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 Hyperledger Fabric network that includes an ordering service and at least one application channel.
• A peer organization on the IBM Blockchain Platform. If you have not deployed an IBM Blockchain Platform network and are following this tutorial for development or testing, you need to complete Step one: Create a peer organization and a peer to create a CA, organization MSP definition, and a peer node.

• To avoid compatibility issues, it is recommended that you use 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:

• Hyperledger Fabric prerequisites have been installed.

• 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 private cloud. The instructions in this tutorial work with both offerings.
• The jq tool has been installed.

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 through an out-of-band process.

  • Signature management: Users would have to know where to send signature requests and sign channel updates using Hyperledger Fabric tools. Org1 and Org2 need to sign something. How do I let them know? The orderer organization needs to sign a consortium update? How does that happen? How do I know when enough signatures have been gathered so the request can be submitted? Where is this logic coded? At the application level? Somewhere else?

Export your organization MSP definition

Before your peer organization can join the Hyperledger Fabric network, you need to provide your organization MSP definition to the Hyperledger Fabric administrators in an out-of-band operation. Your MSP definition contains certificates that are used by other Hyperledger Fabric nodes to identify your organization. After you send the organization MSP used by the IBM Blockchain Platform to the Hyperledger Fabric administrators, they can use the certificates to add your organization to the channels in the network.

Log in to your IBM Blockchain console. Navigate to the Organizations tab and click on the MSP definition for your organization. Click the Export icon in the console to download your MSP definition, as shown below:

Your browser downloads a JSON file, which will look like this one:

json
{
    "display_name": "Org1 MSP",
    "msp_id": "org1msp",
    "type": "msp",
    "admins": [
        "LS0tLS1CR...LS0tLQo="
    ],
    "root_certs": [
        "LS0tL...LS0K"
    ],
    "tls_root_certs": [
        " LS0tLS1CR...LS0tLQo= "
    ],
    "fabric_node_ous": {
        "admin_ou_identifier": {
            "certificate": " LS0tL...LS0K ",
            "organizational_unit_identifier": "admin"
        },
        "client_ou_identifier": {
            "certificate": " LS0tL...LS0K ",
            "organizational_unit_identifier": "client"
        },
        "enable": true,
        "orderer_ou_identifier": {
            "certificate": " LS0tL...LS0K ",
            "organizational_unit_identifier": "orderer"
        },
        "peer_ou_identifier": {
            "certificate": " LS0tL...LS0K ",
            "organizational_unit_identifier": "peer"
        }
    },
    "host_url": "https://sw0317-ibpconsole-console.ibp20openshifttestcluster-a1-0001.us-south.containers.appdomain.cloud:443"
}

Send the organization MSP JSON file to the administrators of the Hyperledger Fabric network in an out-of-band operation. You need to send the file to at least one administrator of the ordering service and at least one peer organization admin for each channel that you join.

You also need to use your organization administrator identity to join your peer to the channel. After you download your organization MSP definition, navigate to the Wallet tab and export your organization admin identity:

The console exports a JSON identity that will look like the following file:

json
{
    "name": "Org1 MSP Admin",
    "type": "identity",
    "private_key": "LS0tLS1CR...LS0tLQ0K",
    "cert": "LS0d1CR...LS0tLQo="
}

The admin identity from your IBM Blockchain console contains a certificate and private key that you need to operate your peer. Because this file contains a private key that can operate your network, you need to keep this file in a secure place.

Set up the Hyperledger Fabric tools

All organizations in the process need to download the Hyperledger Fabric tools before they can get started. In this tutorial, we provide instructions on how to install the Hyperledger Fabric CLI binaries and operate your network from the machine of your choice. Organizations can also deploy the Hyperledger Fabric tools container on their cluster and follow the steps in this tutorial from inside the container.

If you do not already have the Hyperledger Fabric binaries on your local machine, you can use these instructions to download the binaries and add them to your CLI path. For simplicity, we assume that you use the setup created in this section for the remainder of the tutorial.

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

Add the new organization to the system channel

When you add the peer organization from the IBM Blockchain Platform to your network, you have the option of adding the new organization to the consortium of peer organizations hosted by the orderer system channel. This step is not required to join an application channel; however, joining the consortium allows the peer organization to become a channel member when new channels are created. Joining the consortium also allows the new organization to create new channels on the network using Hyperledger Fabric tools.

You can use the instructions in this section to update the orderer system channel as an administrator of the ordering service. In the previous section, you followed instructions to Set up the Hyperledger Fabric tools and navigate to the interop directory. In order to update the system channel, you need to use the MSP folder of your orderer organization admin and the TLS certificate of your orderer node. Run the following commands in the interop directory for the MSP folder and the TLS certificate:

mkdir -p organizations/ordererOrganizations/ordererOrg/admin/
mkdir -p organizations/ordererOrganizations/ordererOrg/orderer/tls

Copy the MSP folder of your orderer organization admin identity to the admin directory. Move the TLS certificate of your ordering node into the orderer/tls folder. You now have the cryptographic material that you need to update the orderer system channel.

Create an MSP folder for the new peer organization

You need to create an MSP folder for the peer organization that you want to add to the system channel. You can use the MSP definition used by the IBM Blockchain Platform to create the MSP folder used by Hyperledger Fabric. Make sure that the administrator from the new organization has sent you the MSP JSON file that they exported from their IBM Blockchain Platform console. Then, again from the interop folder, create a directory that you will use to create the MSP folder and change into that directory:

mkdir -p organizations/peerOrganizations/ibporg
cd organizations/peerOrganizations/ibporg

Copy the MSP definition from the IBM Blockchain Platform into this directory and rename the file msp.json so that it is easier to work with. Run the following commands from the ibporg directory to create the MSP folder structure:

mkdir -p msp/admincerts
mkdir -p msp/cacerts
mkdir -p msp/tlscacerts

You can now copy the certificates from the msp.json file into the MSP folder structure. Run the following commands from the ibporg directory to copy the certificates, decode them, and place them into the MSP folders:

export root_cert=$(cat msp.json | jq --raw-output '.root_certs[]')
export tls_root_cert=$(cat msp.json | jq --raw-output '.tls_root_certs[]')
export admin_certs=$(cat msp.json | jq --raw-output '.admins[]')
export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
echo $root_cert | base64 --decode $FLAG > msp/cacerts/cacert.pem
echo $tls_root_cert | base64 --decode $FLAG > msp/tlscacerts/tlscacert.pem
echo $admin_certs  | base64 --decode $FLAG > msp/admincerts/cert.pem

If your network has enabled node OUs for your admin identities, copy the following yaml file into the msp directory and name it config.yaml:

NodeOUs:
Enable: true
ClientOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: client
PeerOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: peer
AdminOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: admin
OrdererOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: orderer

When you are finished building the MSP folder, you can use a tree command to verify that the MSP folder was created correctly.

tree msp/
msp/
├── admincerts
│   └── cert.pem
├── cacerts
│   └── cacert.pem
├── config.yaml
└── tlscacerts
    └── tlscacert.pem

We can now create the channel MSP that can be used to add the organization to the channel configuration. Go back the interop directory and save the following file as configtx.yaml.

yaml
Organizations:

    - &Org1
        # DefaultOrg defines the organization which is used in the sampleconfig
        # of the fabric.git development environment
        Name: <IBP_MSP_ID>

        # ID to load the MSP definition as
        ID: <IBP_MSP_ID>

        MSPDir: organizations/peerOrganizations/ibporg/msp

        # Policies defines the set of policies at this level of the config tree
        # For organization policies, their canonical path is usually
        #   /Channel/<Application|Orderer>/<OrgName>/<PolicyName>
        Policies:
            Readers:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.admin', '<IBP_MSP_ID>.peer', '<IBP_MSP_ID>.client')"
            Writers:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.admin', '<IBP_MSP_ID>.client')"
            Admins:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.admin')"
            Endorsement:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.peer')"

Replace <IBP_MSP_ID> with the MSP ID of the peer organization on the IBM Blockchain Platform. You can find the MSP ID in the msp_id field in the MSP JSON file exported from the console.

You can now use the edited configtx.yaml and the configtxgen tool to create the channel MSP. Replace <IBP_MSP_ID> with the MSP ID of the peer organization and run the following commands from the interop directory:

export FABRIC_CFG_PATH=${PWD}
configtxgen -printOrg <IBP_MSP_ID> > ibporg.json

Fetch the system channel configuration

You can now use the peer CLI to fetch the most recent system channel configuration block and add the new organization to the channel. Set the following environment variables to operate peer CLI. Replace <OrdererMSP> with the MSP ID of your organization and <orderer_address> with the address of your ordering node.

export FABRIC_CFG_PATH=${PWD}/config/
export CORE_PEER_LOCALMSPID="<OrdererMSP>"
export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/ordererOrganizations/ordererOrg/orderer/tls/cert.pem
export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/ordererOrganizations/ordererOrg/admin/msp
export CORE_PEER_ADDRESS=<orderer_address>

You can now use the peer channel fetch command to retrieve the system channel configuration. Replace <system-channel-name> with the name of the system channel:

peer channel fetch config config_block.pb -o $CORE_PEER_ADDRESS -c <system-channel-name> --tls --cafile $CORE_PEER_TLS_ROOTCERT_FILE

If the command is successful, you should see a message of the block being received:

2017-11-07 17:17:57.383 UTC [channelCmd] readBlock -> DEBU 011 Received block: 4

The channel configuration block is named config_block.pb on your local file system.

Update the system channel configuration

We can now use the configtxlator Hyperledger Fabric CLI tool and the jq tool to add the new organization to the system channel consortium by updating the channel configuration. In this tutorial, we follow the process for updating a channel configuration that is documented in more detail in the Updating a channel configuration tutorial. However, we provide the specific command that uses the jq to add the channel MSP to the list of organizations in the consortium hosted by the system channel.

The first step is to decode the channel configuration block from the protobuf format used by Hyperledger Fabric into a JSON that can be read and edited by humans. We also strip away the unnecessary metadata from the channel configuration that is not relevant to the updates are making.

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

This command leaves us with a trimmed down JSON object — config.json — which serves as the baseline for our config update. Let’s make a copy of this file and use the copy to update the channel. We use the original channel configuration in a future step.

cp config.json config_copy.json

We can now use the jq tool to append the channel MSP of the peer organization on the IBM Blockchain platform to the consortium.

jq -s '.[0] * {"channel_group":{"groups":{"Consortiums":{"groups":{"<consortium-name>":{"groups": {"<IBP_MSP_ID>":.[1]}}}}}}}' config_copy.json ./ibporg.json > modified_config.json

Replace <IBP_MSP_ID> with the MSP ID of peer organization. Replace "<consortium-name>" with the name of your consortium. You can find the name of your consortium using the following command:

cat config.json | jq '.channel_group.groups.Consortiums.groups | keys'

The command outputs the consortium name:

[
  "SampleConsortium"
]

After this step, we have updated channel configuration in JSON format in the modified_config.json file. Now, we can convert both the original and modified channel configurations back into protobuf format and calculate the difference between them. Replace <system-channel-name> with the name of your system 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 <system-channel-name> --original config.pb --updated modified_config.pb --output system_channel_update.pb

The new protobuf named system_channel_update.pb contains the update to the system channel in protobuf that we need to apply to the channel configuration. Now, we need to add the metadata back to the channel configuration and create the new channel config block. You need to replace <system-channel-name> with the name of your system channel once again.

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

We have the final artifact we need, system_channel_update_in_envelope.pb, which we can use to update the system channel.

Sign and submit the system channel update

We can update the system channel by signing the new channel configuration block and submitting it to the ordering service. If you used the default policies provided by Hyperledger Fabric, the channel update needs to be signed by a majority of ordering service administrators. Make sure that you are operating the peer CLI as the admin of the ordering service:

env | grep CORE

The command will print the environment variables that you are using to connect to your network:

CORE_PEER_TLS_ROOTCERT_FILE=/usr/interop/organizations/ordererOrganizations/ordererOrg/orderer/tls/cert.pem
CORE_PEER_LOCALMSPID=OrdererMSP
CORE_PEER_MSPCONFIGPATH=/usr/interop/organizations/ordererOrganizations/ordererOrg/admin/msp
CORE_PEER_ADDRESS=169.55.231.137:30732

You can sign the channel update using the peer CLI:

export FABRIC_CFG_PATH=${PWD}/config/
peer channel signconfigtx -f system_channel_update_in_envelope.pb

If the channel update needs to be signed by multiple organizations, pass the signed system_channel_update_in_envelope.pb object to other administrators out of band. By out of band, we mean you need to send the object to other organizations manually (through email, for example) without using Fabric. The last organization that is required to sign the update can also use the peer channel update to submit the new channel configuration:

peer channel update -f system_channel_update_in_envelope.pb -c <system-channel-name> -o <orderer_address> --tls --cafile <orderer_tls_certificate>

Replace <orderer_address> and <orderer_tls_certificate> with the endpoint and TLS certificate of your ordering node. Replace <system-channel-name> with the name of the system channel. You will see a message in your logs similar to this one if the channel has been updated successfully:

2020-01-09 21:30:45.791 UTC [channelCmd] update -> INFO 002 Successfully submitted channel update

Add the new organization to an application channel

Peer organizations from the Hyperledger Fabric network can add the peer organization on the IBM Blockchain Platform to existing application channels. When the new organization becomes a channel member, they can access the channel ledger from their peer on the IBM Blockchain Platform and validate new transactions. If you completed the steps in the previous section, the steps for adding the peer organization to an application channel are similar to the ones required to add the organization to the system channel. You need to repeat the steps in this section for each channel that the organization will join.

To add a new member, the channel needs to be updated by a peer organization that is an administrator of the channel. Follow the instructions to Set up the Hyperledger Fabric tools and navigate to the interop directory. To update the system channel, you need to use the MSP folder of your organization admin, the TLS certificate of your peer node, and a TLS certificate of a node of your ordering service. Run the following commands in the interop directory for the MSP folder and the TLS certificates:

mkdir -p organizations/peerOrganizations/fabricPeerOrg/admin/
mkdir -p organizations/peerOrganizations/fabricPeerOrg/peer/tls
mkdir -p organizations/ordererOrganizations/ordererOrg/orderer/tls

Move the MSP folder of your organization admin identity to the admin directory. Move the TLS certificate of your peer node into the peer/tls folder. Move a TLS certificate of an ordering node into the orderer/tls folder. You now have the cryptographic material that you need to update your channel.

Create an MSP folder for the new channel member

You need to create an MSP folder for the peer organization you want to add to the channel. If you are also an administrator of the ordering service, you may have completed these steps already if you completed the steps to add the organization to the system channel. You can use the channel MSP named ibporg.json that you already created and proceed to fetch the channel configuration. You can also have the orderer admin send you channel MSP in ibporg.json out of band.

You can use the MSP definition used by the IBM Blockchain Platform to create the MSP folder used by Hyperledger Fabric. Make sure that the administrator from the new organization has sent you the MSP JSON file that they exported from their IBM Blockchain platform console. Then, create a directory that you can use to create the MSP folder and change into that directory:

mkdir -p organizations/peerOrganizations/ibporg
cd organizations/peerOrganizations/ibporg

Copy the MSP definition from the IBM Blockchain Platform into this directory and rename the file msp.json so that it is easier to work with. Run the following commands from ibporg directory to create the MSP folder structure:

mkdir -p msp/admincerts
mkdir -p msp/cacerts
mkdir -p msp/tlscacerts

You can now copy the certificates from the msp.json file into the MSP folder structure. Run the following commands from the ibporg directory to copy the certificates, decode them, and place them into the MSP folders:

export root_cert=$(cat msp.json | jq --raw-output '.root_certs[]')
export tls_root_cert=$(cat msp.json | jq --raw-output '.tls_root_certs[]')
export admin_certs=$(cat msp.json | jq --raw-output '.admins[]')
export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
echo $root_cert | base64 --decode $FLAG > msp/cacerts/cacert.pem
echo $tls_root_cert | base64 --decode $FLAG > msp/tlscacerts/tlscacert.pem
echo $admin_certs  | base64 --decode $FLAG > msp/admincerts/cert.pem

If your network has enabled node OUs for your admin identities, copy the following yaml file into the msp directory and name it config.yaml:

yaml
echo 'NodeOUs:
Enable: true
ClientOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: client
PeerOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: peer
AdminOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: admin
OrdererOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: orderer'

When you are finished building the MSP folder, you can use a tree command to verify that the MSP folder was created correctly.

tree msp/
msp/
├── admincerts
│   └── cert.pem
├── cacerts
│   └── cacert.pem
├── config.yaml
└── tlscacerts
    └── tlscacert.pem

We can now create the channel MSP that can be used to add the organization to the channel configuration. Go back to the interop directory and save the following file as configtx.yaml.

yaml
Organizations:

    - &Org1
        # DefaultOrg defines the organization which is used in the sampleconfig
        # of the fabric.git development environment
        Name: <IBP_MSP_ID>

        # ID to load the MSP definition as
        ID: <IBP_MSP_ID>

        MSPDir: organizations/peerOrganizations/ibporg/msp

        # Policies defines the set of policies at this level of the config tree
        # For organization policies, their canonical path is usually
        #   /Channel/<Application|Orderer>/<OrgName>/<PolicyName>
        Policies:
            Readers:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.admin', '<IBP_MSP_ID>.peer', '<IBP_MSP_ID>.client')"
            Writers:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.admin', '<IBP_MSP_ID>.client')"
            Admins:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.admin')"
            Endorsement:
                Type: Signature
                Rule: "OR('<IBP_MSP_ID>.peer')"

Replace <IBP_MSP_ID> with the MSP ID of the peer organization on the IBM Blockchain Platform. You can find the MSP ID in the msp_id field in the MSP JSON file exported from the console.

You can now use the edited configtx.yaml and the configtxgen tool to create the channel MSP. Replace <IBP_MSP_ID> with the MSP ID of the peer organization and run the following commands from the interop directory:

export FABRIC_CFG_PATH=${PWD}
configtxgen -printOrg <IBP_MSP_ID> > ibporg.json

Fetch the channel configuration

You can now use the peer CLI to fetch the most recent channel configuration block and add the new organization to the channel. Set the following environment variables to operate the peer CLI as your organization admin. Replace <peerOrgMSP> with the MSP ID of your organization and <peer_address> with the address of your peer. We assume that the TLS certificate is named cert.pem.

export FABRIC_CFG_PATH=${PWD}/config/
export CORE_PEER_LOCALMSPID="<peerOrgMSP>"
export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/fabricPeerOrg/peer/tls/cert.pem
export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/fabricPeerOrg/admin/msp
export CORE_PEER_ADDRESS=<peer_address>

You can now use the peer channel fetch command to retrieve the channel configuration. Replace <channel_name> with the name of the application channel.

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

If the command is successful, you should see a message of the block being received:

2017-11-07 17:17:57.383 UTC [channelCmd] readBlock -> DEBU 011 Received block: 6

The channel configuration block will be named config_block.pb on your local file system.

Update the channel configuration

We can now use the configtxlator Hyperledger Fabric CLI tool and the jq tool to make the new organization a channel member by updating the channel configuration. In this tutorial, we follow the process for updating a channel configuration that is documented in more detail in the Updating a channel configuration tutorial. However, we provide the specific command that uses the jq to add the channel MSP to the list of channel members.

The first step is to decode the channel configuration block from the protobuf format used by Hyperledger Fabric into a JSON that can be read and edited by humans. We also strip away the unnecessary metadata from the channel configuration that is not relevant to the updates we are making.

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

This command leaves us with a trimmed down JSON object — config.json — which serves as the baseline for our config update. Let’s make a copy of this file and use the copy to update the channel. We use the original channel configuration in a future step.

cp config.json config_copy.json

We can now use the jq tool to append the channel MSP of the peer organization on the IBM Blockchain platform to the consortium. Replace <IBP_MSP_ID> with the MSP ID of peer organization on the IBM Blockchain platform.

jq -s '.[0] * {"channel_group":{"groups":{"Application":{"groups": {"<IBP_MSP_ID>":.[1]}}}}}' config_copy.json ./ibporg.json > modified_config.json

We assume that your channel uses the default policies provided by Hyperledger Fabric. If you use the default policies, the new organization is automatically added as an admin and writer on the channel. If you created custom policies for the channel, you might have to update the policies to add a new organization. The new peer organization needs to be a writer on the channel in order to fetch the channel genesis block and join their peer to the channel. For more information, see Policies in Hyperledger Fabric.

After this step, we have updated channel configuration in JSON format in the modified_config.json file. We can now 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

Th new protobuf named channel_update.pb contains the update to the channel in protobuf that we need to apply to the channel configuration. We now need to add the metadata back to the channel configuration and create the new channel config block. You need to replace <channel_name> with the name of the channel once again.

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

We have the final artifact we need, config_update_in_envelope.pb, which we can use to update the channel.

Sign and submit the channel update

We can now update the channel by signing the new channel configuration block and submitting it to the ordering service. If you used the default policies provided by Hyperledger Fabric, the channel update needs to be signed by a majority of channel members. Make sure that you are operating the peer CLI as the admin of your peer org:

env | grep CORE

The command prints the core environment variables that you are using to connect with your network:

CORE_PEER_TLS_ROOTCERT_FILE=/usr/interop/organizations/peerOrganizations/fabricPeerOrg/peer/tls/cert.pem
CORE_PEER_LOCALMSPID=FabricPeerMSP
CORE_PEER_MSPCONFIGPATH=/usr/interop/organizations/peerOrganizations/fabricPeerOrg/admin/msp
CORE_PEER_ADDRESS=169.55.231.137:30420

You can sign the channel update using the peer CLI:

export FABRIC_CFG_PATH=${PWD}/config/
peer channel signconfigtx -f config_update_in_envelope.pb

If the channel update needs to be signed by multiple organizations, pass the signed config_update_in_envelope.pb object to other administrators out of band. The last organization that is required to sign the update can also use the peer channel update to submit the new channel configuration:

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

Replace <orderer_address> and <orderer_tls_certificate> with the endpoint and TLS certificate of your ordering node. Replace <channel_name> with the name of the system channel. You will see a message in your logs similar to the one below if the channel has been updated successfully:

2020-03-31 21:33:32.267 EDT [channelCmd] InitCmdFactory -> INFO 004 Endorser and orderer connections initialized
2020-03-31 21:33:32.615 EDT [channelCmd] update -> INFO 005 Successfully submitted channel update

Join your peer to the channel

After your organization has been added to an application channel, you can use the Fabric tooling to join the channel with your peer on the IBM Blockchain Platform. Even though you can manage your peer using the IBM Blockchain console, the Hyperledger Fabric ordering service does not contain the gRPC web proxy that would be required to communicate with your console. As a result, you need to join the peer to the channel using the Fabric peer CLI.

Create an MSP folder for your organization admin

You need to operate the peer CLI using your organization admin identity. This requires converting the admin identity from the JSON format used by the IBM Blockchain console into the MSP folder structure used by Hyperledger Fabric. Follow the instructions to set up the Hyperledger Fabric tools and navigate to the interop directory. Create a folder that we will use to create the MSP folder and navigate to the that directory:

mkdir -p organizations/peerOrganizations/ibporg/admin
cd organizations/peerOrganizations/ibporg/admin

Copy the MSP definition and the admin identity that you exported from your console into the admin folder. Rename the files msp.json and admin.json to make them easier to work with. Although your admin identity contains your certificate and private key, you need certificates from your MSP file to operate the peer CLI. From the admin directory, run the following commands to create the MSP folder:

mkdir -p msp/admincerts
mkdir -p msp/cacerts
mkdir -p msp/tlscacerts
mkdir -p msp/keystore
mkdir -p msp/signcerts

You can now copy the certificates and key from the msp.json and admin.json file into the MSP folder structure. Run the following commands from the admin directory to copy the certificates, decode them, and place them into the MSP folders:

export root_cert=$(cat msp.json | jq --raw-output '.root_certs[]')
export tls_root_cert=$(cat msp.json | jq --raw-output '.tls_root_certs[]')
export admin_certs=$(cat msp.json | jq --raw-output '.admins[]')
export privateKey=$(cat admin.json | jq --raw-output '.private_key')
export cert=$(cat admin.json | jq --raw-output '.cert')
export FLAG=$(if [ "$(uname -s)" == "Linux" ]; then echo "-w 0"; else echo "-b 0"; fi)
echo $root_cert | base64 --decode $FLAG > msp/cacerts/cacert.pem
echo $tls_root_cert | base64 --decode $FLAG > msp/tlscacerts/cert.pem
echo $admin_certs  | base64 --decode $FLAG > msp/admincerts/cert.pem
echo $privateKey | base64 --decode $FLAG > msp/keystore/key.pem
echo $cert | base64 --decode $FLAG > msp/signcerts/cert.pem

If your network has enabled node OUs for your admin identities, copy the following yaml file below into the msp directory and name it config.yaml:

echo 'NodeOUs:
Enable: true
ClientOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: client
PeerOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: peer
AdminOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: admin
OrdererOUIdentifier:
    Certificate: cacerts/cacert.pem
    OrganizationalUnitIdentifier: orderer'

When you are finished building the MSP folder, you can use a tree command to verify that the MSP folder was created correctly.

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

We now have the admin MSP that we can use to the 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}/organizations/peerOrganizations/ibporg/admin/msp/tlscacerts/cert.pem
export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/ibporg/admin/msp
export CORE_PEER_ADDRESS=<peer_address>

1. Replace <IBP_MSP_ID> with the MSP ID of your organization.
2. Replace <peer_address> with the URL of the peer that you will join to channel. You can find your peer endpoint information by logging into your IBM Blockchain console. Navigate to the peer in the Nodes tab and export the peer information. You can find the peer URL and port that you need to target with the peer CLI in the api_url field. Leave off grpcs:// from the beginning of the URL.
3. Because you can complete a TLS handshake using a root certificate, we will use the root TLS certificate from the organization MSP to communicate with the peer. You can also use the TLS certificate from the tls_cert field of the peer information.

To join the channel, you need to fetch the channel genesis block from the Hyperledger Fabric ordering service, and then provide the genesis block to your peer. Your peer will then retrieve the other blocks in the channel from the Hyperledger Fabric ordering service.

You can use the peer channel fetch command to retrieve the channel genesis block. Replace <channel_name> with the name of the application channel and <orderer_address> with the address of a node of the Hyperledger Fabric ordering service. The --cafile needs to point to the TLS certificate of the ordering node.

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

If successful, the command returns the 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. After your peer has joined the channel, the channel will be visible in your console.

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. Anchor peers allow you to 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. We are going to follow the steps outlined in the Updating a channel configuration tutorial to create an anchor peer for your organization. However, because the process is similar to the one for adding an organization to the channel, we will go through the steps more quickly this time. We assume that the environment variables are still set from when you joined your peer to the channel.

We need to 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 --cafile ${PWD}/organizations/ordererOrganizations/ordererOrg/orderer/tls/cert.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

Th 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 block 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 needs to point to 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}/organizations/ordererOrganizations/ordererOrg/orderer/tls/cert.pem

Next steps

After you join the application channel, you can start transacting with the other members of the Hyperledger Fabric network. You can use the IBM Blockchain console or the peer CLI to install the chaincode that is instantiated on the channel. However, you cannot use the console to instantiate or upgrade a chaincode on a channel.

You can use the console to download the connection profile that will be used by your client applications to submit transactions to the channel. You can access the connection profile from the Smart contracts tab, on the overflow menu next to chaincode that was instantiated on the Hyperledger Fabric channel. The chaincode from the Hyperledger Fabric channel is visible in the console UI. However, if service discovery is not enabled, you need to gather the node endpoint information and TLS certificate for the ordering nodes and peer nodes joined to the channel.

Summary

In this tutorial, we have described the process to connect an IBM Blockchain Platform peer to an application channel on a Hyperledger Fabric network. Using a combination of the IBP console to create a peer and the Hyperledger Fabric CLI interface to join it to the existing Hyperledger Fabric channel, we have demonstrated the steps that are required to configure the interoperability between the two blockchain networks.