Fabric

Overview¶

This page introduces the Fabric adapter that utilizes the Common Connection Profile (CCP) feature of the Fabric SDK to provide compatibility and a unified programming model across different Fabric versions.

The adapter exposes many SDK features directly to the user callback modules, making it possible to implement complex scenarios.

Installing dependencies¶

You must bind Caliper to a specific Fabric SDK to target the corresponding (or compatible) SUT version. Refer to the binding documentation for details. When you bind to an SUT, you are in fact selecting a specific Fabric SDK to use which could be used with different versions of Fabric SUTs.

Binding with Fabric 1.4 Client SDK¶

To bind with this client sdk, use fabric:1.4. Do not use this binding if using the BFT Concensus mechanism in Hyperledger Fabric that was introduced in version 3.0.0, use fabric:fabric-gateway instead.

It is confirmed that a 1.4 Fabric SDK is compatible with a Fabric 2.2 and later Fabric 2.x SUTs, therefore this binding can be used with later Fabric SUTs

Note that when using the binding target for the Fabric SDK 1.4 there are capability restrictions:

Binding with Fabric 2.2 Client SDK¶

To bind with this client sdk, use fabric:2.2. Do not use this binding if using the BFT Concensus mechanism in Hyperledger Fabric that was introduced in version 3.0.0, use fabric:fabric-gateway instead.

It is confirmed that a 2.2 Fabric SDK is compatible with 2.2 and later Fabric SUTs, therefore this binding can be used with 2.2 and later Fabric SUTs

Binding with Fabric Gateway Client SDK¶

To bind with this client sdk, use fabric:fabric-gateway. This is now the preferred SDK to use given that Fabric 2.2 and earlier are now not in LTS and as such the Fabric 1.4 and 2.2 SDKs are deprecated.

Only Fabric 2.4 and later with the Peer Gateway capability enabled (which is the default setting for a Fabric peer) can be used so for older versions of Hyperledger Fabric you cannot bind with this client SDK.

Connection Profiles¶

Connection Profiles are a Fabric standard that provides connectivity information for your Fabric network. In the past (Hyperledger Fabric 1.1) you needed to describe all your endpoints in a connection profile, ie all the orderers and all the peers in order to be able to connect a client application to the network. This is referred to as a static connection profile and when you use this connection profile with Caliper you should set the discover property to false. The problem with static connection profiles is that if a network topology changes (eg add/remove orderer, peer, organisation etc) then every client needs to have an updated connection profile.

Hyperledger Fabric in 1.2 introduced the concept of discovery. This allowed you to ask a peer for the network topology. Your Fabric network has to be configured correctly for this to work (but all Fabric networks should be configured to allow for discovery now). Connection profiles that use this capability will only have a list of 1 or more peers for the specific organisation that connection profile applies to which will be used to discover the network. These connection profiles are referred to as dynamic connection profiles and when you use this connection profile with Caliper you should set the discover property to true.

Network builders and providers should generate connection profiles (for example test-network in fabric-samples does this), however if you don’t have a connection profile you will need to create one. Information about creating connection profiles can be found in Hyperledger Fabric documentation as well as the node-sdk documentation (the format changed between node sdks. The 1.4 version should work when binding to either Fabric 1.4 or 2.2 but the version documented by 2.2 may only work when binding to Fabric 2.2)

• node sdk 2.2 documentation for connection profiles
• node sdk 1.4 documentation for connection profiles

Unfortunately the documentation provided by Hyperledger Fabric is more focused on static connection profiles rather than dynamic connection profiles and your aim should be to create the simpler and smaller dynamic connection profile.

With the introduction of using the Peer Gateway rather than the traditional node sdks (1.4 and 2.2) caliper has introduced the concept of declaring peers in an organization within the network configuration file as an alternative to connection profiles. This provides a simple way to describe either peers to discover from (when binding to Fabric 1.4 or 2.2, for Fabric 1.4 you must enable the gateway option as it won’t work otherwise as discovery is not supported with the Fabric 1.4 binding when the gateway option is not enabled) or the peer to be used as a gateway into the Fabric network (when binding to Fabric 2.4/fabric-gateway). An example of a peers section in the network configuration is

peers:
      - endpoint: peer0.org3.example.com:7051
        tlsCACerts:
          pem: |-
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
        grpcOptions:
          grpc.keepalive_timeout_ms: 20000
          grpc.keepalive_time_ms: 120000
          grpc.http2.min_time_between_pings_ms: 120000
          grpc.http2.max_pings_without_data: 0
          grpc.keepalive_permit_without_calls: 1

Runtime settings¶

Common settings¶

Some runtime properties of the adapter can be set through Caliper’s runtime configuration mechanism. For the available settings, see the caliper.fabric section of the default configuration file and its embedded documentation.

The above settings are processed when starting Caliper. Modifying them during testing will have no effect. However, you can override the default values before Caliper starts from the usual configuration sources. In the following example the localhost property applies only when binding with Fabric 2.2 or Fabric 1.4 (and only if the gateway option is enabled)

caliper:
    fabric:
        gateway:
          localhost: false

The connector API¶

The workload modules interact with the adapter at three phases of the tests: during the initialization of the user module (in the initializeWorkloadModule callback), when submitting invoke or query transactions (in the submitTransaction callback), and at the optional cleanup of the user module (in the cleanupWorkloadModule callback).

The initializeWorkloadModule function¶

See the corresponding documentation of the function for the description of its parameters.

The last argument of the function is a sutContext object, which is a platform-specific object provided by the backend blockchain’s connector. The context object provided by this connector is a FabricConnectorContext instance but this doesn’t provide anything of use at this time.

For the current details/documentation of the API, refer to the source code.

The submitTransaction function¶

The sutAdapter object received (and saved) in the initializeWorkloadModule function is of type [ConnectorInterface](https://github.com/hyperledger-caliper/caliper/blob/v0.6.0/packages/caliper-core/lib/common/core/connector-interface.js). Its getType() function returns the fabric string value.

The sendRequests method of the connector API allows the workload module to submit requests to the SUT. It takes a single parameter: an object or array of objects containing the settings of the requests.

The settings object has the following structure:

• contractId: string. Required. The ID of the contract to call. This is either the unique contractID specified in the network configuration file or the chaincode ID used to deploy the chaincode and must match the id field in the contacts section of channels in the network configuration file.
• contractFunction: string. Required. The name of the function to call in the contract.
• contractArguments: string[]. Optional. The list of string arguments to pass to the contract.
• readOnly: boolean. Optional. Indicates whether the request is a TX or a query. Defaults to false.
• transientMap: Map. Optional. The transient map to pass to the contract.
• invokerIdentity: string. Optional. The name of the user who should invoke the contract. If not provided, a user will be selected from the organization defined by invokerMspId or the first organization in the network configuration file if that property is not provided.
• invokerMspId: string. Optional. The mspid of the user organization who should invoke the contract. Defaults to the first organization in the network configuration file.
• targetPeers: string[]. Optional. An array of endorsing peer names as the targets of the transaction proposal. If omitted, the target list will be chosen for you and if discovery is used then the node SDK uses discovery to determine the correct peers.
• targetOrganizations: string[]. Optional. An array of endorsing organizations as the targets of the invoke. If both targetPeers and targetOrganizations are specified, then targetPeers will take precedence.
• channel: string. Optional. The name of the channel on which the contract to call resides.
• timeout: number. Optional. [Only applies to 1.4 binding when not enabling gateway use] The timeout in seconds to use for this request.
• orderer: string. Optional. [Only applies to 1.4 binding when not enabling gateway use] The name of the target orderer for the transaction broadcast. If omitted, then an orderer node of the channel will be automatically selected.

So invoking a contract looks like the following:

let requestSettings = {
    contractId: 'marbles',
    contractFunction: 'initMarble',
    contractArguments: ['MARBLE#1', 'Red', '100', 'Attila'],
    invokerIdentity: 'client0.org2.example.com',
    timeout: 10
};

await this.sutAdapter.sendRequests(requestSettings);

Gathered TX data¶

The previously discussed sendRequests function returns the result (or an array of results) for the submitted request(s) with the type of TxStatus. The class provides some standard and platform-specific information about its corresponding transaction.

The standard data provided are the following: - GetID():string returns the transaction ID. - GetStatus():string returns the final status of the transaction, either success or failed. - GetTimeCreate():number returns the epoch when the transaction was submitted. - GetTimeFinal():number return the epoch when the transaction was finished. - IsVerified():boolean indicates whether we are sure about the final status of the transaction. Unverified (considered failed) transactions could occur, for example, if the adapter loses the connection with every Fabric event hub, missing the final status of the transaction. - GetResult():Buffer returns one of the endorsement results returned by the chaincode as a Buffer. It is the responsibility of the user callback to decode it accordingly to the chaincode-side encoding.

The adapter also gathers the following platform-specific data (if observed) about each transaction, each exposed through a specific key name. The placeholders <P> and <O> in the key names are node names taking their values from the top-level peers and orderers sections from the network configuration file (e.g., endorsement_result_peer0.org1.example.com). The Get(key:string):any function returns the value of the observation corresponding to the given key. Alternatively, the GetCustomData():Map<string,any> returns the entire collection of gathered data as a Map.

Available data keys for all Fabric SUTs¶

The adapter-specific data keys that are available when binding to any of the Fabric SUT versions are :

Available data keys for the Fabric 1.4 SUT when gateway is not enabled¶

The adapter-specific data keys that only the v1.4 SUT when not enabling the gateway makes available are :

You can access these data in your workload module after calling sendRequests:

let requestSettings = {
    contractId: 'marbles',
    contractVersion: '0.1.0',
    contractFunction: 'initMarble',
    contractArguments: ['MARBLE#1', 'Red', '100', 'Attila'],
    invokerIdentity: 'client0.org2.example.com',
    timeout: 10
};

// single argument, single return value
const result = await this.sutAdapter.sendRequests(requestSettings);

let shortID = result.GetID().substring(8);
let executionTime = result.GetTimeFinal() - result.GetTimeCreate();
console.log(`TX [${shortID}] took ${executionTime}ms to execute. Result: ${result.GetStatus()}`);

The cleanupWorkloadModule function¶

The cleanupWorkloadModule function is called at the end of the round, and can be used to perform any resource cleanup required by your workload implementation.

Network configuration file reference¶

The YAML network configuration file of the adapter mainly describes the organizations and the identities associated with those organizations, It also provides explicit information about the channels in your Fabric network and the chaincode (containing 1 or more smart contracts) deployed to those channels. It can reference Common Connection Profiles for each organization (as common connection profiles are specific to a single organization). These are the same connection profiles that would be consumed by the node-sdk. Whoever creates the Fabric network and channels would be able to provide appropriate profiles for each organization.

The following sections detail each part separately. For a complete example, please refer to the example section or one of the files in the Caliper repository, such as the caliper-fabric test folder.

name: Fabric

version: '2.0.0'

 info:
   Version: 1.1.0
   Size: 2 Orgs with 2 Peers
   Orderer: Solo
   Distribution: Single Host
   StateDB: CouchDB

 organizations:
- mspid: Org1MSP
  identities:
    wallet:
      path: './org1wallet'
      adminNames:
      - admin
    certificates:
    - name: 'User1'
      clientPrivateKey:
        pem: |-
          -----BEGIN PRIVATE KEY-----
          ...
          -----END PRIVATE KEY-----
      clientSignedCert:
        pem: |-
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
  connectionProfile:
    path: './Org1ConnectionProfile.yaml'
    discover: true
- mspid: Org2MSP
  connectionProfile:
    path: './Org2ConnectionProfile.yaml'
    discover: false
  identities:
    wallet:
      path: './org2wallet'
      adminNames:
      - admin
- mspid: Org3MSP
  peers:
    - endpoint: peer0.org3.example.com:7051
      tlsCACerts:
        pem: |-
          -----BEGIN CERTIFICATE-----
          ...
          -----END CERTIFICATE-----
      grpcOptions:
        grpc.keepalive_timeout_ms: 20000
        grpc.keepalive_time_ms: 120000
        grpc.http2.min_time_between_pings_ms: 120000
        grpc.http2.max_pings_without_data: 0
        grpc.keepalive_permit_without_calls: 1

channels:
- channelName: mychannel
  contracts:
  - id: marbles
    contractID: myMarbles

- channelName: somechannel
  contracts:
  - id: basic

Network Configuration Example¶

The following example is a Fabric network configuration for the following network topology and artifacts:

• two organizations Org1MSP and Org2MSP (Note that having 2 organizations is not common in a network configuration file);
• one channel named mychannel;
• asset-transfer-basic chaincode deployed to mychannel with a chaincode id of basic;
• the nodes of the network use TLS communication, but not mutual TLS;
• the Fabric samples test network is started and terminated automatically by Caliper;

name: Fabric
version: "2.0.0"

caliper:
  blockchain: fabric
  sutOptions:
    mutualTls: false
  command:
    start: ../fabric-samples/test-network/network.sh up createChannel && ../fabric-samples/test-network/network.sh deployCC -ccp ../fabric-samples/asset-transfer-basic/chaincode-javascript -ccn basic -ccl javascript
    end: ../fabric-samples/test-network/network.sh down

info:
  Version: 1.1.0
  Size: 2 Orgs
  Orderer: Raft
  Distribution: Single Host
  StateDB: GoLevelDB

channels:
  - channelName: mychannel
    contracts:
    - id: basic
      contractID: BasicOnMyChannel

organizations:
  - mspid: Org1MSP
    identities:
      certificates:
      - name: 'admin.org1.example.com'
        admin: true
        clientPrivateKey:
          pem: |-
            -----BEGIN PRIVATE KEY-----
            ...
            -----END PRIVATE KEY-----
        clientSignedCert:
          pem: |-
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
    connectionProfile:
      path: './Org1ConnectionProfile.yaml'
      discover: true
  - mspid: Org2MSP
    connectionProfile:
    identities:
      certificates:
      - name: 'admin.org2.example.com'
        admin: true
        clientPrivateKey:
          pem: |-
            -----BEGIN PRIVATE KEY-----
            ...
            -----END PRIVATE KEY-----
        clientSignedCert:
          pem: |-
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
      path: './Org2ConnectionProfile.json'
      discover: true

Another example with only a single organization but using the peers property so everything required is contained in a single network configuration file:

name: Fabric
version: "2.0.0"

caliper:
  blockchain: fabric
  sutOptions:
    mutualTls: false

channels:
  - channelName: mychannel
    contracts:
    - id: basic

organizations:
  - mspid: Org1MSP
    identities:
      certificates:
      - name: 'admin.org1.example.com'
        admin: true
        clientPrivateKey:
          pem: |-
            -----BEGIN PRIVATE KEY-----
            ...
            -----END PRIVATE KEY-----
        clientSignedCert:
          pem: |-
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----
    peers:
      - endpoint: peer0.org1.example.com:7051
        grpcOptions:
          ssl-target-name-override: peer0.org1.example.com
          grpc.keepalive_time_ms: 600000
        tlsCACerts:
          pem: |-
            -----BEGIN CERTIFICATE-----
            ...
            -----END CERTIFICATE-----

License¶

The Caliper codebase is released under the Apache 2.0 license. Any documentation developed by the Caliper Project is licensed under the Creative Commons Attribution 4.0 International License. You may obtain a copy of the license, titled CC-BY-4.0, at http://creativecommons.org/licenses/by/4.0/.