Updated on 2023-03-07 GMT+08:00

Chaincode Invoking

Function

This API is used to invoke and query the instantiated chaincodes of deployed BCS services.

URI

POST /v1/chaincode/operation

Request

Table 1 Request parameters

Parameter

Mandatory

Type

Description

channelId

Yes

String

Channel ID in a blockchain.

chaincodeId

Yes

String

Chaincode ID.

chaincodeVersion

No

String

Chaincode version.

userId

Yes

String

User ID issued by the organization CA. Currently, the default value generated for BCS is User1.

orgId

Yes

String

Organization ID in a blockchain.

orgPeers

Yes

String

A character string consisting of the organization ID and domain name of each peer in an organization. The format is as follows:

[{"orgId":"7258adda1803f4137eff4813e7aba323018200c5","peerDomainName":"peer-7258adda1803f4137eff4813e7aba323018200c5-0.peer-7258adda1803f4137eff4813e7aba323018200c5.default.svc.cluster.local"}]

opmethod

Yes

String

Purpose, that is, to invoke or query chaincodes.

args

Yes

String

Arguments, for example, ["Invoke", "a", "b", "1"]

timestamp

Yes

String

For example, 2018-10-31T17:28:16+08:00.

cert

Yes

String

User certificate file, which is uploaded in the form of a character string.

For details about how to obtain the values of the preceding parameters, see Chaincode Management and Block Browser.

  • On the Chaincode Management page, click in front of a chaincode to view its details, including the version, installation, and instantiation information.
  • On the Block Browser page, select a channel to view real-time blockchain information, including the block quantity, transaction quantity, block details, transaction details, performance, and peer statuses.
  • To ensure transaction security, you must use the private key in the Fabric user certificate (downloaded by following instructions in Downloading the User Certificate) to sign the request body. Currently, only the ECDSA encryption method is supported. Other encryption algorithms such as OSCCA-published cryptographic algorithms are not supported. Then, place the signature result in the x-bcs-signature-sign field in the request header.

Table 2 lists the request header parameters customized for the chaincode invoking RESTful API.

Table 2 Customized header parameters

Parameter

Mandatory

Description

x-bcs-signature-sign

Yes

Signature of the chaincode invoking request message body

x-bcs-signature-method

Yes

Encryption type, which is fixed at SW now.

x-bcs-signature-sign-gzip

Yes

Indication of whether GZIP compression is enabled. 0: disabled; 1: enabled.

x-bcs-signature-sign: To ensure that only authorized invocation entities can invoke chaincodes, the user private key (downloaded by following instructions in Downloading the User Certificate) and the ECDSA encryption method must be used to encrypt and sign the SHA256 hash of the entire request body. The value of x-bcs-signature-sign is the encrypted and signed hash.

Downloading the User Certificate

Download the user certificate that is configured in BCS to call the APIs.

  1. Log in to the BCS console.
  2. On the Instance Management page, check the BCS instances.
  3. Click Download Client Configuration, and select Peer Certificates. Specify the peer organization and select User certificate.
  4. Click Download.
  5. Decompress the certificates. In the msp folder, the private key of the organization is stored in keystore, and the user certificate (public key) in signcerts.

Response

  • If opmethod is invoke, the transactionID encrypted and encoded using Base64 is returned.
  • If opmethod is query, the query result returned by the chaincode is also encrypted and encoded using Base64.

Examples

The following is an example of invoking a chaincode:

  • Example request
    {
      "channelId": "testchannel",
      "chaincodeId": "zmmcode",
      "chaincodeVersion": "1.0",
      "userId": "User1",
      "orgId": "7258adda1803f4137eff4813e7aba323018200c5", 
      "orgPeers": "[{\"orgId\":\"7258adda1803f4137eff4813e7aba323018200c5\",\"peerDomainName\":\"peer-7258adda1803f4137eff4813e7aba323018200c5-0.peer-7258adda1803f4137eff4813e7aba323018200c5.default.svc.cluster.local\"}]",
      "opmethod": "invoke",
      "args": "[\"invoke\",\"a\",\"b\",\"1\"]",
      "timestamp": "2018-10-31T17:28:16+08:00",
      "cert": "-----BEGIN CERTIFICATE-----\nMIIDBzCCAq2gAwIBAgIQEXPZlMsReamxVtVNnKwCCzAKBggqhkjOPQQDAjCCAQQx\nDjAMBgNVBAYTBUNISU5BMRAwDgYDVQQIEwdCRUlKSU5HMRAwDgYDVQQHEwdCRUlK\nSU5HMXkwdwYDVQQKE3A3MjU4YWRkYTE4MDNmNDEzN2VmZjQ4MTNlN2FiYTMyMzAx\nODIwMGM1LnBlZXItNzI1OGFkZGExODAzZjQxMzdlZmY0ODEzZTdhYmEzMjMwMTgy\nMDBjNS5kZWZhdWx0LnN2Yy5jbHVzdGVyLmxvY2FsMVMwUQYDVQQDE0pjYS5wZWVy\nLTcyNThhZGRhMTgwM2Y0MTM3ZWZmNDgxM2U3YWJhMzIzMDE4MjAwYzUuZGVmYXVs\ndC5zdmMuY2x1c3Rlci5sb2NhbDAeFw0xODEwMzAwMjQ5MjZaFw0yODEwMjcwMjQ5\nMjZaMIG1MQ4wDAYDVQQGEwVDSElOQTEQMA4GA1UECBMHQkVJSklORzEQMA4GA1UE\nBxMHQkVJSklORzF/MH0GA1UEAwx2VXNlcjFANzI1OGFkZGExODAzZjQxMzdlZmY0\nODEzZTdhYmEzMjMwMTgyMDBjNS5wZWVyLTcyNThhZGRhMTgwM2Y0MTM3ZWZmNDgx\nM2U3YWJhMzIzMDE4MjAwYzUuZGVmYXVsdC5zdmMuY2x1c3Rlci5sb2NhbDBZMBMG\nByqGSM49AgEGCCqGSM49AwEHA0IABPMrzoJL/MHeSFPFOJWLqnJ0sqB0it7wDIOq\n+eTSvvPpGk1BIDmb2n13K5V04RO8xNezDQ7I6rW4LF2elq14eH+jTTBLMA4GA1Ud\nDwEB/wQEAwIHgDAMBgNVHRMBAf8EAjAAMCsGA1UdIwQkMCKAIFBXQ5TC4acFeTlT\nJuDZg62XkXCdnOfvbejSeKI2TXoIMAoGCCqGSM49BAMCA0gAMEUCIQCadHIKl0Mk\nYn0WZizyDZYR4rT2q0nzjFaiW+YfV5FBjAIgNalKUe3rIwXJvXORV4ZXurEua2Ag\nQmhcjRnVwPTjpTE=\n-----END CERTIFICATE-----\n"
    }
  • Example response
     After  invoke the count of a is 188  b is  262

Error Codes

See Error Codes.