Chaincode Management
Chaincode is a smart contract of Hyperledger Fabric that handles the business logic of a particular application. A smart contract programmatically accesses two distinct pieces of the ledger – a blockchain, which immutably records the history of all transactions, and a world state that holds a cache of the current value of these states.
In other words, a chaincode is programmable code that runs on the peers and facilitates transactions on a Hyperledger Fabric blockchain application allowing the users to update the world state of the assets.
The chaincode structure usually represents business logic, asset definition, or transactional flow. Catalyst Blockchain Platform supports JavaScript, Golang, and Java for smart contract development.
Endorsement
Any transaction generated by the chaincode must be approved by specific organizations, which are defined according to the business logic.
The chaincode endorsement policy defines which organization in the channel is required to validate the transaction by signing it digitally for that transaction to be declared valid. See more information here.
Valid Transactions
When a smart contract executes, it runs on a peer node. The contract takes a set of input parameters (transaction proposal) and uses them in combination with its program logic to read and write to the ledger. Changes to the world state are captured as a transaction proposal response, which contains a read-write set with both the states that have been read and the new states that are to be written if the transaction is valid. See more information here.
Each peer completes the validation of a transaction in two phases.
- 1.Ensuring that all the parties mentioned in the endorsement policy have signed the transaction.
- 2.Checking the authenticity of a transaction as it matches the current value of the world state with the value present at the time of signing the transaction, ensuring that there have not been any changes in between.
In cases where the transaction is not valid, the read activity is still recorded to the blockchain history. However, only the valid transactions update the world state.
Chaincode Namespace
Chaincode namespaces provide isolation between different world states.
The contracts inside a single chaincode share access to the same world state, while the contracts in different chaincodes do not have access to each other’s world state.
Users cannot choose the chaincode namespace; it is assigned by Hyperledger Fabric and maps directly to the name of the chaincode.
External Chaincodes
With Hyperledger Fabric v2.0, the user can add a Chaincode externally through a Docker image. The process of adding an external chaincode becomes difficult if you do not possess enough technical knowledge. However, on Catalyst Blockchain Platform, you can refer to your Docker image that was uploaded to your online repository. The Catalyst Blockchain Platform will run the chaincode container in the same environment as the Fabric application.
Catalyst Blockchain Platform supports Hyperledger Fabric application v2.0 capabilities, which define the following chaincodes lifecycle:
- Package the chaincode - This step can be completed by one organization or by each organization. The user needs to create a Docker image and provide a link to the Docker repository while adding chaincode in Catalyst Blockchain Platform.
Important - You need to add environment variables mentioned in the guide to run chaincode in Catalyst Blockchain Platform.
- Install the chaincode on your peers - Every organization that will use the chaincode to endorse a transaction or query the ledger needs to complete this step.
- Approve a chaincode definition for your organization - Every organization that will use the chaincode needs to complete this step. The chaincode definition needs to be approved by a sufficient number of organizations to satisfy the channel’s Lifecycle Endorsement policy before the chaincode can be started on the channel.
There is a Chaincode tab on the left-hand side of the screen in the Catalyst Blockchain Platform dashboard. To see information regarding all of the chaincodes currently added on the platform, you need to click on the “Chaincode” tab.
The information is divided into four columns: Name, Version, Image, and Actions. There is a chain icon with a small “+” sign on the upper right-hand corner inside this box.
Add chaincode
This icon allows the user to add a new chaincode on their Catalyst Blockchain Platform. Clicking this option opens up a new window as a panel on the right that includes all of the necessary fields for adding the chaincode.
You can see the following fields:
- Chaincode name
Note: The name of a chaincode should contain only lowercase letters.
- Image - Link to your chaincode docker container at the public docker repository.
- CPU limit
- Memory limit
- Private repository - Use this field to add a private repository (for example, JFrog) to provide the chaincode. Upon clicking it, three new fields are displayed on the screen: server name, username, and password for the private repository.
Click the Submit button to add the chaincode on the platform.
Chaincode templates - After adding a chaincode on the platform, you do not need to add it individually on each peer because you can install the already added chaincode on the peer. Templates help keep the same version of chaincode for all peers, ensuring the seamless execution of transactions and queries among the peers.
Any peer that wants to leverage the chaincode to complete a transaction or query the ledger must install that particular chaincode. If the installation of a chaincode is done through code, it requires extensive knowledge of Docker containers and Linux commands, not to mention the time consumed throughout the process. However, Catalyst Blockchain Platform streamlines the entire process by allowing users to add the chaincode through just a few clicks.
Please go to the “Peer” tab present in the left navigation bar on Catalyst Blockchain Platform, displaying the available peers in a particular organization. Ensure that the peer on which you want to install the chaincode has a green tick on the upper right-hand corner, which shows that it is running. (For information about peer status, please refer to this section). After this, the user can click on a specific peer, which displays peer actions. The fourth option in the available actions is “Install chaincode.”
Install chaincode
It opens an on-screen menu when clicked. You can select the chaincode from a drop-down menu that displays all of the chaincodes added to the platform.
Install chaincode
You can also add indexes for optimizing performance when using CouchDB as a state database.
- Chaincode index needs two sub fields to be entered: chaincode index name and chaincode index jsons.
- To add a private index, you need to fill in three subfields: private index name, private collection name, and private index Jsons. Private indexes refer to private data collections. To provide more granularity to the network, Hyperledger Fabric allows the creation of private data collection. The private data collection contains private data and hash. The private data is shared among a specified group of organizations inside the channel while the hash goes through the process of endorsement and ordering and finally getting written to the ledger which is shared by all peers to act as a proof of the transaction. Details of the private collection are specified at the time of chaincode approval on a channel.
By clicking the “Chaincodes” tab on the “Peer Details” tab, you can see installed chaincodes on that specific peer. The information displayed under this tab are Label, PackageID, and Available/All Replicas:
Chaincodes tab
- Label - Human-readable description of the package.
- PackageID - A package identifier is used to associate a chaincode package installed on your peers with a chaincode definition approved by your organization. The peer generates it.
- Available/All Replicas - See below.
- Available: amount of chaincode pods which are up and running.
- All replicas: the number of chaincode pods that are up and running.
Note: The current version of Catalyst Blockchain Platform supports a single replica, but it will be possible to add more chaincode replicas in future releases.
After the chaincode was installed on the peer, the chaincode container will launch on all of the peers where the chaincode is installed, allowing channel members to start using the chaincode. It may take a few minutes for the chaincode container to start.
Tip: If you observe that 0/1 replicas are running, you need to wait a little longer or upgrade the chaincode. Removing chaincode from the peer is not supported by the current Catalyst Blockchain Platform version.
Every chaincode has a definition that includes certain parameters such as name, version, endorsement policy, and more. This chaincode definition needs to be approved by the channel members for the peers to use that chaincode. The chaincode needs to be approved only once by each organization and used by all peers in the channel. The approval of the chaincode is subject to the endorsement policy, which defines the voting mechanism. The endorsers (regarding the channel policies) are responsible for authenticating the chaincode. Each endorser should approve the same chaincode definition to be able to commit it to the channel.
To approve a chaincode on a channel,
- 1.Go to the “Channels” tab and open the specific channel where you need to approve the chaincode.
- 2.Under the “Channel Actions” section, there is an option labeled “Approve chaincode.”
Note: Each organization needs to approve the same chaincode definition to commit this chaincode on a channel. Only the peer and package ID are different for each organization.
Note: You cannot approve a chaincode definition twice. If an error appears while you’re trying to approve a chaincode, check to make sure that it has not been approved earlier.
Approve chaincode
To approve chaincode you need to fill in the following fields:
- Chaincode - Choose a chaincode from a drop-down menu.
- Peer - A peer node where this chaincode was installed earlier.
- Policy - Any type of policy, majority or all.
- Endorsers - Which organizations need to execute and validate the transaction output.
- Sequence - The number of times the chaincode was defined, automatically specified by the platform.
- Package ID - The package ID value is generated by the peer while installing the chaincode on the peer. It is automatically specified by the platform when you choose a peer in the field above.
- Init required checkmark - If you specify that Init is required, Fabric will ensure that the Init function is invoked before any other function in the chaincode and is only invoked once (to read more about init, please, refer to the Hyperledger Fabric documentation here).
- You can also add a private collection if needed. If you want to keep data private from other organizations on the channel, you can use private data collection instead of new channel creation. The private collection comprises the actual private data and a hash of that data. You can read more about private data collection here.
- Name - Any name can be given
- Block to live - Represents how long the data should live on the private database in terms of blocks. To keep private data indefinitely, meaning that the private data is not purged, set this property to 0.
- Required peer count - A minimum number of peers (across authorized organizations) that each endorsing peer must successfully disseminate private data to before the peer signs the endorsement and returns the proposal response to the client.
- Max peer count - The maximum number of peers.
- Members - You should also specify members who will have access to this private collection, and choose rights (read-only or write-only) according to your business rules.
- You can also choose Override chaincode policy to specify a policy to utilize for the collection. If this option is not chosen, the chaincode endorsement policy applies to the private collection. You can read more about all private collection fields in the official Hyperledger Fabric documentation here.
Once a sufficient number of channel members have approved a chaincode definition, one organization can commit the definition to the channel. The channel policy governs the number of organizations with endorser rights that need to approve a definition before it can be successfully committed to the channel.
Note: Only an organization with endorser rights on the particular channel, who approved this chaincode definition earlier, can commit it.
Commit chaincode
To commit a chaincode on a channel, go to the “Channels” tab and open the specific channel to commit the chaincode. Under the “Channel Actions” section, there is an option labeled “Commit chaincode.” Select the chaincode from the dropdown menu and the peer where it is installed, and click the “Submit” button.
After the chaincode is successfully committed, it will be displayed in the “Chaincodes” section. Chaincode can be queried or invoked.
Invoke chaincode
You can upgrade a chaincode using the same Hyperledger Fabric lifecycle process as you used to install and start the chainocode. You can upgrade the chaincode binaries or only update the chaincode policies.
Follow these steps to upgrade a chaincode.
- 1.Add a new chaincode version to the platform (as described in the “Adding chaincode” section). You should add the same name as the chaincode you want to upgrade and specify a new version.
- 2.Install the new chaincode package on your peers.
- 3.Approve a new chaincode definition.
- 4.Commit the definition to the channel.
If you want to update the chaincode policies, you can skip Steps 1 and 2 and just approve and commit the same chaincode with a new policy.
When a sufficient number of channel members regarding the channel policy have approved the new chaincode definition, one organization can commit the new definition to upgrade the channel's chaincode definition.
Note: Only an organization with endorser rights on the particular channel, who approved this chaincode definition earlier, can commit it.
You can delete a chaincode template by clicking on the remove button present under the actions column inside the Chaincodes action table.
However, deleting a chaincode will remove the chaincode template from the list, and the chaincode will still exist on the network if the peers on which the chaincode was installed are still running.
Last modified 2yr ago