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 IBM Cloud Private. 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>
- 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. 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 thepeer
CLI in theapi_url
field. Leave offgrpcs://
from the beginning of the URL. - 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.