In Hyperledger Fabric, chaincode (also known as smart contract) is a program written in Go, Node.js, or Java, primarily used to manipulate data on the ledger. A complete Fabric blockchain application has two parts: the client application and the chaincode. The application calls chaincode through peer nodes, and the chaincode reads and writes ledger data through those same peer nodes.
To interact with a Fabric peer node from your application, use one of these two methods:
Fabric SDK — Fabric's native client library. See the Fabric SDK documentation for details.
Alibaba Cloud BaaS API — The API provided by Alibaba Cloud BaaS to interact with the Fabric peer.
Chaincode lifecycle
After writing a chaincode, you must complete a series of lifecycle operations before it can process transactions on the network. The exact steps differ between Fabric 1.x and Fabric 2.x.
In the Alibaba Cloud BaaS console, you can upload, install, and instantiate chaincodes without using the command line.
Fabric 1.x lifecycle
| Step | Command | Description |
|---|---|---|
| 1 | package | Package the chaincode into a deployable archive |
| 2 | install | Install the packaged chaincode on peer nodes |
| 3 | instantiate | Instantiate the installed chaincode on a channel |
| 4 | upgrade | Upgrade the chaincode as requirements change |
Fabric 2.x lifecycle
Fabric 2.x introduces a decentralized governance model: multiple organizations must approve a chaincode definition before it becomes active on the channel.
| Step | Command | Description |
|---|---|---|
| 1 | package | Package the chaincode |
| 2 | approveformyorg | Approve the chaincode definition for your organization |
| 3 | commit | Commit the chaincode definition to the channel — takes effect after more than half of the channel members approve |
Chaincode types
Hyperledger Fabric has two categories of chaincode: system chaincode and user chaincode.
System chaincode
System chaincodes handle the internal processing logic of Fabric nodes, including system configuration, endorsement, and verification. They are written exclusively in Go and are registered and deployed automatically when a peer node starts. Installation, instantiation, and upgrade do not apply to system chaincodes.
The three main system chaincodes are:
| System chaincode | Abbreviation | Description |
|---|---|---|
| Lifecycle System Chaincode | LSCC | Manages the lifecycle of user chaincodes. |
| Configuration System Chaincode | CSCC | Manages channel configuration on each peer. |
| Query System Chaincode | QSCC | Provides a ledger query API to retrieve block and transaction information. |
User chaincode
User chaincodes contain the business logic written by application developers. They are written in Go, Node.js, or Java, run in a chaincode container, and interact with the ledger through Fabric's chaincode interfaces.
User chaincode directly accepts calls from application business logic and performs reads and writes on ledger data.
Endorsement policy
Every smart contract has an endorsement policy that specifies which organizations must approve a transaction before it is considered valid. Specify the endorsement policy when you upload and instantiate a chaincode.
Examples:
OR ('Org1MSP.peer','Org2MSP.peer')— either organization can endorse the transaction.AND ('Org1MSP.peer','Org2MSP.peer')— both organizations must endorse the transaction.
For the full policy syntax reference, see Fabric design > Endorsement policies.
Transaction execution process
Every transaction in Hyperledger Fabric goes through a four-step execute-order-validate flow involving peer nodes, orderer nodes, CA nodes, and clients.
Roles:
| Node | Role |
|---|---|
| Peer node | Stores the complete ledger, executes smart contracts, verifies blocks and transactions, and commits valid transactions to the ledger. |
| Orderer node | Receives endorsed transactions, sorts them, and packages them into new blocks to ensure a consistent ledger state across all peer nodes. |
| CA node | Issues certificates to every node and client for identity verification during transactions. |
| Client | Initiates transactions through the Fabric SDK. |
Steps:
The transaction execution flow chart is from the Fabric community's open source technical documentation, licensed under the Creative Commons Attribution 4.0 International License.
Proposal — The client sends a transaction proposal to the endorsing peer nodes specified by the endorsement policy. In the example above, the policy requires Peer1, Peer2, and Peer3 to participate.
Execution and signing — Each peer node executes the chaincode, signs the result, and returns the signed output to the client.
Submission to orderer — The client packages all execution results together with the endorsements from each peer (including their voting results and endorsement signatures) and sends them to the orderer node.
Ordering, block creation, and commit — The orderer sorts transactions and packages them into a new block, then broadcasts the block to all peer nodes. Each peer verifies that the transaction signatures satisfy the endorsement policy and that the read-write set matches the current ledger version. Transactions that pass both checks are written to the local ledger.
For more information, see Fabric design > Transaction process.
Usage notes
Cross-channel calls: read-only
When the called chaincode is in a different channel than the calling chaincode, only read queries are allowed. The called chaincode does not participate in the read-write set validation during the commit phase.
Same-channel calls: shared transaction
When the called chaincode and the calling chaincode are in the same channel, the read-write set generated by the called chaincode is merged into the calling chaincode's transaction. Both chaincodes share a single transaction rather than generating separate ones.
Chaincode shim package dependency
Chaincode communicates with peer nodes through the shim package (ChainCodeStub). By default, when you instantiate and compile a chaincode, the peer node supplies a shim package that matches the node version.
If your chaincode depends on a specific compatible version of the shim package (v1.4.x), bundle it inside the chaincode package.
Node version reference:
| Creation date | Node version |
|---|---|
| Before April 29, 2020 | v1.4.2 |
| After April 29, 2020 | v1.4.5 |
Golang dependencies:
| Version | Packages |
|---|---|
| v1.4.2 (old) | github.com/hyperledger/fabric/core/chaincode/shim, github.com/hyperledger/fabric/protos/peer |
| v1.4.5 (new) | github.com/hyperledger/fabric-chaincode-go/shim, github.com/hyperledger/fabric-protos-go/peer |
Java dependencies:
fabric-chaincode-shim-1.4.x.jarfabric-chaincode-protos-1.4.x.jar