Chaincode Lifecycle on Hyperledger Fabric

Chaincode, also known as smart contracts, is a type of software that runs on a blockchain network and executes specific business logic. They are used to define the rules for interacting with the data stored on a blockchain, such as reading and writing data to the ledger, verifying the identity of users, and enforcing access controls.
Chaincode is typically written in a programming language that is supported by the blockchain platform, such as Go, JavaScript, or Java. The article focus on discussing the chaincode lifecycle on Hyperledger Fabric.

What is Chaincode?

Chaincode is a program written in Go, Node, or Java that implements a prescribed interface and runs in a secured Docker container isolated from the endorsing peer process. 

• Chaincode handles the business logic agreed to by the members of the network.
• It initializes and manages the ledger state through transactions submitted by applications.
• It is deployed to the blockchain network as a package and can be invoked by clients through transactions. 

Chaincode Life Cycle

Chaincode lifecycle is a process that allows multiple organizations to agree on how a chaincode will be operated before it can be used on a channel. The process of deploying chaincode to a blockchain network typically involves the following four steps:

1. Package: This step involves packaging the chaincode source code into a deployable package. The package consists of the chaincode source code, as well as any dependencies and metadata required for the chaincode to be installed and executed on the network. The chaincode needs to be packaged in a tar file before it can be installed on your peers. The chaincode can be packaged using 

peer lifecycle chaincode package <PACKAGE_NAME> –path <PATH> –lang <LANG> –label <LABEL>

Here,

PACKAGE_NAME: It must be a tar file ending with .tar.gz extension
PATH: It refers to the chaincode path and must be located under the /opt/gopath/src/ directory 
LANG: It refers to the language that is used to write the chaincode
LABEL: It can be any text

2. Install: In this step, the packaged chaincode is installed on the endorsing peer nodes that are part of the target network. The endorsing peers are responsible for executing the chaincode and returning the results to the client application.

peer lifecycle chaincode install <PACKAGE_NAME>

Here,

PACKAGE_NAME: It must be the same as mentioned in the previous step

peer lifecycle chaincode queryinstalled 

Use this command to approve the chaincode definition to organizations. This command generates PACKAGE_ID that will be used in the next step. 

3. Approve: After the chaincode is installed on the endorsing peer nodes, it must be approved by one or more organizations in the network before it can be committed and activated. This step involves creating a proposal to approve the chaincode, which is then sent to the designated chaincode endorsement policy (CCEP) evaluators for approval. The CCEP specifies the organizations and/or individuals that must approve the chaincode before it can be committed.

peer lifecycle chaincode approveformyorg -o <orderer_url> –tls –cafile $ORDERER_CA –channelID CHANNEL_NAME> –name <CHAINCODE_NAME> –version <VERSION_TAG> –init-required –package-id $PACKAGE_ID –sequence 1 –signature-policy “OR(Organizations in network)”

Here,

CHANNEL_NAME: This refers to the channel name that was created

CHAINCODE_NAME: This refers to the chaincode name

VERSION_TAG: This refers to the channel name

–signature-policy: This can be changed by the organizations in the network.

4. Commit: In the final step, the chaincode is committed to the network’s shared ledger, making it available for execution by client applications. This step involves creating a transaction containing the chaincode deployment proposal and sending it to the ordering service, which then orders and broadcasts the transaction to the peer nodes in the network. The peer nodes then validate the transaction, and if it is valid, it is added to the ledger, and the chaincode is activated and ready for use.

peer lifecycle chaincode commit -o <orderer_url> –channelID <CHANNEL_NAME> –name <CHAINCODE_NAME> –version <VERSION_TAG> –sequence 1 –init-required –tls –cafile $ORDERER_CA –peerAddresses <PEER_ADDRESS> –tlsRootCertFiles <TLS_ROOT_CERT_FILES>

Here,

CHANNEL_NAME, CHAINCODE_NAME, and VERSION_TAG: This must be same as the one mentioned in the previous step

PEER_ADDRESS and TLS_ROOT_CERT_FILES: This refer to peer address and .crt file’s path of each peer that will commit so write as much –peerAddress and –tlsRootCertFiles as much there are number of peers

Upgrade a Chaincode

One can upgrade a chaincode using the same Fabric lifecycle process as used to install and start the chaincode. One can upgrade the chaincode binaries or just update the chaincode policies. Follow the steps below to upgrade a chaincode:

1. Repackage the chaincode: This steps needs to be completed only if upgrading the chaincode binaries. The organizations upgrade the chaincode and repackage the chaincode. Both organizations use different package labels for the chaincode.

2. Install the new chaincode package on your peers: This step again needs to be completed only when in case of upgrading the chaincode binaries. Installing the new chaincode package will generate a package ID which will be passed to the new chaincode definition. The chaincode version also needs to be updated which is used by the lifecycle process to track if the chaincode binaries have been upgraded.

3. Approve a new chaincode definition: If upgrading the chaincode binaries then the chaincode version and package ID need to be updated in the chaincode definition. Chaincode endorsement policy can be updated without having to repackage the chaincode binaries. Channel members have to approve the definition with the new policy. The new definition needs to increment the sequence variable in the definition by one.

4. Commit the definition to the channel: When a sufficient number of channel members have approved the new chaincode definition, one organization can commit the new definition to upgrade the chaincode definition to the channel. There is no separate upgrade command.

• After committing the chaincode definition, a new chaincode container will launch with the code from the upgraded chaincode binaries.
• If chaincode definition is updated without changing the chaincode version, the chaincode container will remain the same and there is no need to invoke the Init function.
• If there is a request for execution of the Init function in the chaincode definition then there is a need to initialize the upgraded chaincode by invoking the Init function again after the new definition is successfully committed. 

The sequence is used in the chaincode definition to keep track of the upgrades. The channel members need to upgrade the sequence number by one and approve a new definition to upgrade the chaincode. The version parameter will be used to track the chaincode binaries and needs to be changed only when the chaincode binaries are upgraded.

Chaincode Deployment/ Life Cycle Scenarios

The chaincode lifecycle refers to the process of developing, deploying, and managing chaincode (also known as smart contracts) on a blockchain platform. The specific steps involved in the chaincode lifecycle may vary depending on the platform, but generally, it consists of the following stages:

1. Join a channel: In this scenario, an organization wants to join an existing channel and deploy a chaincode on that channel. The organization would need to perform the following steps:

• Package the chaincode: Use the peer lifecycle chaincode package command to create a package file containing the chaincode source code and dependencies.
• Install the chaincode: Use the peer lifecycle chaincode install command to install the chaincode package on a peer.
• Approve the chaincode: Use the peer lifecycle chaincode approveformyorg command to submit a proposal to the channel’s endorsing peers to approve the chaincode for deployment.
• Commit the chaincode: Use the peer lifecycle chaincode commit command to submit a transaction to the channel containing the approved chaincode and its associated metadata. The chaincode becomes active on the channel once the transaction is committed.

2. Update an endorsement policy: In this scenario, an organization wants to update the endorsement policy for an existing chaincode on a channel. The endorsement policy specifies which organizations must endorse a transaction before it can be committed to the ledger.
To update the endorsement policy for a chaincode, the organization would need to perform the following steps:

• Update the chaincode source code: Modify the chaincode source code to specify the new endorsement policy.
• Package the chaincode: Use the peer lifecycle chaincode package command to create a new package file containing the updated chaincode source code and dependencies.
• Install the chaincode: Use the peer lifecycle chaincode install command to install the updated chaincode package on a peer.
• Approve the chaincode: Use the peer lifecycle chaincode approveformyorg command to submit a proposal to the channel’s endorsing peers to approve the updated chaincode for deployment.
• Commit the chaincode: Use the peer lifecycle chaincode commit command to submit a transaction to the channel containing the approved chaincode and its associated metadata. The updated chaincode becomes active on the channel once the transaction is committed.

3. Approve a definition without installing: In this scenario, an organization wants to approve a chaincode definition without installing the chaincode package on a peer. This might be useful if the organization wants to approve the chaincode definition but is not yet ready to install the chaincode. To approve a chaincode definition without installing it, the organization can use the peer lifecycle chaincode approveformyorg –sequence <chaincode_sequence> –init-required command, which takes the following form:

peer lifecycle chaincode approveformyorg –channelID <channel_name> –name <chaincode_name> –version <chaincode_version> –init-required –sequence <chaincode_sequence> –tls –cafile <path_to_tls_certificate>

4. Disagreement on definitions: In this scenario, Organization A and Organization B are part of a network that uses Hyperledger Fabric. They both agree to deploy a new chaincode to the network, but they have a disagreement on the definitions of certain variables and functions in the chaincode. To resolve the disagreement, they decide to create two different versions of the chaincode, each with its own definitions. They package and install the chaincodes on their respective endorsing peer nodes, and then create proposals to approve the chaincodes. The proposals are sent to the designated CCEP evaluators, who review the proposals and determine that both versions of the chaincode meet the CCEP requirements. As a result, both versions of the chaincode are approved and can be committed to the network.

5. Multiple organizations install different packages: In this scenario, Organization A and Organization B are part of a network that uses Hyperledger Fabric. They both agree to deploy a new chaincode to the network, but they have different ideas on how the chaincode should be implemented. Organization A decides to create a chaincode package with its preferred implementation, while Organization B creates a separate chaincode package with its own implementation. Both packages are installed on the endorsing peer nodes of their respective organizations.

6. Create multiple chaincodes from one package: In this scenario, Organization A is part of a network that uses Hyperledger Fabric. They create a chaincode package and install it on their endorsing peer nodes. After the chaincode is installed, they create a proposal to approve the chaincode and send it to the designated CCEP evaluators for approval. The CCEP evaluators review the proposal and determine that the chaincode meets the CCEP requirements. As a result, the chaincode is approved and can be committed to the network. However, Organization A decides that they want to create multiple versions of the chaincode, each with slightly different functionality. To do this, they can use the peer chaincode instantiate command to create multiple instances of the chaincode from the same package. Each instance will have its own unique name and version and can be approved and committed separately.

Managing the chaincode lifecycle is an important aspect of developing and maintaining applications on a blockchain platform. It ensures that the chaincode is properly deployed and configured and that it can be updated and maintained as needed.