Class: Chain

Chain

The class representing a chain with which the client SDK interacts. The “Chain” object captures settings for a channel, which is created by the orderers to isolate transactions delivery to peers participating on channel. A chain must be initialized after it has been configured with the list of peers and orderers. The initialization sends a get configuration block request to the primary orderer to retrieve the configuration settings for this channel.

new Chain(name, clientContext)

Parameters:
Name Type Description
name string to identify different chain instances. The naming of chain instances is enforced by the ordering service and must be unique within the blockchain network
clientContext Client An instance of Client that provides operational context such as submitting User etc.
Tutorials:
  • Tutorial: app-overview

Methods


<static> buildTransactionID(nonce, userContext)

Utility method to build an unique transaction id based on a nonce and this chain's user.
Parameters:
Name Type Description
nonce int a one time use number
userContext User the user context
Returns:
An unique string
Type
string

addOrderer(orderer)

Add orderer endpoint to a chain object, this is a local-only operation. A chain instance may choose to use a single orderer node, which will broadcast requests to the rest of the orderer network. Or if the application does not trust the orderer nodes, it can choose to use more than one by adding them to the chain instance. All APIs concerning the orderer will broadcast to all orderers simultaneously.
Parameters:
Name Type Description
orderer Orderer An instance of the Orderer class.
Throws:
if the orderer with that url already exists.
Type
Error

addPeer(peer)

Add peer endpoint to chain.
Parameters:
Name Type Description
peer Peer An instance of the Peer class that has been initialized with URL, TLS certificate, and enrollment certificate.
Throws:
if the peer with that url already exists.
Type
Error

compareProposalResponseResults(The)

Utility method to examine a set of proposals to check they contain the same endorsement result write sets. This will validate that the endorsing peers all agree on the result of the chaincode execution.
Parameters:
Name Type Description
The Array.<ProposalResponse> proposal responses from all endorsing peers
See:
  • /protos/peer/proposal_reponse.proto
Returns:
True when all proposals compare equally, false otherwise.
Type
boolean

getChannelConfig()

Queries for the current config block for this chain(channel). This transaction will be made to the orderer.
See:
  • /protos/orderer/ab.proto
  • /protos/common/configtx.proto
Returns:
Object containing the configuration items.
Type
ConfigEnvelope

getGenesisBlock(request)

Will get the genesis block from the defined orderer that may be used in a join request
Parameters:
Name Type Description
request Object An object containing the following fields:
`txId` : required - String of the transaction id
`nonce` : required - Integer of the once time number
See:
  • /protos/peer/proposal_response.proto
Returns:
A Promise for a protobuf `Block`
Type
Promise

getMSPManager()

Get the MSP Manager for this channel
Returns:
Type
MSPManager

getName()

Get the chain name.
Returns:
The name of the chain.
Type
string

getOrderers()

Get orderers of a chain.

getOrganizations()

Get organization identifiers from the MSP's for this channel
Returns:
array of MSP identifiers representing the channel's participating organizations
Type
Array.<string>

getPeers()

Get peers of a chain from local information.
Returns:
The peer list on the chain.
Type
Array.<Peer>

getPrimaryPeer()

Get the primary peer The peer to use for doing queries. Default: When no primary peer has been set the first peer on the list will be used.
Returns:
peer An instance of the Peer class.
Type
Peer

initialize(config_update-)

Retrieve the configuration from the primary orderer and initializes this chain (channel) with those values. Optionally a configuration may be passed in to initialize this channel without making the call to the orderer.
Parameters:
Name Type Description
config_update- Array.<byte> Optional - A serialized form of the protobuf configuration update
Returns:
a Promise that will resolve when the action is complete

isReadonly()

Get chain status to see if the underlying channel has been terminated, making it a read-only chain, where information (transactions and states) can be queried but no new transactions can be submitted.
Returns:
Is read-only, true or not.
Type
boolean

joinChannel(request)

Sends a join channel proposal to one or more endorsing peers Will get the genesis block from the defined orderer to be used in the proposal.
Parameters:
Name Type Description
request Object An object containing the following fields:
`targets` : required - An array of `Peer` objects that will join this channel
`block` : the genesis block of the channel see getGenesisBlock() method
`txId` : required - String of the transaction id
`nonce` : required - Integer of the once time number
See:
  • /protos/peer/proposal_response.proto
Returns:
A Promise for a `ProposalResponse`
Type
Promise

queryBlock(blockNumber)

Queries the ledger for Block by block number. This query will be made to the primary peer.
Parameters:
Name Type Description
blockNumber number The number which is the ID of the Block.
Returns:
Object containing the block.
Type
object

queryBlockByHash(block)

Queries the ledger for Block by block hash. This query will be made to the primary peer.
Parameters:
Name Type Description
block Array.<byte> hash of the Block.
Returns:
Object containing the block.
Type
object

queryByChaincode(request)

Sends a proposal to one or more endorsing peers that will be handled by the chaincode. This request will be presented to the chaincode 'invoke' and must understand from the arguments that this is a query request. The chaincode must also return results in the byte array format and the caller will have to be able to decode these results
Parameters:
Name Type Description
request Object A JSON object with the following
targets : An array or single Endorsing Peer objects as the targets of the request
chaincodeId : The id of the chaincode to perform the query
`args` : an array of arguments specific to the chaincode 'innvoke' that represent a query invocation on that chaincode
`transientMap` : optional - map that can be used by the chaincode but not saved in the ledger, such as cryptographic information for encryption
Returns:
A Promise for an array of byte array results from the chaincode on all Endorsing Peers
Type
Promise

queryInfo()

Queries for various useful information on the state of the Chain (height, known peers). This query will be made to the primary peer.
Returns:
With height, currently the only useful info.
Type
object

queryInstantiatedChaincodes()

Queries the instantiated chaincodes on this channel.
Returns:
ChaincodeQueryResponse proto
Type
object

queryTransaction(transactionID)

Queries the ledger for Transaction by number. This query will be made to the primary peer.
Parameters:
Name Type Description
transactionID number
Returns:
Transaction information containing the transaction.
Type
object

removeOrderer(orderer)

Remove orderer endpoint from a chain object, this is a local-only operation.
Parameters:
Name Type Description
orderer Orderer An instance of the Orderer class.

removePeer(peer)

Remove peer endpoint from chain.
Parameters:
Name Type Description
peer Peer An instance of the Peer class.

sendInstantiateProposal(request)

Sends an instantiate proposal to one or more endorsing peers.
Parameters:
Name Type Description
request Object An object containing the following fields:
`targets` : Optional : An array of endorsing Peer objects as the targets of the request. The list of endorsing peers will be used if this parameter is omitted.
`chaincodeType` : optional -- Type of chaincode ['golang', 'car', 'java'] (default 'golang')
`chaincodePath` : required - String of the path to location of the source code of the chaincode
`chaincodeId` : required - String of the name of the chaincode
`chaincodeVersion` : required - String of the version of the chaincode
`txId` : required - String of the transaction id
`transientMap` : optional - map that can be used by the chaincode but not saved in the ledger, such as cryptographic information for encryption
`nonce` : required - Integer of the once time number
`fcn` : optional - String of the function to be called on the chaincode once instantiated (default 'init')
`args` : optional - String Array arguments specific to the chaincode being instantiated
`endorsement-policy` : optional - EndorsementPolicy object for this chaincode. If not specified, a default policy of "a signature by any member from any of the organizations corresponding to the array of member service providers" is used
See:
  • /protos/peer/proposal_response.proto
Returns:
A Promise for a `ProposalResponse`
Type
Promise
Examples

"Signed by any member from one of the organizations"

{
  identities: [
    { role: { name: "member", mspId: "org1" }},
    { role: { name: "member", mspId: "org2" }}
  ],
  policy: {
    "1-of": [{ "signed-by": 0 }, { "signed-by": 1 }]
  }
}

"Signed by admin of the ordererOrg and any member from one of the peer organizations"

{
  identities: [
    { role: { name: "member", mspId: "peerOrg1" }},
    { role: { name: "member", mspId: "peerOrg2" }},
    { role: { name: "admin", mspId: "ordererOrg" }}
  ],
  policy: {
    "2-of": [
      { "signed-by": 2},
      { "1-of": [{ "signed-by": 0 }, { "signed-by": 1 }]}
    ]
  }
}

sendTransaction(proposalResponses, chaincodeProposal)

Sends the orderer an endorsed proposal. The caller must use the proposal response returned from the endorser along with the original proposal request sent to the endorser.
Parameters:
Name Type Description
proposalResponses Array An array or single {ProposalResponse} objects containing the response from the endorsement
chaincodeProposal Proposal A Proposal object containing the original request for endorsement(s)
See:
  • /protos/peer/proposal_response.proto
  • /protos/peer/proposal.proto
  • /protos/orderer/ab.proto
Returns:
A Promise for a `BroadcastResponse`. This will be an acknowledgement from the orderer of successfully submitted transaction.
Type
Promise

sendTransactionProposal(request)

Sends a transaction proposal to one or more endorsing peers.
Parameters:
Name Type Description
request Object
`targets` : optional -- The peers that will receive this request, when not provided the peers assigned to this channel will be used.
`chaincodeId` : The id of the chaincode to perform the transaction proposal
`txId` : required - String of the transaction id
`nonce` : required - Integer of the once time number
`transientMap` : optional - map that can be used by the chaincode but not saved in the ledger, such as cryptographic information for encryption
`args` : an array of arguments specific to the chaincode 'invoke'
Returns:
A Promise for a `ProposalResponse`
Type
Promise

sendUpgradeProposal(request)

Sends an upgrade proposal to one or more endorsing peers.
Parameters:
Name Type Description
request Object An object containing the following fields:
`targets` : An array of endorsing Peer objects as the targets of the request
`chaincodeType` : optional -- Type of chaincode ['golang', 'car', 'java'] (default 'golang')
`chaincodePath` : required - String of the path to location of the source code of the chaincode
`chaincodeId` : required - String of the name of the chaincode
`chaincodeVersion` : required - String of the version of the chaincode
`txId` : required - String of the transaction id
`transientMap` : optional - map that can be used by the chaincode but not saved in the ledger, such as cryptographic information for encryption
`nonce` : required - Integer of the once time number
`fcn` : optional - String of the function to be called on the chaincode once instantiated (default 'init')
`args` : optional - String Array arguments specific to the chaincode being instantiated
See:
  • /protos/peer/proposal_response.proto
Returns:
A Promise for a `ProposalResponse`
Type
Promise

setMSPManager(the)

Set the MSP Manager for this channel This utility method will not normally be use as the `initialize()` method will read this channel's current configuration and reset MSPManager with the MSP's found.
Parameters:
Name Type Description
the MSPManager msp manager for this channel

setPrimaryPeer(peer)

Set the primary peer The peer to use for doing queries. Peer must be a peer on this chain's peer list. Default: When no primary peer has been set the first peer on the list will be used.
Parameters:
Name Type Description
peer Peer An instance of the Peer class.
Throws:
Error when peer is not on the existing peer list

toString()

return a printable representation of this object

verifyProposalResponse(The)

Utility method to verify a single proposal response. Requires that the initialize method of this channel has been executed to load this channel's MSPs. The MSPs will have the trusted root certificates for this channel. The verifications performed are - validate that the proposal endorsement's signer is trusted - verify that the endorsement signature matches the signer's claimed identity
Parameters:
Name Type Description
The ProposalResponse endorsement response from the peer, includes the endorser certificate and signature over the proposal, endorsement result and endorser certificate.
See:
  • /protos/peer/proposal_reponse.proto
Returns:
a boolean value of true when both the identity and the signature are valid, false otherwise.
Type
boolean