Operating the Hyperledger Fabric smart contracts the right way!
The document is for Hyperledger Fabric developers and administrators. You would need to know how to install, upgrade and revert your chaincode on a Hyperledger Fabric network. This article is an attempt to simplify the understanding, it is not a replacement for the wonderful documentation created by the Hyperledger community. Refer to the official documentation for the detailed insights.
Tip: Understanding the chaincode package in detail requires another article. In simple terms, a package is file archive that has everything related to your chaincode. Hyperledger Fabric peer wouldn’t require anything extra outside of this package.
Chaincode installation “Old” vs “New” lifecycle
In the earlier versions of Hyperledger Fabric, you would install a chaincode package on all the peers in a channel, initialize the chaincode on the peer (Hyperledger Fabric peer brings up a chaincode container), then invoke the chaincode.
The process lacks a way of customizing chaincode per organization. If an organization has additional smart contract validations, they want to customize the chaincode for themselves, there needs to be a way for it. The new chaincode lifecycle allows for each organization to choose the package they want. Hyperledger Fabric has a lifecycle system chaincode to manage the requirement.
A system chaincode is pre-installed in your Hyperledger Fabric peer node. It has specific functionality defined. It is used handle administration of your Hyperledger Fabric network using blockchain principles.
How to install “Chaincode” on Hyperledger Fabric using lifecycle?
The points below can be considered a golden summary for installing the chaincode. Installing a chaincode involves following steps
- Install chaincode on each peer node at a specific version.
- Approve chaincode package ID for an organization at a sequence.
- Commit chaincode approved at a specific sequence.
Install: The peer node generates the chaincode package ID when a package is installed. The chaincode package is copied and stored on a peer node at the installation step. The peer node also does a match of chaincode builders when a chaincode package is installed. The release artefacts that a peer can later use to connect to the chaincode or the artefacts that a chaincode can use to connect to the peer node are generated.
Approve: An organization participating in a channel will approve for a particular package ID. The approval shall happen against a specific sequence. Each organization could have their own package ID approved for the same sequence.
Commit: Once the channel participants have approved for their sequence, one of them can proceed with committing to the sequence. What this allows is for every participant to have their own version of chaincode running alongside their peer nodes, but globally agreed upon in a channel setup.
What is relationship between chaincode “Version”, “Package ID”, “Sequence”, “Name” and the “Channel”?
When you are working with Hyperledger Fabric, there are so many terms related to chaincode. It could easily distract you if you do not understand their meaning accurately.
Always remember that the chaincode installation happens on a peer node. The chaincode can then be used on all the channels to which that particular peer is part of. Every channel requires a chaincode commit operation. You can have a setup where on a channel 1 it has chaincode A at version 2, at the same time channel 2 has chaincode A at version 3. There exists complete independence for an administrator.
Name: Unique name to identify the chaincode on a peer node.
Channel: A chaincode definition can be approved and committed on multiple channels. The peer nodes participating in a channel would pick up the chaincode package by using the chaincode package ID.
Version: It is important to note that the version number of a chaincode is local to the peer node where it is installed. Use this parameter as a SVN that a system administrator requires.
Chaincode ID (Package ID): An organization has to approve for one package ID for a chaincode (identified by its “name”). If you have multiple peers belonging to an organization, then install same version of chaincode on all of them. They all “shall” generate the same package ID.
Sequence: Once there are sufficient number of approvals as per the policy, a chaincode definition can be committed. Sequence number is a unique number across consortium members to commit to a change in the definition.
A peer node when you install the chaincode package, stores it using name, version and the package ID.
Tip: It is tricky to generate the same package ID in case of using chaincode as a server. Especially if you are trying to attach different chaincode servers to each of the peer node.
How to “Upgrade” and “Revert” a chaincode in Hyperledger Fabric?
Upgrading a chaincode involves one to run through series of same steps as they followed for initial installation of the chaincode. You would update the version number for easier identification of the package on a peer node.
At given point in time for a given chaincode name, there can only be one version active.
Every time, you require to upgrade the chaincode, the new sequence associated with the new package ID shall be committed by the channel participants (as per the policy).
There is no true “Revert” of chaincode, you would instead assign a newer version to your earlier chaincode, repeat all the steps you did for the chaincode upgrade.
Note: Remember that the blockchain technology provides a means of keeping immutable entry of records. Blockchain data is trustable as long as you have put in appropriate measures to not write unexpected data. “What you Write is What you Get” from the blockchain. If you had an erroneous smart contract installed on your network, and it has done an unexpected state change then the only way to recover back your old data is to run a correction method in your smart contract. You cannot erase that you did an error earlier, but at the same time you get to know that you took a recovery action.