Table of contents
2.1 Install and define chaincode
2.1.1 Packaging smart contracts
2.1.2 Peer node installs chain code
2.1.3 Organization approves chaincode
2.1.4 Submit the chaincode to the channel
1. What is chain code?
ChainCode is a program, written in Go , Node.js or Java , that implements a specified interface. ChainCode runs in a secure Docker container and is isolated from the endorsement node. ChainCode initializes and manages the ledger state through transactions submitted by the application.
Chaincode typically handles business logic agreed upon by network members and can therefore be considered a "smart contract". Updates to the ledger created by a chaincode are limited to that chaincode and cannot be directly accessed by other chaincodes. However, within the same network, if given the appropriate permissions, a chaincode can call another chaincode to access its state.
2. Deploy chain code
The Fabric chaincode lifecycle is a process that allows multiple organizations to agree on how to operate the chaincode before using it on the channel. We use the Fabric lifecycle to operate the deployment and operation of the chaincode:
2.1 Install and define chaincode
The Fabric chaincode lifecycle requires organizations to agree on the parameters that define the chaincode, such as name, version, and chaincode endorsement policy. Channel members agree through the following four steps, but not every organization on the channel needs to complete each step.
- Packaging smart contracts: This step can be completed by one organization or by each organization.
- Install the chaincode on the peer node: Each organization that wants to use the chaincode to endorse transactions or query the ledger needs to complete this step.
- Organization Approval of Chaincode: Each organization that will use chaincode needs to complete this step. The chaincode definition needs to be approved by a sufficient number of organizations to satisfy the channel's LifecycleEndorsement policy (default is majority) before the chaincode can be launched on the channel.
- Submitting the chaincode to the channel: Once the required number of organizations on the channel are approved, a transaction will be committed by one organization. The submitter first collects endorsements from enough peers from approved organizations and then submits a transaction to submit the chaincode.
2.1.1 Packaging smart contracts
The chaincode needs to be packaged in a tar file before it can be installed on the peer node. You can use the Fabric peer binary, the Node Fabric SDK, or a third-party tool (such as GNU tar) to package the chaincode. When you create a chaincode package, you need to provide a chaincode package tag to create a concise and readable package description.
If you use a third-party tool to package the chaincode, the generated file needs to be in the following format. The Fabric peer binaries and Fabric SDK will automatically create files in this format.
-
The chaincode needs to be packaged in a tar file, ending with a .tar.gz file extension.
-
The tar file needs to contain two files (no directories): a metadata file "metadata.json" and another tar "code.tar.gz" containing the chaincode file.
-
"metadata.json" contains JSON specifying the chaincode language, code path, and package tags. An example of a metadata file can be seen below:
{"Path":"fabric-samples/asset-transfer-basic/chaincode-go","Type":"golang","Label":"basicv1"}
The chain code is packaged by Org1 and Org2 respectively. Both organizations use MYCC_1 as their package label to identify packages using name and version. It is not necessary for organizations to use the same package labels.
2.1.2 Peer node installs chain code
Only peer nodes with chaincode installed can perform transactions and endorsement transactions. Whether it is CLI or SDK, you need to use Peer Administrator to complete this step. The chaincode will be built after it is installed, and if there is a problem with the chaincode, a build error will be returned. It is recommended that the organization only needs to package the chain code once, and then install the same chain code package on the peer nodes belonging to the organization that need to be installed. If the channel wants to ensure that each organization runs the same chain code, one organization will complete the packaging work and then send it to other members of the channel.
A successful install command will return a chaincode package identifier, which is a hashed combination of the package label and the package. This package identifier is used to associate the chaincode package installed on the peer node with the organization-approved chaincode definition. Save the identifier for the next step. It can also be found by querying the package installed on the peer using the Peer CLI. Package identifier.
The peer administrators of Org1 and Org2 install the chaincode package MYCC_1 on the peers joining the channel. Installing the chaincode package will build the chaincode and create a package identifier MYCC_1:hash.
2.1.3 Organization approves chaincode
When a channel member approves a chaincode definition, approval is determined by a vote of the organization that accepts the chaincode parameters. These approved organization definitions allow channel members to agree on chaincode before it is used on the channel. The chaincode definition includes the following parameters, which need to be consistent across organizations:
-
Name: The name the application will use when calling the chaincode.
-
Version: The version number or value associated with a given chaincode package. If you upgrade the chaincode binary, you will also need to change the chaincode version. The version can contain any characters, but usually uses a format such as v1.v2.v3. The peer node does not check the version, it is just an indicator designed to help the organization. Coordinate when updating its chaincode logic.
-
Sequence: The number of times the chain code is defined on the channel. This value is an integer used to track chaincode upgrades. For example, the first time a chaincode definition is approved and submitted on a channel, the sequence number must be set to 1. The next time the chaincode is upgraded or the chaincode definition is updated, the sequence number is increased to 2. The sequence number is used by the peer nodes to ensure that all organizations are in sync with their approved and submitted chaincode definitions.
-
Endorsement policy: Which organizations are required to execute and verify transaction outputs. Endorsement policies can be expressed as strings passed to the CLI, or they can reference policies in the channel configuration. By default, the endorsement policy is set to channel/Application/Endorsement, which requires most organizations in the channel to endorse the transaction.
-
Collection configuration: The path to the private data collection definition file associated with the chaincode. For more information about private data collections, see Private Data Schema Reference .
-
ESCC/VSCC plugin: The name of the custom endorsement or verification plugin to be used by the chaincode.
-
Initialization: If you use the low-level API provided by the Fabric ChainCode Shim API, the chaincode needs to include an Init function for initializing the chaincode. This function is required by the chaincode interface but does not necessarily need to be called by your application. When you approve the chaincode definition, you can specify whether Init must be called before calling it. If you specify that Init is required, Fabric will ensure that Init calls this function before any other function in the chaincode and only calls it once. Requesting execution of the Init function allows you to implement logic that runs when the chaincode is initialized, such as setting some initial state. Each time you increment the version of the chaincode, you need to call init to initialize the chaincode, assuming the chaincode defines the init required for incrementing the version indication.
The chaincode definition also includes the package identifier . This is a required parameter for every organization that wants to use chaincode. The package ID does not have to be the same for all organizations. Organizations can approve chaincode definitions without installing the chaincode or including the identifier in the definition.
Each channel member who wants to use chaincode needs to approve the chaincode definition for their organization. This approval needs to be submitted to the ordering service and then distributed to all peers. This approval needs to be submitted by your organization administrator . After the approval transaction is successfully submitted, the approved definition will be stored in a collection available to all peers in the organization. Therefore, even if you have multiple peers, your organization only needs to approve the chaincode once.
The organization administrators of Org1 and Org2 approve MYCC's chaincode definition for their organizations. The chaincode definition includes fields such as chaincode name, version, and endorsement policy. Since both organizations will use chaincode to endorse transactions, both organizations' approval definitions need to include packageID.
2.1.4 Submit the chaincode to the channel
Once a sufficient number of channel members approve a chaincode definition, an organization can submit the definition to the channel. Before committing a definition to a channel using the peer CLI, you can use the checkcommitreadiness command to check whether submitting a chaincode definition should succeed based on which channel members have approved the definition. Submitted transaction proposals are first sent to peers who are members of the channel, who query the chaincode definition approved by their organization and, if approved by their organization, endorse the definition. Then submit the transaction to the orderer, and then submit the chaincode definition to the channel. Submitting the definition transaction needs to be submitted as an administrator of the organization.
The number of organizations that need to approve definitions for successful submission to the channel is controlled by the Channel/Application/LifecycleEndorsement policy. By default, this policy requires a majority of organizations in the channel to endorse the transaction, and the LifecycleEndorsement policy is separate from the chaincode endorsement policy. For example, even if a chaincode endorsement policy only requires signatures from one or two organizations, a majority of channel members still need to approve the chaincode definition according to the default policy. When submitting a channel definition, you need to target enough peer organizations in the channel to satisfy your requirements. LifecycleEndorsement policy.
You can also set the Channel/Application/LifeCycleEndoseMent policy as a signing policy and explicitly specify the set of organizations on the channel that can approve the chaincode definition. This allows you to create a channel where a selected number of organizations act as chaincode administrators and manage the business logic used by the channel. You can also use a signing policy if your channel has a large number of Idemix organizations, which cannot approve the chaincode definition or endorse the chaincode and may therefore prevent the channel from reaching a majority.
An organization administrator from Org1 or Org2 submits the chaincode definition to the channel. The definition on the channel does not include packageID.
After the chaincode definition is submitted to the channel, the chaincode container will be started on all peers that have the chaincode installed, allowing channel members to start using the chaincode. The chaincode container may take a few minutes to start. You can use the chaincode Defined to require calling the Init function to initialize the chaincode. If the Init request calls a function, the first call of the chain code must be a call to the Init function. The call of the function Init is subject to the chain code endorsement policy.
2.2 Upgrade chain code
You can upgrade chaincode using the same Fabric lifecycle process as installing and launching chaincode. You can upgrade the chaincode binary, or just update the chaincode policy. Follow these steps to upgrade chaincode:
-
Repackage the chaincode: You only need to complete this step if you are upgrading the chaincode binaries.
Org1 and Org2 upgrade the chaincode binary and repackage the chaincode, both organizations use different packaging tags than before.
-
Install the new chaincode package on your peers: Again, you only need to complete this step if you are upgrading the chaincode binaries. Installing a new chaincode package will generate a package ID that needs to be passed to the new chaincode definition. You will also need to change the chaincode version, which is used by the lifecycle process to track whether the chaincode binary has been upgraded.
Org1 and Org2 install new packages onto their peers. Installation creates a new packageID.
-
Approve new chaincode definition: If you want to upgrade the chaincode binary, you need to update the chaincode version and package ID in the chaincode definition. You can also update your chaincode endorsement policy without repackaging your chaincode binary. Channel members simply approve the definition of the new policy, which requires incrementing the sequence variable in the definition .
The organization administrators of Org1 and Org2 approve the new chaincode definition for their respective organizations, the new definition references the new packageID and changes the chaincode version, increasing the sequence from one to two since this is the first update of the chaincode.
-
Submit definitions to the channel: When a sufficient number of channel members approve the new chaincode definition, an organization can submit the new definition to upgrade the chaincode definition to the channel as part of the lifecycle process, without a separate upgrade command.
The organization administrator of Org1 or Org2 submits the new chaincode definition to the channel.
After you commit the chaincode definition, a new chaincode container will be started with the code in the upgraded chaincode binary. If you request the execution of this function in the chaincode definition, you need to call this function again after the new definition is successfully submitted to initialize the upgraded chaincode. If the chaincode definition is updated without changing the chaincode version, the chaincode container will remain unchanged and you will not need to call the Init function.
After submitting the new definition to the channel, each peer will automatically start a new chaincode container.
The Fabric chaincode lifecycle uses sequences in the chaincode definition to track upgrades. All channel members need to increment the serial number and approve the new definition to upgrade the chaincode. The version parameter is used to track the chaincode binary and only needs to be changed when upgrading the chaincode binary.
Summarize
参考：Fabric chaincode lifecycle — hyperledger-fabricdocs main documentation