The Hyperledger Fabric first-network sample (variously called the “Build Your First Network” sample and the “e2e_cli” sample) showcases a fully scripted and end-to-end automated example of a basic blockchain use case tutorial sample. The sample provisions a Hyperledger Fabric blockchain network, deploys a smart contract (chaincode-Example02) application to the running network, and runs transactions against the deployed chaincode.

The provisioned Hyperledger Fabric blockchain network consists of two organizations, two peers per organization, and a single Solo ordering service. The network supports automatic provisioning of cryptographic material for peer and orderer organizations, automatic provisioning of channel artifacts, and channel joining by participating organizational peers.

In this tutorial, we show you how to add a third organization to an application channel with its own peers to an already running Hyperledger Fabric blockchain network, and join it to the channel.

Introducing the configtxlator tool

The configtxlator tool provides a true stateless REST API, independent of the SDK, to simplify configuration tasks in Hyperledger Fabric blockchain networks. The tool converts easily between different equivalent data representations/formats. For example, in one mode of tool operation, the tool performs conversions between the binary protobuf format to a human-readable JSON textual format, and vice-versa. Additionally, the tool can compute configuration updates based on the differences between two different sets of configurations transactions.

Setting up your environment

For command-line configuration updates, make sure you have at least the Version 1.1.0-preview of Hyperledger Fabric installed. (This version introduces the peer channel signconfigtx command for collection of multiple signatures before submitting configuration updates. It also includes bug fixes in the configtxlator tool not available in v1.0.4.) Other options available are collecting signatures manually or letting the client application collect required signatures programmatically using NodeSDK support.

Verify that you are using the peer binary for your platform of choice at the V1.1.0 release level as shown in Figure 1.

Figure 1. Verifying the version number of the peer platform binary executable
alt

This tutorial uses the open source jq tool to script interactions with the JSON returned by configtxlator. These JSON manipulations may also be performed manually or with other JSON tools. Install the jq tool into the container using the following commands on an Ubuntu platform, as shown in Figure 2.


apt‑get ‑y ‑qq update && 
apt‑get install ‑y ‑qq curl && 
apt‑get clean
curl ‑o /usr/local/bin/jq https://stedolan.github.io/jq/download/linux64/jq && 
chmod +x /usr/local/bin/jq

Figure 2. Installation and verification of jq tool
alt

Start the configtxlator tool in the background, and verify that the tool has started correctly to receive incoming client requests, as shown in Figure 3.

           
configtxlator start &

Figure 3. Successful starting and verification of configtxlator tool inside container
alt

The general steps for adding a third organization, which we’ll cover in this tutorial, are:

  1. Retrieve the current configuration.
  2. Decode the configuration into a human-readable version of JSON configuration using configtxlator.
  3. Extract the config section.
  4. Create the new configuration by performing automated or manual edits on the extracted config section.
  5. Encode both updated and original configurations using configtxlator.
  6. Send them to configtxlator to compute the config update delta, which represents the changes to the config.
  7. Decode the config update and wrap it up into a config update envelope.
  8. Create the new config transaction.
  9. Update the channel by submitting the new signed config transaction.
1

Retrieve the current configuration

Execute the following command to retrieve the current configuration block on the application channel named mychannel. Because the orderer end point is secured by TLS, provide the root certificate authority identity as a parameter.


peer channel fetch config config_block.pb ‑o orderer.example.com:7050 ‑c mychannel ‑‑tls ‑‑cafile
./crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com‑cert.pem

Figure 4 shows the successful fetching and verification of the channel configuration block for application channel mychannel. The file command on the fetched binary configuration data block shows that, as expected, config_block.pb contains a binary protobuf message.

Figure 4. Fetching and verification of channel configuration for application channel – client view
alt

Figure 5 shows the successful fetching of the channel configuration for application channel mychannel from the orderer (server) side view of the console log.

Figure 5. Fetching and verification of channel configuration for application channel – server view
alt
2

Decode the configuration into a human-readable version of JSON configuration using configtxlator

Decode the binary protobuf channel configuration block information into human-readable, textual JSON format using the configtxlator tool. Verify the decoded content of the JSON file for successful decoding using the file command, as shown in Figure 6.


curl ‑X POST ‑‑data‑binary @config_block.pb http://127.0.0.1:7059/protolator/decode/common.Block > config_block.json

Figure 6. Decoding of the fetched channel configuration block for the application channel
alt
3

Extract the config section

Extract the config section of data’s payload data section from the decoded channel configuration block for application channel mychannel, and verify the correct and successful extraction, as shown in Figures 7 and 8.


jq .data.data[0].payload.data.config config_block.json > config.json

Figure 7. Decoding of fetched channel configuration block for application channel
alt
Figure 8. Verification of artifacts created for channel configuration block of application channel
alt
4

Create the new configuration by editing the extracted config section

Modify the channel configuration of application channel mychannel. In particular, add Org3MSP, as shown in Figure 9.

Figure 9. Modified channel configuration for the application channel mychannel – Org3MSP added
alt
5

Encode both the original and modified configurations using configtxlator

Encode the original channel configuration of the application channel mychannel into protobuf using the tool, and verify the correct encoding, as shown in Figure 10.


curl ‑X POST ‑‑data‑binary @config.json http://127.0.0.1:7059/protolator/encode/common.Config > config.pb

Figure 10. Encoding the original channel configuration block for the application channel mychannel
alt

Encode the modified channel configuration of the application channel mychannel into protobuf using the tool, and verify the correct encoding, as shown in Figure 11.


curl ‑X POST ‑‑data‑binary @updated_config.json http://127.0.0.1:7059/protolator/encode/common.Config > updated_config.pb

Figure 11. Encoding the modified channel configuration block for the application channel mychannel
alt
6

Send them to configtxlator to compute the config update delta

Compute the configuration update, which transitions between the original and modified channel configurations for the application channel mychannel using the tool, by executing the following command. Verify that the computed configuration update is correct, as shown in Figure 12.


curl ‑X POST ‑F original=@config.pb ‑F updated=@updated_config.pb http://127.0.0.1:7059/configtxlator/compute/update‑from‑configs ‑F
                channel=mychannel > config_update.pb

Figure 12. Compute changes to the channel configuration for the application channel mychannel
alt
7

Decode the config update and wrap it up into a config update envelope

Decode the configuration update into JSON format, and verify the decoding operation, as shown in Figure 13.


curl ‑X POST ‑‑data‑binary @config_update.pb
http://127.0.0.1:7059/protolator/decode/common.ConfigUpdate > config_update.json

Figure 13. Decode computed changes to channel configuration for application channel
alt

Create an envelope for the configuration update message in JSON format, and verify the successful envelope creation step, as shown in Figure 14.


echo '{"payload":{"header":{"channel_header":{"channel_id":"mychannel",
                "type":2}},"data":{"config_update":'$(cat config_update.json)'}}}' >
                config_update_as_envelope.json

Figure 14. Create an envelope for configuration update block message in JSON format
alt
8

Create the new config transaction

Encode a configuration update message into a protobuf format, and verify that the encoding operation is successful, as shown in Figure 15.


curl ‑X POST ‑‑data‑binary @config_update_as_envelope.json
                http://127.0.0.1:7059/protolator/encode/common.Envelope >
                config_update_as_envelope.pb

Figure 15. Encode and verify configuration update message into protobuf format
alt

Set the environment to be Org1MSP with an admin privileged user in preparation for signing the configuration update transaction, as shown in Figure 16.


CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt
CORE_PEER_TLS_KEY_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.key
CORE_PEER_LOCALMSPID=Org1MSP
CORE_PEER_TLS_CERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/server.crt
CORE_PEER_TLS_ENABLED=true
CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

Figure 16. Set the environment in preparation for signing the configuration update transaction – Org1MSP/Admin
alt
9

Update the channel by submitting the new signed config transaction

Execute the following command to sign the configuration update transaction. See Figures 17 and 18 for successful execution of the command from the client (CLI container) side and server (orderer) side. This command adds a signature to the transaction in place on the filesystem.


peer channel signconfigtx ‑f config_update_as_envelope.pb ‑o
                orderer.example.com:7050 ‑‑tls ‑‑cafile
                ./crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com‑cert.pem

Figure 17. Successful execution of channel configuration transaction signing command – client view
alt
Figure 18. Successful execution of channel configuration transaction signing command – server view
alt

Set the environment to be Org2MSP with an admin privileged user in preparation for signing and submitting the update transaction, as shown in Figure 19.


CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt
CORE_PEER_TLS_KEY_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/server.key
CORE_PEER_LOCALMSPID=Org2MSP
CORE_PEER_TLS_CERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/server.crt
CORE_PEER_TLS_ENABLED=true
CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp

Figure 19. Set the environment in preparation for submitting the configuration update transaction – Org2MSP/Admin
alt

Execute the following command to submit the configuration update transaction. The update command automatically adds the user’s signature to the configuration update before submitting it to the orderer (so signconfigtx is not needed a second time). See Figures 20 and 21 for the successful execution of the command from the client (CLI container) side and server (orderer) side.

peer channel update ‑f config_update_as_envelope.pb ‑o
                orderer.example.com:7050 ‑c mychannel ‑‑tls ‑‑cafile
                ./crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com‑cert.pem

Figure 20. Successful execution of the channel configuration transaction submit command – client view
alt

Execute the following command to fetch the updated current configuration. See Figures 21 and 22 for the successful execution of the command from the client side and server side.


peer channel fetch config config_block_Org3MSP.pb ‑o
                orderer.example.com:7050 ‑c mychannel ‑‑tls ‑‑cafile
                ./crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com‑cert.pem

Figure 21. Successful execution of the updated current channel configuration – client view
alt
Figure 22. Successful execution of the updated current channel configuration – server view
alt

Execute the following command to decode the successfully updated current channel configuration, and verify correct operation, as shown in Figure 23.


curl ‑X POST ‑‑data‑binary @config_block_Org3MSP.pb
                http://127.0.0.1:7059/protolator/decode/common.Block >
                config_block_Org3MSP.json

Figure 23. Decoding and verification of updated current channel configuration
alt

Figure 24 shows the verification of correctness of all artifacts generated by the configtxlator tool for the end-to-end process.

Figure 24. Verification and validation of configtxlator tool generated artifacts in end-to-end process
alt

Run the following command to determine the location of container logs. Review them to make sure everything worked correctly in your configuration update process steps, as shown in Figure 25.


docker inspect ‑‑format='{{.LogPath}}' orderer.example.com

Figure 25. Container log files for review and validation
alt

Conclusion

Congratulations! You have successfully used the encoding and decoding features of the configtxlator tool to add a third organization with its own peers to the application channel of an already running Hyperledger Fabric blockchain network. You have verified and validated the successful addition of this new organization to your channel configuration.

Acknowledgments

The authors gratefully thank IBM Blockchain development and research professionals Gari Singh, Bobbie Cochrane, and Yacov Manevich for their thoughtful input.

The authors gratefully acknowledge and appreciate the outstanding teaming that facilitated writing this tutorial from our current/recent customer/partner engagement team consisting of management and technical professionals, notably Balaji Balaraman, Harish Naik, Andras Ferenczi, Dallas Gale, Nilesh Jadhav, Alejandro Vences, and Jai Kiran.

The authors also thank their reviewers and managers for constructive feedback and encouragement.