Update Aug 29th 2019: Hyperledger Composer has been deprecated. Please see the README for more information.

Deploying to a multi-organization Hyperledger Fabric

Deploying a Hyperledger Composer blockchain business network to Hyperledger Fabric (multiple organizations)

This tutorial provides an insight into the process for configuring a blockchain network, spanning multiple organizations.

It outlines the steps you need configure a Hyperledger Fabric based multi-organisation blockchain network. The two-organisation blockchain network is based on a sample network provided by Hyperledger Fabric. Furthermore, it describes the steps to generate the necessary security artifacts and secure the network in either organization.

Once the blockchain network is configured, we show how to deploy a business network (eg. a Commodity trading business network from our sample networks), which runs in its own chaincode container and which is instantiated on the ledger shared across both organizations. We then show interactions with the shared ledger as different participants / identities, as generated by an Identity provider in each organization.

It is recommended that you first follow the accompanying singie organization tutorial first ; this tutorial demonstrates how to deploy a blockchain network to an instance of Hyperledger Fabric for a single organization, and will explain some of the concepts in more detail.

The Hyperledger Fabric blockchain network (for two organizations) in this tutorial is configured using docker containers, with both organizations' fabric networks, on the same machine - obviously, in the real world, they'll be in separate IP networks or domains, or secure Cloud environments.

The tutorial has colour-coded steps for convenience, to indicate 'which organization' should follow a particular step or sequence - or indeed, if steps are needed for both Orgs.

The first kind of step is for both organizations to follow:

Example Step: A step for Org1 and Org2 to follow

The organization Org1 is represented by Alice, the Green Conga Block:

Example Step: A step for Org1 to follow

The organization Org2 is represented by Bob, the Violet Conga Block:

Example Step: A step for Org2 to follow

You can follow these steps by yourself, or pair with a friend or colleague and follow the steps together.

Let's get started!

Prerequisites

If you have previously installed the Composer development environment, you will need to first tear down the Hyperledger Fabric containers provided by the development environment:

cd ~/fabric-dev-servers
export FABRIC_VERSION=hlfv12
./stopFabric.sh
./teardownFabric.sh

Next, clone the following GitHub Fabric Samples repository using the command line (IMPORTANT: DO NOT USE the samples from the Fabric site: as it is missing some changes that are required for this tutorial)

git clone https://github.com/mahoney1/fabric-samples.git

We are using the Building Your First Network Fabric sample network for this multi-org tutorial. We will refer to this Hyperledger Fabric network as the 'BYFN' (Building Your First Network) network henceforth. If you choose to split your organisations across separate physical machines or separate virtual machines running on different IP networks, it is outside the scope of this particular tutorial.

Step One: Starting a Hyperledger Fabric network

In order to follow this tutorial, you must start up a fresh Hyperledger Fabric network. This tutorial will assume that you use the Hyperledger Fabric network provided in the Hyperledger Fabric Building Your First Network tutorial.

  1. change directory to fabric-samples

    cd fabric-samples

  2. Download the platform binaries, including cryptogen using this command (three parameters needed for the bash command):

    curl -sSL http://bit.ly/2ysbOFE | bash -s 1.2.1 1.2.1 0.4.10

    Verify the list of docker images downloaded without issues.

    (Please note that you can ignore the initial "error: pathspec v1.x.x did not match" message in the output - you may not even see this message)

  3. We need to use the 'multi-org' branch from the Git repo we cloned earlier (to work with current Fabric level):

    git checkout multi-org

  4. change directory into first-network sample

    cd first-network

  5. Next, start the BYFN network - additional flags (to the byfn.sh script below) must be specified, as we're using CouchDB as the world state database (different to that specified on the Fabric BYFN page) - we also want to start a Certificate Authority (CA) for each organization.

  6. Execute the following commands in sequence from the first-network directory:

    ./byfn.sh -m generate

./byfn.sh -m up -s couchdb -a

If the command works successfully, the first command will generate Fabric network / security artifacts(see this link. Following the second command (above), the BYFN network is started, and verify that you see the following output before proceeding:

========= All GOOD, BYFN execution completed ===========


_____   _   _   ____
| ____| | \ | | |  _ \
|  _|   |  \| | | | | |
| |___  | |\  | | |_| |
|_____| |_| \_| |____/

Next, delete any 'old' business network cards that may exist in your wallet from previous Fabric environments. It is safe to ignore any errors that state that the business network cards cannot be found:

composer card delete -c PeerAdmin@byfn-network-org1
composer card delete -c PeerAdmin@byfn-network-org2
composer card delete -c alice@trade-network
composer card delete -c bob@trade-network
composer card delete -c admin@trade-network
composer card delete -c PeerAdmin@fabric-network

However any other types of failure could indicate you have cards in the card store which are from an older version of Hyperledger Composer and you will then have to delete your file system card store in your HOME directory as follows:

rm -fr $HOME/.composer

Step Two: Exploring the Hyperledger Fabric network

This step will explore the BFYN network configuration and components. The configuration details are required to complete the subsequent steps.

Organizations

The BYFN network is made up of two organizations: Org1 and Org2. The organization Org1 uses the domain name org1.example.com. The Membership Services Provider (MSP) for Org1 is called Org1MSP. The organization Org2 uses the domain name org2.example.com. The MSP for Org2 is called Org2MSP. In this tutorial, you will deploy a blockchain business network that both of the organizations Org1 and Org2 can interact with.

Network components

The Hyperledger Fabric network is made up of several components:

  • Two peer nodes for Org1, named peer0.org1.example.com and peer1.org1.example.com.
    • The request port for peer0 is 7051.
    • The event hub port for peer0 is 7053.
    • The request port for peer1 is 8051.
    • The event hub port for peer1 is 8053.
  • A single CA (Certificate Authority) for Org1, named ca.org1.example.com.
    • The CA port is 7054.
  • Two peer nodes for Org2, named peer0.org2.example.com and peer1.org2.example.com.
    • The request port for peer0 is 9051.
    • The event hub port for peer0 is 9053.
    • The request port for peer1 is 10051.
    • The event hub port for peer1 is 10053.
  • A single CA (Certificate Authority) for Org2, named ca.org2.example.com.
    • The CA port is 8054.
  • A single orderer node, named orderer.example.com.
    • The orderer port is 7050.

These components are running inside Docker containers. When running Hyperledger Composer within a Docker container, the names above (for example, peer0.org1.example.com) can be used to interact with the Hyperledger Fabric network.

This tutorial will run Hyperledger Composer commands on the Docker host machine, rather than from inside the Docker network. This means that the Hyperledger Composer commands must interact with the Hyperledger Fabric network using localhost as the host name and the exposed container ports.

All of the network components are secured using TLS to encrypt communications. You will need the Certificate Authority (CA) certificates for all of the network components in order to connect to those network components. The CA certificates can be found in the directory containing the byfn.sh script.

CA certificate for the orderer node:

crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/tls/ca.crt

CA certificate for Org1:

crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt

CA certificate for Org2:

crypto-config/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt

You will use these files later on to interact with the Hyperledger Fabric network.

Users

The organization Org1 is configured with a user named Admin@org1.example.com. This user is an administrator.

The user Admin@org1.example.com has a set of certificates and private key files stored in the directory:

crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

The organization Org2 is configured with a user named Admin@org2.example.com. This user is an administrator.

The user Admin@org2.example.com has a set of certificates and private key files stored in the directory:

crypto-config/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp

You will use some of these files later on to interact with the Hyperledger Fabric network.

In addition to the administrator, the CAs (Certificate Authorities) for Org1 and Org2 have been configured with a default user. This default user has an enrolment ID of admin and an enrolment secret of adminpw. However, this user does not have permission to deploy a blockchain business network.

It is recommended to create a temporary working directory (and subdirectories) to manage the Composer connection profiles and key/certificate files that we will work with later on in the tutorial.

mkdir -p /tmp/composer/org1

mkdir -p /tmp/composer/org2

Channel

A channel named mychannel has been created. All four peer nodes - peer0.org1.example.com, peer1.org1.example.com, peer0.org2.example.com, and peer1.org2.example.com have been joined to this channel.

Connection Profiles

We need a base connection profile that describes this fabric network which can then be given to alice and bob to customize for their organization.

{
    "name": "byfn-network",
    "x-type": "hlfv1",
    "version": "1.0.0",
    "channels": {
        "mychannel": {
            "orderers": [
                "orderer.example.com"
            ],
            "peers": {
                "peer0.org1.example.com": {
                    "endorsingPeer": true,
                    "chaincodeQuery": true,
                    "eventSource": true
                },
                "peer1.org1.example.com": {
                    "endorsingPeer": true,
                    "chaincodeQuery": true,
                    "eventSource": true
                },
                "peer0.org2.example.com": {
                    "endorsingPeer": true,
                    "chaincodeQuery": true,
                    "eventSource": true
                },
                "peer1.org2.example.com": {
                    "endorsingPeer": true,
                    "chaincodeQuery": true,
                    "eventSource": true
                }
            }
        }
    },
    "organizations": {
        "Org1": {
            "mspid": "Org1MSP",
            "peers": [
                "peer0.org1.example.com",
                "peer1.org1.example.com"
            ],
            "certificateAuthorities": [
                "ca.org1.example.com"
            ]
        },
        "Org2": {
            "mspid": "Org2MSP",
            "peers": [
                "peer0.org2.example.com",
                "peer1.org2.example.com"
            ],
            "certificateAuthorities": [
                "ca.org2.example.com"
            ]
        }
    },
    "orderers": {
        "orderer.example.com": {
            "url": "grpcs://localhost:7050",
            "grpcOptions": {
                "ssl-target-name-override": "orderer.example.com"
            },
            "tlsCACerts": {
                "pem": "INSERT_ORDERER_CA_CERT"
            }
        }
    },
    "peers": {
        "peer0.org1.example.com": {
            "url": "grpcs://localhost:7051",
            "grpcOptions": {
                "ssl-target-name-override": "peer0.org1.example.com"
            },
            "tlsCACerts": {
                "pem": "INSERT_ORG1_CA_CERT"
            }
        },
        "peer1.org1.example.com": {
            "url": "grpcs://localhost:8051",
            "grpcOptions": {
                "ssl-target-name-override": "peer1.org1.example.com"
            },
            "tlsCACerts": {
                "pem": "INSERT_ORG1_CA_CERT"
            }
        },
        "peer0.org2.example.com": {
            "url": "grpcs://localhost:9051",
            "grpcOptions": {
                "ssl-target-name-override": "peer0.org2.example.com"
            },
            "tlsCACerts": {
                "pem": "INSERT_ORG2_CA_CERT"
            }
        },
        "peer1.org2.example.com": {
            "url": "grpcs://localhost:10051",
            "grpcOptions": {
                "ssl-target-name-override": "peer1.org2.example.com"
            },
            "tlsCACerts": {
                "pem": "INSERT_ORG2_CA_CERT"
            }
        }
    },
    "certificateAuthorities": {
        "ca.org1.example.com": {
            "url": "https://localhost:7054",
            "caName": "ca-org1",
            "httpOptions": {
                "verify": false
            }
        },
        "ca.org2.example.com": {
            "url": "https://localhost:8054",
            "caName": "ca-org2",
            "httpOptions": {
                "verify": false
            }
        }
    }
}

Copy this base file (above) into a new file byfn-network.json under the new directory /tmp/composer and save it.

Open byfn-network.json and replace all instances of the text INSERT_ORG1_CA_CERT with the CA certificate for the peer nodes for Org1: - use the following command to get the certificate from the .pem file so that it can be embedded into the above connection profile.

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt > /tmp/composer/org1/ca-org1.txt

Copy the contents of the file /tmp/composer/org1/ca-org1.txt and replace the text INSERT_ORG1_CA_CERT in the .json file. It should now look something like this (must be a single line in the profile file as shown)

"pem": "-----BEGIN CERTIFICATE-----\nMIICNTCCAdygAwIBAgIRAMNvmQpnXi7uM19BLdha3MwwCgYIKoZIzj0EAwIwbDEL\nMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBG\ncmFuY2lzY28xFDASBgNVBAoTC2V4YW1wbGUuY29tMRowGAYDVQQDExF0bHNjYS5l\neGFtcGxlLmNvbTAeFw0xNzA2MjYxMjQ5MjZaFw0yNzA2MjQxMjQ5MjZaMGwxCzAJ\nBgNVBAYTAlVTMRMwEQYDVQQIEwpDYWxpZm9ybmlhMRYwFAYDVQQHEw1TYW4gRnJh\nbmNpc2NvMRQwEgYDVQQKEwtleGFtcGxlLmNvbTEaMBgGA1UEAxMRdGxzY2EuZXhh\nbXBsZS5jb20wWTATBgcqhkjOPQIBBggqhkjOPQMBBwNCAASJn3QUVcKCp+s6lSPE\nP5KlWmE9rEG0kpECsAfW28vZQSIg2Ez+Tp1alA9SYN/5BtL1N6lUUoVhG3lz8uvi\n8zhro18wXTAOBgNVHQ8BAf8EBAMCAaYwDwYDVR0lBAgwBgYEVR0lADAPBgNVHRMB\nAf8EBTADAQH/MCkGA1UdDgQiBCB7ULYTq3+BQqnzwae1RsnwQgJv/HQ5+je2xcDr\nka4MHTAKBggqhkjOPQQDAgNHADBEAiB2hLiS8B1g4J5Qbxu15dVWAZTAXX9xPAvm\n4l25e1oS+gIgBiU/aBwSxY0uambwMB6xtQz0ZE/D4lyTZZcW9SODlOE=\n-----END CERTIFICATE-----\n"

In the same .json file - you need to replace all instances of the text INSERT_ORG2_CA_CERT with the CA certificate for the peer nodes for Org2: - use the following command to convert the .pem file to something that can be embedded into the above connection profile.

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' crypto-config/peerOrganizations/org2.example.com/peers/peer0.org2.example.com/tls/ca.crt > /tmp/composer/org2/ca-org2.txt

Copy the contents of the file /tmp/composer/org2/ca-org2.txt and replace the text called INSERT_ORG2_CA_CERT. Once again, all on the same line.

Replace all instances of the text INSERT_ORDERER_CA_CERT with the CA certificate for the orderer node: use the following command to convert the .pem file to something that can be embedded into the above connection profile json file.

awk 'NF {sub(/\r/, ""); printf "%s\\n",$0;}' crypto-config/ordererOrganizations/example.com/orderers/orderer.example.com/tls/ca.crt > /tmp/composer/ca-orderer.txt

Copy the contents of the file /tmp/composer/ca-orderer.txt and replace the text INSERT_ORDERER_CA_CERT. Once again, all on the same line.

Once done, save this file as /tmp/composer/byfn-network.json.

This connection profile now describes the fabric network setup, all the peers, orderers and certificate authorities that are part of the network, it defines all the organizations that are participating in the network and also defines the channel's on this network. Hyperledger Composer can only interact with a single channel so only one channel should be defined.

Step Three: Customizing the connection profile for Org1

This is just a case of specifying the organization that alice belongs to, in a client section with optional timeouts, add the following block into the above connection profile /tmp/composer/byfn-network.json, between the version property and just before the channel property - once done, save it as a NEW file called /tmp/composer/org1/byfn-network-org1.json.

    "client": {
        "organization": "Org1",
        "connection": {
            "timeout": {
                "peer": {
                    "endorser": "300",
                    "eventHub": "300",
                    "eventReg": "300"
                },
                "orderer": "300"
            }
        }
    },

So the section of the profile should look like

    ...
    "version": "1.0.0",
    "client": {
        "organization": "Org1",
        "connection": {
            "timeout": {
                "peer": {
                    "endorser": "300",
                    "eventHub": "300",
                    "eventReg": "300"
                },
                "orderer": "300"
            }
        }
    },
    "channel": {
    ...

Step Four: Building a connection profile for Org2

Repeat the same process for bob - but this time specify the organization as Org2 and then save the file as /tmp/composer/byfn-network-org2.json - so the section of the profile should look like:

    ...
    "version": "1.0.0",
    "client": {
        "organization": "Org2",
        "connection": {
            "timeout": {
                "peer": {
                    "endorser": "300",
                    "eventHub": "300",
                    "eventReg": "300"
                },
                "orderer": "300"
            }
        }
    },
    "channel": {
    ...

Step Five: Locating the certificate and private key for the Hyperledger Fabric administrator for Org1

The administrator for our Hyperledger Fabric Org1 network is a user called Admin@org1.example.com. The certificates and private key files for this user are stored in the directory:

crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

You must first locate the certificate file for this user. The certificate is the public part of the identity. The certificate file can be found in the signcerts subdirectory and is named Admin@org1.example.com-cert.pem.

Next, you must locate the private key file for this user. The private key is used to sign transactions as this identity. The private key file can be found in the keystore subdirectory. The name of the private key file is a long hexadecimal string, with a suffix of _sk, for example: 78f2139bfcfc0edc7ada0801650ed785a11cfcdef3f9c36f3c8ca2ebfa00a59c_sk. The name will change every time the configuration is generated, hence the wildcard below.

Remember the path to both of these files - or copy them into the same directory as the connection profile file /tmp/composer/org1/byfn-network-org1.json that you created in 'Step Three'. You will need these files in the next steps.

Use the following commands to do this:

export ORG1=crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

cp -p $ORG1/signcerts/A*.pem /tmp/composer/org1

cp -p $ORG1/keystore/*_sk /tmp/composer/org1

Step Six: Locating the certificate and private key for the Hyperledger Fabric administrator for Org2

The administrator for our Hyperledger Fabric network is a user called Admin@org2.example.com. The certificates and private key files for this user are stored in the directory:

crypto-config/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp

You must first locate the certificate file for this user. The certificate is the public part of the identity. The certificate file can be found in the signcerts subdirectory and is named Admin@org2.example.com-cert.pem.

Next, you must locate the private key file for this user. The private key is used to sign transactions as this identity. The private key file can be found in the keystore subdirectory. The name of the private key file is a long hexadecimal string, with a suffix of _sk, for example d4889cb2a32e167bf7aeced872a214673ee5976b63a94a6a4e61c135ca2f2dbb_sk. The name will change every time the configuration is generated.

Remember the path to both of these files, or copy them into the same directory as the connection profile file /tmp/composer/byfn-network-org2.json that you created in step four. You will need these files in the next steps.

Use the following commands to do this:

export ORG2=crypto-config/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp

cp -p $ORG2/signcerts/A*.pem /tmp/composer/org2

cp -p $ORG2/keystore/*_sk /tmp/composer/org2

Step Seven: Creating business network cards for the Hyperledger Fabric administrator for Org1

In this step you will create business network cards for the administrator to use to deploy the blockchain business network to the Hyperledger Fabric network.

Run the composer card create command to create a business network card using the connection profile for Org1. You must specify the path to all three files that you either created or located in the previous steps: (note: the sk file will differ.)

composer card create -p /tmp/composer/org1/byfn-network-org1.json -u PeerAdmin -c /tmp/composer/org1/Admin@org1.example.com-cert.pem -k /tmp/composer/org1/*_sk -r PeerAdmin -r ChannelAdmin -f PeerAdmin@byfn-network-org1.card

If the command works successfully, a business network card file called PeerAdmin@byfn-network-org1.card will have been written to the current directory.

Step Eight: Creating business network cards for the Hyperledger Fabric administrator for Org2

In this step you will create business network cards for the administrator to use to deploy the blockchain business network to the Hyperledger Fabric network.

Run the composer card create command to create a business network card using the connection profile for Org2. You must specify the path to all three files that you either created or located in the previous steps:

composer card create -p /tmp/composer/org2/byfn-network-org2.json -u PeerAdmin -c /tmp/composer/org2/Admin@org2.example.com-cert.pem -k /tmp/composer/org2/*_sk -r PeerAdmin -r ChannelAdmin -f PeerAdmin@byfn-network-org2.card

If the command works successfully, a business network card file called PeerAdmin@byfn-network-org2.card will have been written to the current directory.

Step Nine: Importing the business network cards for the Hyperledger Fabric administrator for Org1

Run the composer card import command to import the business network card for Org1 into the wallet:

composer card import -f PeerAdmin@byfn-network-org1.card --card PeerAdmin@byfn-network-org1

If the command works successfully, a business network card called PeerAdmin@byfn-network-org1 will have been imported into the wallet.

Step Ten: Importing the business network cards for the Hyperledger Fabric administrator for Org2

Run the composer card import command to import the business network card for Org2 into the wallet:

composer card import -f PeerAdmin@byfn-network-org2.card --card PeerAdmin@byfn-network-org2

If the command works successfully, a business network card called PeerAdmin@byfn-network-org2 will have been imported into the wallet.

Step Eleven: Installing the business network onto the Hyperledger Fabric peer nodes for Org1

Run the composer network install command to install the business network onto all of the Hyperledger Fabric peer nodes for Org1 that you specified in the connection profile file you created in 'Step Three':

composer network install --card PeerAdmin@byfn-network-org1 --archiveFile trade-network.bna

As you can see from the above, we are using a Hyperledger Composer business network called trade-network to test our multi-org environment. You will need a file trade-network.bna (business network archive, from our sample networks) to do the test. If you don't have this, just go to https://composer-playground.mybluemix.net/ and deploy the trade-network sample in the online Playground, then 'connect' to the business network as 'admin', change the version number to 0.1.14 in the lower left, and export it to the current directory as trade-network.bna. The business network has a version property specified in a package.json file. That version must be specified when the business network is started using the composer start command in Step Seventeen. If you are using the trade-network sample network, the version is 0.1.14. (Note: If you are planning on using a different network, such as the Composer tutorial network tutorial-network as your business network, you would need to specify that file in the network install command above and thereafter, as the business network archive in this tutorial, as well as the correct version number for this business network).

A useful feature of the network install command is that it will output the name of the business network and the version number that has just been installed and you can note these down for use in 'Step Seventeen' later.

Step Twelve: Installing the business network onto the Hyperledger Fabric peer nodes for Org2

Run the composer network install command to install the business network onto all of the Hyperledger Fabric peer nodes for Org2 that you specified in the connection profile file you created in step four:

composer network install --card PeerAdmin@byfn-network-org2 --archiveFile trade-network.bna

Step Thirteen: Defining the endorsement policy for the business network

A running business network has an endorsement policy, which defines the rules around which organizations must endorse transactions before they can be committed to the blockchain. By default, a business network is deployed with an endorsement policy that states that only one organization has to endorse a transaction before it can be committed to the blockchain.

In real world blockchain business networks, multiple organizations will want to ensure that they endorse transactions before they can be committed to the blockchain, and so the default endorsement policy is not suitable. Instead, you can specify a custom endorsement policy when you start a business network.

You can find more information on endorsement policies in the Hyperledger Fabric documentation, in Endorsement policies.

Please note that the endorsement policies used for a business network must be in the JSON format used by the Hyperledger Fabric Node.js SDK. This is a different format to the simple endorsement policy format used by the Hyperledger Fabric CLI, which you will see in the Hyperledger Fabric documentation.

Create an endorsement policy file called /tmp/composer/endorsement-policy.json with the following contents and save it to disk. You will use this file in later steps, so remember where you place it!

{
    "identities": [
        {
            "role": {
                "name": "member",
                "mspId": "Org1MSP"
            }
        },
        {
            "role": {
                "name": "member",
                "mspId": "Org2MSP"
            }
        }
    ],
    "policy": {
        "2-of": [
            {
                "signed-by": 0
            },
            {
                "signed-by": 1
            }
        ]
    }
}

The endorsement policy you have just created states that both Org1 and Org2 must endorse transactions in the business network before they can be committed to the blockchain. If Org1 or Org2 do not endorse transactions, or disagree on the result of a transaction, then the transaction will be rejected by the business network.

Step Fourteen: Understanding and selecting the business network administrators

When a business network is started, the business network must be configured with a set of initial participants. These participants will be responsible for bootstrapping the business network and onboarding other participants into the business network. In Hyperledger Composer, we call these initial participants the business network administrators.

In our business network, the organizations Org1 and Org2 have equal rights. Each organization will provide a business network administrator for the business network, and those business network administrators will onboard the other participants in their organizations. The business network administrator for Org1 will be Alice, and the business network administrator for Org2 will be Bob.

When the business network is started, the certificates (the public part of the identity) for all of the business network administrators must be passed to the organization performing the commands to start the business network. After the business network has been started, all of the business network administrators can use their identities to interact with the business network.

You can find more information on business network administrators in Deploying Business Networks.

Step Fifteen: Retrieving business network administrator certificates for Org1

Run the composer identity request command to retrieve certificates for Alice to use as the business network administrator for Org1:

composer identity request -c PeerAdmin@byfn-network-org1 -u admin -s adminpw -d alice

The -u admin and the -s adminpw options to this command correspond to the default user registered with the Hyperledger Fabric CA (Certificate Authority).

The certficates will be placed into a directory called alice in the current working directory. There are three certificate files created, but only two are important. These are admin-pub.pem, the certificate (including the public key), and admin-priv.pem, the private key. Only the admin-pub.pem file is suitable for sharing with other organizations. The admin-priv.pem file must be kept secret as it can be used to sign transactions on behalf of the issuing organization.

Step Sixteen: Retrieving business network administrator certificates for Org2

Run the composer identity request command to retrieve certificates for Bob to use as the business network administrator for Org2:

composer identity request -c PeerAdmin@byfn-network-org2 -u admin -s adminpw -d bob

The -u admin and the -s adminpw options to this command correspond to the default user registered with the Hyperledger Fabric CA (Certificate Authority).

The certficates will be placed into a directory called bob in the current working directory. There are three certificate files created, but only two are important. These are admin-pub.pem, the certificate (including the public key), and admin-priv.pem, the private key. Only the admin-pub.pem file is suitable for sharing with other organizations. The admin-priv.pem file must be kept secret as it can be used to sign transactions on behalf of the issuing organization.

Step Seventeen: Starting the business network

Run the composer network start command to start the business network. Only Org1 needs to perform this operation. This command uses the /tmp/composer/endorsement-policy.json file created in step thirteen, and the admin-pub.pem files created by both Alice and Bob in step fifteen and step sixteen, so you must ensure that all of these files are accessible to this command:

composer network start -c PeerAdmin@byfn-network-org1 -n trade-network -V 0.1.14 -o endorsementPolicyFile=/tmp/composer/endorsement-policy.json -A alice -C alice/admin-pub.pem -A bob -C bob/admin-pub.pem

Once this command completes, the business network will have been started. Both Alice and Bob will be able to access the business network, start to set up the business network, and onboard other participants from their respective organizations. However, both Alice and Bob must create new business network cards with the certificates that they created in the previous steps so that they can access the business network.

Step Eighteen: Creating a business network card to access the business network as Org1

Run the composer card create command to create a business network card that Alice, the business network administrator for Org1, can use to access the business network:

composer card create -p /tmp/composer/org1/byfn-network-org1.json -u alice -n trade-network -c alice/admin-pub.pem -k alice/admin-priv.pem

Run the composer card import command to import the business network card that you just created:

composer card import -f alice@trade-network.card

Run the composer network ping command to test the connection to the blockchain business network:

composer network ping -c alice@trade-network

If the command completes successfully, then you should see the fully qualified participant identifier org.hyperledger.composer.system.NetworkAdmin#alice in the output from the command. You can now use this business network card to interact with the blockchain business network and onboard other participants in your organization.

Lets create a participant, issue an identity (mapped to that participant) and create an asset on the blockchain network as that identity.

Run the composer participant add command below, copying it to the command line to execute:

composer participant add -c alice@trade-network -d '{"$class":"org.example.trading.Trader","tradeId":"trader1-org1", "firstName":"Jo","lastName":"Doe"}'

Next create the identity for trader1-org1 with the composer issue identity command below:

composer identity issue -c alice@trade-network -f jo.card -u jdoe -a "resource:org.example.trading.Trader#trader1-org1"

Import the card and test it

composer card import -f jo.card

composer network ping -c jdoe@trade-network

Next we will create an asset - From the command line, submit a transaction to create a Commodity asset, as participant jdoe (or alternatively, if you already have Composer Playground installed, connect as jdoe@trade-network to trade-network to create the asset 'EMA' - the JSON snippet is shown below ).

To create the asset using the CLI - copy the transaction submit sequence below - it creates a Commodity asset for you:

composer transaction submit --card jdoe@trade-network -d '{"$class": "org.hyperledger.composer.system.AddAsset", "targetRegistry" : "resource:org.hyperledger.composer.system.AssetRegistry#org.example.trading.Commodity", "resources": [{"$class": "org.example.trading.Commodity","tradingSymbol":"EMA", "description":"Corn commodity","mainExchange":"EURONEXT", "quantity":"10","owner":"resource:org.example.trading.Trader#trader1-org1"}]}'

Or alternatively, to create in Playground - copy the following:

{
  "$class": "org.example.trading.Commodity",
  "tradingSymbol": "EMA",
  "description": "Corn commodity",
  "mainExchange": "EURONEXT",
  "quantity": 10,
  "owner": "resource:org.example.trading.Trader#trader1-org1"
}

Finally, do a composer network list to confirm the generated artifacts in the business network:

composer network list -c jdoe@trade-network

Step Nineteen: Creating a business network card to access the business network as Org2

Run the composer card create command to create a business network card that Bob, the business network administrator for Org2, can use to access the business network:

composer card create -p /tmp/composer/org2/byfn-network-org2.json -u bob -n trade-network -c bob/admin-pub.pem -k bob/admin-priv.pem

Run the composer card import command to import the business network card that you just created:

composer card import -f bob@trade-network.card

Run the composer network ping command to test the connection to the blockchain business network:

composer network ping -c bob@trade-network

If the command completes successfully, then you should see the fully qualified participant identifier org.hyperledger.composer.system.NetworkAdmin#bob in the output from the command. Let's onboard another Trader, this time for Org 2:

Once again, create a participant, issue an identity (mapped to that participant) - as we already have an asset on the blockchain network, we will use a transaction to change the ownership (from Org1 trader to an Org2 trader):

Run the composer participant add command below, copying it to the command line to execute:

composer participant add -c bob@trade-network -d '{"$class":"org.example.trading.Trader","tradeId":"trader2-org2", "firstName":"Dave","lastName":"Lowe"}'

Next create the identity for trader2-org2 with the composer issue identity command below:

composer identity issue -c bob@trade-network -f dave.card -u dlowe -a "resource:org.example.trading.Trader#trader2-org2"

Import the card and test it

composer card import -f dave.card

composer network ping -c dlowe@trade-network

Lastly, submit a transaction to change ownership of the Commodity asset created earlier. We will submit the transaction as the asset owner Jon Doe and transfer it to trader 'Dave Lowe'. We will then verify the ownership change has occurred as the Org 2 trader participant mapped to the dlowe identity: Perform the step below.

composer transaction submit --card jdoe@trade-network -d '{"$class":"org.example.trading.Trade","commodity":"resource:org.example.trading.Commodity#EMA","newOwner":"resource:org.example.trading.Trader#trader2-org2"}'

Finally, do a composer network list as the Org 2 trader participant to confirm the change of ownership on the asset:

composer network list -c dlowe@trade-network

Conclusion

In this tutorial you have seen how to configure a blockchain network based on Hyperledger Composer in a multi-organizational setup. You've also learned how to deploy a business network (such as our Commodities trading network) to that blockchain network and perform some simple transactions as participants in each organization, using identities that were issued by the Certificate of Authorities in either organization.