Hyperledger Fabric on Kaleido

Hyperledger Fabric is an open source blockchain protocol custom designed for enterprise use cases on a permissioned blockchain network. As part of the Hyperledger project of the Linux Foundation, Fabric is the most widely used blockchain protocol in the umbrella project with the widest overall community participation.

If you want to learn more about what it is, what it's for, and whether it's right for your project read our guide on the basics of Hyperledger Fabric. You can also get started by following our Fabric quick start guide.

Kaleido supports Hyperledger Fabric version 2.3 and Fabric CA version 1.4 as of release 1.0.45. Read below for details on how Hyperledger Fabric works on Kaleido.

Entitlement

All accounts at all plan levels are able to provision Fabric environments. As with all other platform features, it is free in the starter plan. For pricing in the higher plan tiers, please check out the pricing page.

Only small node sizes are offered at the moment, with the following resource allocations:

If you have a need for higher resource allocations, please contact us via support@kaleido.io.

Multi-Region Environments

All Fabric environments on Kaleido are multi-region compatible by default. Depending on your subscription tier you will be able to add multiple regions and clouds to any Fabric environment. If you create an environment with a single initial deployment zone, you can still dynamically add additional deployment zones at any time.

Note that, due to the latency sensitivity of the Raft protocol, the orderer nodes are limited to a single deployment zone.

Managed Membership CAs

For each membership inside Fabric environments, Kaleido automatically provisions a Fabric CA instance when the first orderer of the membership is created. These certificate authorities are bootstrapped with a self-signed root certificate, or can be configured to be an intermediate CA, and use an embedded Sqlite database.

Managed Fabric Orderers

Every customer Fabric orderer node is automatically enrolled with the membership's CA, and joined in the global channel default-channel.

Managed Peer Nodes

Every customer Fabric peer node is automatically enrolled with the membership's CA, and joined in the global channel default-channel.

State Databases

Kaleido allows you to select between two choices for state databases used by peer nodes, LevelDB and CouchDB. State databases are chosen at environment creation step and cannot be changed after the creation of said environment. Furthermore, all peer nodes created will use the same state database previously selected.

LevelDB is the default state database embedded into Peer nodes runtimes which provides standard key/value pairs data mapping.

CouchDB is an optional seperate runtime database used by peer nodes that provides the ability to model data on the ledger in the form of JSON. Likewise, this allows users to query large amounts of data using chaincode deployed with indexes rather than just keys against the ledger.

A Global Channel Ready To Use

Every Fabric environment comes with a global channel, named default-channel, that contains all the orderers and peers from all memberships that provisioned any nodes to the environment. This makes Fabric environments ready to use as soon as the orderers and peers are started.

The default channel is defined with an administrative policy of single signature endorsement from the system membership, a special membership created for each individual environment that operates the system monitor node. The system monitor node is hidden behind the scenes to approve new orderers and peers joining the default channel (as well as leaving it when they get deleted). It also maintains the responsibility for approving and committing Chaincodes that are deployed to the default channel.

User-Created Channels

For use cases that require a channel with specific memberships, Kaleido also offers streamlined channel creation support. Creating a channel is as easy as selecting the participating memberships, after which Kaleido performs the complex orchestration behind the scenes to generate the channel's genesis block, and makes updates to the channel configurations in order to add the orderers and peers from the memberships to the channel.

All the orderers and peers of each participating memberships are joined to a channel that the membership is part of, rather than allowing a designation of individual nodes to join. This simplifies the mental model of managing channels.

All channels in Kaleido, including user-created channels and the default-channel, are currently configured to have the following policies by default:

• Channel/Admins: Channel-wide settings administration. MAJORITY Admins.
• Channel/Readers: Channel-wide settings read. ANY Readers.
• Channel/Writers: Channel-wide settings write. ANY Writers.
• Channel/Application/Admins: Application membership administration. Single ADMIN signature from the orchestrator membership, which is the membership that originally created the channel. This governs the top level updates such as adding new memberships to the configuration groups for peers.
• Channel/Application/Readers: Application membership read. ANY Readers.
• Channel/Application/Writers: Application membership write. ANY Writers.
• Channel/Application/LifecycleEndorsement: Application (chaincode) lifecycle endorsement. ANY Endorsement.
• Channel/Application/Endorsement: Application (chaincode) endorsement. MAJORITY Endorsement for user-created channels. ANY Endorsement for the default-channel.
• Channel/Orderer/Admins: Orderer service membership administration. Single ADMIN signature from the orchestrator membership, which is the membership that originally created the channel. This governs the top level updates such as adding new memberships to the configuration groups for the orderer service, adding new consenters for orderer nodes, etc.
• Channel/Orderer/Readers: Orderer service membership read. ANY Readers.
• Channel/Orderer/Writers: Orderer service membership read. ANY Writers.
• Channel/Orderer/BlockValidation: Channel Block Signing Threshold. ANY Writers.

When creating a channel, any of the policies described above can be overriden with a policy of the user's choice. As of the latest Kaleido release, custom policies are only supported via the platform API. An example channel creation request with custom policies may look like the following:

Channel creation goes through these stages:

• Creating: The membership that initiated the channel creation is preparing the genesis block and joining its own orderers to the new channel.
• Updating: All the other orderers and peers in the channel memberships are told about the new channel and are being joined to it.
• Live: All the existing orderers and peers are successfully joined to the new channel.

The System Membership

The system membership can also be added to a channel. The system membership is a built-in membership for every Kaleido environment, which operates the System Monitor node.

Adding the system membership to a channel can be a useful cost-saving mechanism when operating bilateral channels. Each Fabric channel runs as an individual cluster governed by Raft consensus. To achieve crash fault tolerance, a Raft cluster must have at least three participants. Including the system membership when creating a bilateral channel saves the channel's participating members from having to contribute an additional orderer and incurring additional costs.

Adding the system membership to your channel is simple. When creating your channel:

• In the UI: Add the System membership when adding channel members.
• In the API: Specify sys--mon as a participant membership ID. (Note: The value sys--mon contains two hyphens.)

The system membership is always part of the default channel.

Channel Management - Adding/Deleting Members

After a channel is created, additional members can be added to it. Kaleido will orchestrate the channel configuration update and join the new member's orderer and peer nodes to the channel. The entire process can be initiated with a single button click or an API call.

To add a member via the UI, navigate to "Environment" -> "Address Book" -> "Channels" and select your desired channel. From there, navigate to "Members" and click "Add Member". Then select the members you wish to add.

To delete a member, click the trashcan icon when highlighted. There must be at least 1 membership in the channel.

Chaincode Management

Kaleido's contract management supports Fabric chaincode deployment. With click of a few buttons, or calling a few APIs if you prefer that way, you can easily deploy your Chaincodes to your Fabric peer nodes and have them automatically approved for your org, and committed in the channel.

Uploading Chaincode Binary

Before deploying a Chaincode to a Fabric channel, you need to upload the Chaincode to Kaleido's Smart Contract Management system. Kaleido currently supports Golang binary executables and node.js project source archives.

• for Golang binary chaincodes, build your Golang chaincode implementation and make a note of the resulting binary. You must make sure the target OS for the compiler is set to linux, and the target architecture is set to amd64.

  Here's an example build command: GOOS=linux GOARCH=amd64 go build -o asset_transfer.bin

• for node.js chaincodes, zip up your node.js project directory, making sure the node_modules subfolder is NOT included. It's important that the resulted archive file has a single top-level directory, with all the chaincode resources contained in it.

Under the navigation heading, select "Network -> Apps -> Add New App". Select Hyperledger Fabric and select the contract type matching your Chaincode. The name of the contract project should follow the naming conventions of Fabric Chaincodes.

Once inside the new contract project, you are ready to upload the Chaincode. Select "Create New Version" and select the Chaincode package to upload. For the Description field, provide a version string because this value is used as the Chaincode version. For example, specify v1 as the initial version of the Chaincode.

Use the Require initialization before invocation checkbox to set the default value of the Chaincode's requirement for initialization before invocation. This corresponds to the --init-required parameter in the approveformyorg and commit phases of the Fabric Chaincode lifecycle that Kaleido will execute during the deploy step. The value you set here will become the default value during the Chaincode deployment step, thus preserving your preference for other users who may deploy this Chaincode.

Click "Finish" to upload the chaincode. You can see the results in the "Versions" section of the App Details page.

Private Data Collections

If the chaincode implementation uses private data collections, this can be configured when the chaincode is uploaded. Presently this can only be configured with API. Refer to the /compiled_contracts API documentation for more details.

The list of collection definitions can be specified under the property private_data_collections in the POST request payload.

If the collection uses query indexes for couchdb, the index defintions can be configured along with the collection definition. Under each collection definition entry, add an indexes property and set it to the array of indexes. Each index definition will be packaged in the folder META-INF/statedb/couchdb/collections/<collection_name>/indexes in a file named <index>.json when the chaincode is deployed.

NOTE: Support to add the private data collection definition via the Kaleido console UI is coming soon.

CouchDB Indexes

If the chaincode makes queries that rely on CouchDB indexes, the index definitions can be configured when the chaincode is uploaded. Presently this can only be configured with API. Refer to the /compiled_contracts API documentation for more details.

The list of index definitions can be specified under the property couchdb_indexes in the POST request payload.

Each index definition will be packaged in the folder META-INF/statedb/couchdb/indexes in a file named <index>.json when the chaincode is deployed.

NOTE: Support to add CouchDB index definitions via the Kaleido console UI is coming soon.

Promoting Chaincodes

The Chaincode binary and metadata needs to be pushed from the business network level to each individual environment that needs to use it. This process is accomplished with the "Promote" operation.

Select the Chaincode version and click the "Promote To Environment" button. Select the target Fabric environment and click "Finish". This operation makes the Chaincode available for deployment in the subsequent step.

Deploying Chaincodes to a Channel

Per the Fabric protocol, a Chaincode must go through these steps to become available in a channel: install, approve and commit. Kaleido uses sophisticated cross-membership coordination such that the complicated process is wrapped up behind a single API call or a button click in the console UI. The platform also manages the Chaincode definition's sequence numbers based on the version progression of the compiled contract construct described above.

• Install: The Chaincode will be installed on each peer node for each member of the channel.
• Approve: Kaleido's control plane calculates the proper sequence number for the Chaincode definition, based on information captured from the API calls. One of the orderers in each channel member will approve the Chaincode definition for the organization.
• Commit: One of the orderers in the target channel's initiator membership will commit the Chaincode definition in the channel, to make it fully instantiated and ready to handle transaction requests.

This step can be repeated to deploy the Chaincode to other user-created channels.

Navigate to "Environment -> Channels" and select the target channel for the Chaincode deployment. Select the "Chaincodes" tab on the left navigation bar, and then click the "Add Chaincode" button.

Note that this step allows you to override the default value of Require initialization before invocation that was provided during the Chaincode upload step.

Once the deployment process has completed, you will see your Chaincode listed in the "Chaincodes" tab of the channel details.

Verifying Chaincode Instantiation In Channel

To verify that the newly deployed Chaincode is fully approved and committed, and ready to receive invocations in the channel, go to the Logs view of a peer node and look for this line in the log (or search for the keyword lifecycle):

2021-06-08 02:58:12.541 UTC [lifecycle] update -> INFO 086 Chaincode with package ID 'asset_transfer-v1.u0ygf7gk4t:046eefc440e615dc30553347383e49b2cfaf5f1d58befecb092376aa8db68cad' now available on channel default-channel for chaincode definition asset_transfer:v1.u0ygf7gk4t

Note that for node.js/typescript based Chaincodes, the time from deployment to fully available can be a couple of minutes or longer, due to the module install and build steps.

Blockchain Explorer

The Hyperledger Blockchain Explorer has been integrated in every peer node in the Kaleido console. When in the dashboard of a Fabric peer node, note the card in the upper right corner for launching the explorer.

Click the "Open Web UI" button to open the explorer UI and use the credentials displayed in the card to login.

Sending Requests to Orderers and Peers

Kaleido's Fabric orderer and peer nodes use mutual TLS for securing the endpoints. For a client application to communicate with a Fabric orderer or peer node, these TLS and digital signing related artifacts must be prepared:

• TLS CA certificates: In order to establish trust to the remote targets, TLS CA certs are required per membership. These certificates can be downloaded from Kaleido's console under "Manage Resources -> Blockchain -> Certificate Authorities", for each of the memberships participating in the channel.
• MSP Identity key and certificate: Besides TLS, a client also needs to have the MSP identity key and certificate in order to sign transaction payloads. This is accomplished in two steps. First register the identity with the membership's Fabric CA using the "Certificate Authorities" panel or by calling the Kaleido platform API endpoint described below. The resulting enrollment secret can then be used by the client to enroll with the Fabric CA service.
• TLS client key and certificate: For mutual TLS communications, the client must present the client key and certificate. The same MSP identity key and cert from above can be used for this purpose.

Registering Identities in Kaleido UI

To register identities via the UI, navigate to "Manage Resources -> Blockchain -> Certificate Authorities". Select the CA under which you will register the client, then click "Create New Identity".

Provide an arbitrary username (user001 for example) and select "Client" as the role.

After the user is created, store the client secret in a safe place for later usage.

Registering Identities with Kaleido API

Clients that want to automate the enrollment steps can use the platform's API endpoint:

POST https://console.kaleido.io/api/v1/fabric-ca/:fabric-ca-id/register

using the following payload to register:

{
"registrations": [{
    "enrollmentID": "user001",
    "role": "client" }]
}

Enrollment secrets will be returned in the response:

{
  "registrations": [
    {
      "enrollmentID": "user001",
      "role": "client",
      "maxEnrollments": 1,
      "enrollmentSecret": "[secret]"
    }
  ],
  "errors": []
}

Enroll The Identity

The enrollment secrets can then be used in calls to the Fabric CA using a SDK module such as fabric-ca-client:

const FabricCAClient = require('fabric-ca-client');

const caClient = new FabricCAClient(`${caUrl}:443`, { verify: false });
const result = await caClient.enroll({
  enrollmentID: '[arbitrary-id]',
  enrollmentSecret: [secret],
  csr: csrPEM
});
const clientCert = result.certificate;

The URL to the Fabric CA can be obtained from the Kaleido Console UI in panel of the Certificate Authority entry, or programmatically using the Kaleido platform API.

Sample Application

To see how a client application uses the combination of Kaleido API and Fabric SDKs, visit the Kaleido sample application that includes an application written in node.js and another in golang, using the Fabric node.js SDK and golang SDK respectively.

Learn More

For deeper understanding of Hyperledger Fabric, visit the Fabric documentation.