Hyperledger Fabric SDK for Node.js

Module: fabric-network

Overview

This module provides a higher level API for interacting with smart contracts, and is the recommended API for client applications to interact with smart contracts deployed to a Hyperledger Fabric blockchain network.

Note that administrative capabilities, such as installing and starting smart contracts, are not currently provided by this API. For only specific advanced usage, the lower level fabric-common API can be used. Access to related fabric-common objects is provided through the fabric-network API objects.

If migrating a client application from an earlier version of the API, consult the migration tutorial for details of potentially breaking changes and recommended actions.

TypeScript definitions are included in this module.

Getting started

The entry point used to interact with a Hyperledger Fabric blockchain network is the Gateway class. Once instantiated, this long-living object provides a reusable connection to a peer within the blockchain network, and enables access to any of the blockchain Networks (channels) for which that peer is a member. This in turn provides access to Smart Contracts (chaincode) running within that blockchain network, and to which Transactions can be submitted or queries can be evaluated.

Private data can be submitted to transactions as transient data to prevent it from being recorded on the ledger.

Client applications can initiate actions or business processes in response to chaincode events emitted by smart contract transactions using smart contract event listeners. All updates to the ledger can be observed using block event listeners.

Example

// Connect to a gateway peer
const connectionProfileJson = (await fs.promises.readFile(connectionProfileFileName)).toString();
const connectionProfile = JSON.parse(connectionProfileJson);
const wallet = await Wallets.newFileSystemWallet(walletDirectoryPath);
const gatewayOptions: GatewayOptions = {
    identity: 'user@example.org', // Previously imported identity
    wallet,
};
const gateway = new Gateway();
await gateway.connect(connectionProfile, gatewayOptions);

try {

    // Obtain the smart contract with which our application wants to interact
    const network = await gateway.getNetwork(channelName);
    const contract = network.getContract(chaincodeId);

    // Submit transactions for the smart contract
    const args = [arg1, arg2];
    const submitResult = await contract.submitTransaction('transactionName', ...args);

    // Evaluate queries for the smart contract
    const evalResult = await contract.evaluateTransaction('transactionName', ...args);

    // Create and submit transactions for the smart contract with transient data
    const transientResult = await contract.createTransaction(transactionName)
        .setTransient(privateData)
        .submit(arg1, arg2);

} finally {
    // Disconnect from the gateway peer when all work for this client identity is complete
    gateway.disconnect();
}

Classes

DefaultCheckpointers
FabricError
Gateway
HsmX509Provider
IdentityProviderRegistry
TimeoutError
Transaction
TransactionError
Wallet
Wallets

Type Definitions

<async> BlockListener(event)

A callback function that will be invoked when a block event is received.
Parameters:
Name Type Description
event module:fabric-network.BlockEvent A block event.
Returns:
Type
Promise.<void>

CommitListener( [error] [, event])

A callback function that will be invoked when either a peer communication error occurs or a transaction commit event is received. Only one of the two arguments will have a value for any given invocation.
Parameters:
Name Type Argument Description
error module:fabric-network.CommitError <optional>
 Peer communication error.
event module:fabric-network.CommitEvent <optional>
 Transaction commit event from a specific peer.

<async> ContractListener(event)

A callback function that will be invoked when a block event is received.
Parameters:
Name Type Description
event module:fabric-network.ContractEvent Contract event.
Returns:
Type
Promise.<void>

DefaultEventHandlerStrategies

Properties:
Name Type Description
MSPID_SCOPE_ALLFORTX module:fabric-network.TxEventHandlerFactory Listen for transaction commit events from all peers in the client identity's organization. If the client identity's organization has no peers, this strategy will fail. The submitTransaction function will wait until successful events are received from all currently connected peers (minimum 1).
MSPID_SCOPE_ANYFORTX module:fabric-network.TxEventHandlerFactory Listen for transaction commit events from all peers in the client identity's organization. If the client identity's organization has no peers, this strategy will fail. The submitTransaction function will wait until a successful event is received from any peer.
NETWORK_SCOPE_ALLFORTX module:fabric-network.TxEventHandlerFactory Listen for transaction commit events from all peers in the network. The submitTransaction function will wait until successful events are received from all currently connected peers (minimum 1).
NETWORK_SCOPE_ANYFORTX module:fabric-network.TxEventHandlerFactory Listen for transaction commit events from all peers in the network. The submitTransaction function will wait until a successful event is received from any peer.
PREFER_MSPID_SCOPE_ALLFORTX module:fabric-network.TxEventHandlerFactory Listen for transaction commit events from all peers in the client identity's organization. If the client identity's organization has no peers, listen for transaction commit events from all peers in the network. The submitTransaction function will wait until successful events are received from all currently connected peers (minimum 1).
PREFER_MSPID_SCOPE_ANYFORTX module:fabric-network.TxEventHandlerFactory Listen for transaction commit events from all peers in the client identity's organization. If the client identity's organization has no peers, listen for transaction commit events from all peers in the network. The submitTransaction function will wait until a successful event is received from any peer.
NONE module:fabric-network.TxEventHandlerFactory Do not wait for any commit events. The submitTransaction function will return immediately after successfully sending the transaction to the orderer.

DefaultQueryHandlerStrategies

Properties:
Name Type Description
MSPID_SCOPE_SINGLE module:fabric-network.QueryHandlerFactory Query any one of the peers for the connected organization. Continue to use the same event service for all queries unless it fails. If the client identity's organization has no peers, this strategy will fail.
MSPID_SCOPE_ROUND_ROBIN module:fabric-network.QueryHandlerFactory Query any one of the peers for the connected organization. Use the next available peer for each successive query. If the client identity's organization has no peers, this strategy will fail.
PREFER_MSPID_SCOPE_SINGLE module:fabric-network.QueryHandlerFactory Query any one of the peers for the connected organization. If the connected organization has no peers, query any one of the peers in the network. Continue to use the same event service for all queries unless it fails.
PREFER_MSPID_SCOPE_ROUND_ROBIN module:fabric-network.QueryHandlerFactory Query any one of the peers for the connected organization. If the connected organization has no peers, query any one of the peers in the network. Use the next available peer for each successive query.

EventType

The type of an event. The type is based on the type of the raw event data: filtered, full block or including private data. The presence of optional fields and the type of raw protobuf data associated with events is dictated by this value.
Type:
  • 'filtered' | 'full' | 'private'

QueryHandlerFactory(network)

Factory function to obtain query handler instances. Called on every network creation.
Parameters:
Name Type Description
network module:fabric-network.Network The network on which queries are being evaluated.
See:
Returns:
A query handler.
Type
module:fabric-network.QueryHandler

TxEventHandlerFactory(transactionId, network)

Factory function to obtain transaction event handler instances. Called on every transaction submit.
Parameters:
Name Type Description
transactionId string The ID of the transaction being submitted.
network module:fabric-network.Network The network on which this transaction is being submitted.
See:
Returns:
A transaction event handler.
Type
module:fabric-network.TxEventHandler