Fabric Sample -- Building Your First Network

This post runs the Building Your First Network sample from fabric-samples. The network has 4 peers split across 2 organizations, plus a single orderer. A cli container is also needed to interact with the network nodes.

Preparation

1. Environment setup
This covers the required software and Docker images. See https://zhayujie.com/deploy.html for details.

2. Download fabric-samples
Clone fabric-samples (v1.1) from GitHub:

mkdir -p ~/go/src/github.com/hyperledger      // create this directory if it doesn't exist
cd ~/go/src/github.com/hyperledger
git clone -b master https://github.com/hyperledger/fabric-samples.git
cd fabric-samples

3. Download the binaries
Download URL: https://nexus.hyperledger.org/content/repositories/releases/org/hyperledger/fabric/hyperledger-fabric
Pick a suitable version, put the extracted bin directory under the fabric-samples directory, and add it to PATH:

vim ~/.bash_profile            // .profile on Ubuntu
Add: export PATH=$HOME/hyperledger/fabric-samples/bin:$PATH

Running with the Script

1. Generate the network artifacts
This command uses the cryptogen and configtxgen tools to generate the certificates and keys for the network members, the ordering service genesis block, the channel configuration transaction, and the anchor peer updates for Org1 and Org2.

cd ~/hyperledger/fabric-samples/first-network
./byfn.sh -m generate

2. Bring up the network
This step starts all nodes in the network, creates the channel and joins the peers to it, installs and instantiates the chaincode, and then runs a series of queries and transactions.

./byfn.sh -m up

3. Bring down the network
This command removes all containers, the generated artifacts, and the chaincode images.

./byfn.sh -m down

Running Step by Step Manually

To get a better understanding of how a Fabric network is created, you can perform every operation in the script above by hand, one step at a time.

1. Generate the artifacts

1. Generate certificates
From the first-network directory, the following command generates the crypto-config directory (the MSP directory, which holds the members' certificates and private keys) based on the crypto-config.yaml config file:

// if the binaries are on PATH, you can run cryptogen generate directly
../bin/cryptogen generate --config=./crypto-config.yaml

2. Generate the genesis block
This creates the channel-artifacts directory and generates genesis.block in it. The genesis block is used to start the orderer in the network.

export FABRIC_CFG_PATH=$PWD     // tells configtxgen where configtx.yaml is
../bin/configtxgen -profile TwoOrgsOrdererGenesis -outputBlock ./channel-artifacts/genesis.block

3. Generate the channel configuration transaction
This step generates channel.tx in the channel-artifacts directory. When the channel is created, this channel configuration transaction is read from the local file and sent to the orderer.

export CHANNEL_NAME=mychannel    // set the channel name
../bin/configtxgen -profile TwoOrgsChannel -outputCreateChannelTx ./channel-artifacts/channel.tx -channelID $CHANNEL_NAME

4. Generate the anchor peer configuration transactions
Anchor peers are used for gossip communication (block synchronization) between organizations. This step generates Org1MSPanchors.tx and Org2MSPanchors.tx in the channel-artifacts directory. These two configuration transactions are used when setting the anchor peers.

../bin/configtxgen -profile TwoOrgsChannel -outputAnchorPeersUpdate ./channel-artifacts/Org1MSPanchors.tx -channelID $CHANNEL_NAME -asOrg Org1MSP
../bin/configtxgen -profile TwoOrgsChannel -outputAnchorPeersUpdate ./channel-artifacts/Org2MSPanchors.tx -channelID $CHANNEL_NAME -asOrg Org2MSP

2. Start the network

1. Start the node containers
Before starting, edit docker-compose-cli.yaml and comment out this line in the cli container section:

command: /bin/bash -c './scripts/script.sh ${CHANNEL_NAME} ${DELAY}; sleep $TIMEOUT'

That line makes the cli container run script.sh automatically at startup, which carries out every step on its own. Since we want to run the steps by hand here, just comment it out.

Start all nodes in the network:

docker-compose -f docker-compose-cli.yaml up -d

2. Create the channel
Note: the CLI container connects to peer0.org1.example.com by default, and the environment variables it needs are already set. To operate on another peer or on the orderer, you need to set these environment variables again.
First, enter the cli container. All of the following commands run inside it:

docker exec -it cli bash

Run the following command to create the channel. The --cafile flag specifies the path to the orderer's TLS root CA certificate, which is used to verify the TLS connection.

export CHANNEL_NAME=mychannel
peer channel create -o orderer.example.com:7050 -c $CHANNEL_NAME -f ./channel-artifacts/channel.tx --tls --cafile /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem

3. Join the channel
The create channel command generates a <channel-ID.block> in the cli container, here mychannel.block. This is the channel's genesis block, the first block on the chain of every peer in the channel. The join channel operation sends this block to the specified peer.
First, join peer0.org1.example.com to the channel:

peer channel join -b mychannel.block

To join other peers, you need to change the environment variables (the peer's ip:port, certificate paths, and so on). Here peer0.org2.example.com is used as an example.

CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peerOrganizations/org2.example.com/users/Admin@org2.example.com/msp CORE_PEER_ADDRESS=peer0.org2.example.com:7051 CORE_PEER_LOCALMSPID="Org2MSP" 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
peer channel join -b mychannel.block

4. Install the chaincode
The chaincode path inside the cli container is as follows (use the actual path when installing):

github.com/chaincode/chaincode_example02/go/chaincode_example02.go

Run the command to install the chaincode onto the specified peer's file system (here it is installed only on peer0.org1.example.com):

peer chaincode install -n mycc -v 1.0 -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02

5. Instantiate the chaincode
Instantiation happens at the channel level. It binds the chaincode to the channel, and a given chaincode can be instantiated only once on a channel. On the specified target peer, a chaincode image is built and its container is started. Other peers in the channel that have the chaincode installed build the image and start the container automatically the first time they are targeted for a query or transaction.

peer chaincode instantiate -o orderer.example.com:7050 --tls --cafile /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem -C $CHANNEL_NAME -n mycc -v 1.0 -c '{"Args":["init","a", "100", "b","200"]}' -P "OR ('Org1MSP.member','Org2MSP.member')"

The -P flag sets the endorsement policy, here OR ('Org1MSP.member','Org2MSP.member'), which means a transaction is valid once it has been endorsed by any one peer in Org1 or Org2.
The -c flag calls the chaincode's init function, setting a and b to 100 and 200 respectively.

6. Query
Query the value of a, assuming the cli environment variables still point to peer0.org1.example.com:

peer chaincode query -C $CHANNEL_NAME -n mycc -c '{"Args":["query","a"]}'

The result is:

Query Result:100

7. Transaction
Transfer 10 units from account a to account b. This step sends a transaction to the orderer, appends a new block to the blockchain, and updates the state database.

peer chaincode invoke -o orderer.example.com:7050  --tls --cafile /opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/ordererOrganizations/example.com/orderers/orderer.example.com/msp/tlscacerts/tlsca.example.com-cert.pem  -C $CHANNEL_NAME -n mycc -c '{"Args":["invoke","a","b","10"]}'

Once the transaction completes, you can query a again against a different peer and get 90, which shows that the ledger data on different peers stays in sync.