Installation and usage of the platform

REST API: working with confidential smart contracts

https://img.shields.io/badge/auth-required-orange.svg

The confidential-contracts methods group is provided to handle confidential smart contracts.

POST /confidential-contracts/call

The POST /confidential-contracts/call REST method is used to transfer confidential smart contracts data outside the blockchain.

Important

You can only call the POST /confidential-contracts/call method when you have an oAuth token with the ConfidentialContractUser role or a special api-key.

The POST /confidential-contracts/call method is not available for contracts without confidentiality support (isConfidential = false).

The POST /confidential-contracts/call method returns an error if there are less than three nodes with the contract-validator role among the members of the authorization group (policy).

The following data is passed in the method request:

  • broadcast – the flag that marks the need to broadcast the generated CallContract transaction; the field defaults to true; the false value is used to form an atomic container;

  • commitmentVerification – the flag that marks the necessity of input data commitment reconciliation and the need for the user to provide a key for commitment generation; the field defaults to false; if false is set, the node generates the key randomly and calculates the commitment; if commitmentVerification is set to true and the user has not passed commitment or commitmentKey, or has passed an incorrectly generated commitment value or an incorrect commitmentKey, the method returns an error;

  • sender – the confidential smart contract data sender address;

  • contractId – the confidential smart contract identifier;

  • contractVersion – the confidential smart contract version;

  • params – when working with CallContract transaction, the field holds input data of the confidential smart contract, represented as an array of objects; data is entered using the following fields:

    • key – the parameter key;

    • type – the parameter data type;

    • value– the parameter value.

  • timestamp – the Unix Timestamp (in milliseconds), marking the time of the smart contract call;

  • atomicBadge – the flag that marks if the transaction can be included in an atomic transaction;

  • fee – the transaction fee;

  • feeAssetId – the fee token identifier;

  • commitment – the commitment;

  • commitmentKey – the commitment key.

The POST /confidential-contracts/call method takes all the data needed to send a CallContract version 6 transaction, then sends it, and returns a protobuf that includes the CallContract transaction version 6 and the confidential input data to start the confidential smart contract (ConfidentialInput) in the response.

Response example:

POST /confidential-contracts/call:
{
    "callContractTransactionV6":{
       "senderPublicKey":"5oKuxwiRmqHnr7vCAHK3VRJBhg9andjskfX11HpmJcYp8JifBXisz4KEKFD3pbRum3PWHDf4ZKkoCAgrrsLbp8HH",
       "inputCommitment":"GRWajEXricyL5idiJVcCtNaedDGvBow8dZu1w8L3bRh9",
       "fee":10000000,
       "payments":[

       ],
       "type":104,
       "params":[

       ],
       "version":6,
       "contractVersion":1,
       "atomicBadge":null,
       "sender":"3Hakpx6EE4fDb7Vd7EaWMG1HT9UJezLeVcG",
       "feeAssetId":null,
       "proofs":[
           "2JExxgAjQUmr5YNpkJpo3gRYtteDbhx4ZyQtt8CB978BjKBgy8N9yfu7ikh13muRcqWaT1XwYu78xJJttEtAjc2E"
       ],
       "contractId":"BbkPS3BKzs5JFR1wLiHqvRgF8DkuajKiQkKQdKZ5Ydru",
       "id":"2kH8Y4798dqrczZgaPo7LSkmwSWq4CmN6vbr3zhNBrN4",
       "timestamp":1697788418311
    },
    "confidentialInput":{
       "commitment":"GRWajEXricyL5idiJVcCtNaedDGvBow8dZu1w8L3bRh9",
       "txId":"2kH8Y4798dqrczZgaPo7LSkmwSWq4CmN6vbr3zhNBrN4",
       "contractId":{
          "byteStr":"BbkPS3BKzs5JFR1wLiHqvRgF8DkuajKiQkKQdKZ5Ydru"
    },
    "commitmentKey":{
       "bytes":"CMtEfgK628ZT9Bc376caLwhacgozBucfXjxrmyLcrLMg"
    },
    "entries":[
       {
        "type":"integer",
        "value":1,
        "key":"test"
       }
    ]
 }

Note

The POST /confidential-contracts/call REST method is similar to the ConfidentialCall gRPC method.

GET ​/confidential-contracts/{contractId}

The method returns the selected keys values from the confidential smart contract state to the members of the corresponding policy (authorization group).

Important

You can only call the GET ​/confidential-contracts/{contractId} method if you are a member of the corresponding policy and have an oAuth token with the ConfidentialContractUser role or a special api-key.

The following data is passed in the GET ​/confidential-contracts/{contractId} method request:

  • contractId – the confidential smart contract identifier;

  • limit – the limit of number of data blocks to be obtained;

  • offset – the number of data blocks to be missed in the method response;

  • matches – an optional parameter to compose a regular expression that filters the keys.

Response example for policy members:

GET ​/confidential-contracts/{contractId}:
[
  {
   "type": "integer",
   "value": 1,
   "key": "sum"
  }
]

Response example for the addresses that are not policy members:

GET ​/confidential-contracts/{contractId}:
{
  "error": 651,
  "message": "Confidential groups from contract '9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7' not contain NodeOwner '3NtNJV44wyxRXv2jyW3yXLxjJxvY1vR88TF'"
}

Note

There are similar methods for regular (non-confidential) smart contracts: GET /contracts/{contractId} and POST /contracts/{contractId}.

Note

There is a gRPC method similar to the GET /confidential-contracts/{contractId} method: GetContractKeys.

GET /confidential-contracts/tx/{executable-tx-id}

The method returns the transaction of writing the confidential smart contract execution result to its state (105.ExecutedContract version 4), the confidential input data to run the contract (ConfidentialInput) and the confidential contract execution results (confidentialOutput) to the participants of the corresponding policy (authorization group).

In turn, 105.ExecutedContract transaction contains all the fields of 103. CreateContract, 104. CallContract, 107. UpdateContract transactions of the smart contract.

Important

You can only call the GET /confidential-contracts/tx/{executable-tx-id} method if you are a member of the corresponding policy and have an oAuth token with the ConfidentialContractUser role or a special api-key.

Response example for policy members:

GET /confidential-contracts/tx/{executable-tx-id}:
{
  "executedContractTransactionV4": {
    "senderPublicKey": "4nYb9pKHjndhCkCSCLFoP5GXwH8VTNNyzduFDShUtpD9",
    "tx": {
      "senderPublicKey": "CgqRPcPnexY533gCh2SSvBXh5bca1qMs7KFGntawHGww",
      "inputCommitment": "Ee35NnBwJNQTEhMv4m2EgpjgLj99sr1fVzEukVS7PuCS",
      "fee": 10000000,
      "payments": [],
      "type": 104,
      "params": [],
      "version": 6,
      "contractVersion": 1,
      "atomicBadge": null,
      "sender": "3NkZd8Xd4KsuPiNVsuphRNCZE3SqJycqv8d",
      "feeAssetId": null,
      "proofs": [
        "26sgy8uvZNLk3ePCp99MB6NkuzUPG3rLTZ1Hx63nMCsGsS1MzRsGDy5dmqWgFJBsSmYhNuYGY8KQnrSaMvWdqDw3"
      ],
      "contractId": "9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7",
      "id": "8HBTx3CZxzWusLY1Fp55HER7jAA9aQfucKJTTMbkfSc7",
      "timestamp": 1704835802000
    },
    "resultsHash": "DsHN64QHaf3SwNz13smhPjx6hHX1sCArbjCfrfWGtVJq",
    "fee": 0,
    "validationProofs": [],
    "type": 105,
    "version": 4,
    "outputCommitment": "FwK5BbtHoQKo6r9uUaBPLYziV4j9YMKXQAAS4NMpqrWZ",
    "readings": [],
    "sender": "3NqTPTybHjETw2g37vee4WuYjdB6rje1mNa",
    "assetOperations": [],
    "proofs": [
      "2YKSvZXMj5zQXxhg9b8RGFQpHGxLDXKLiX3jHGs84xbcQN82yDLHEJRGgniyY88EWUgoR1sD94iRnoQNoMGshUge"
    ],
    "id": "Gv2dzpWyXrDoH1DE9yDSz5sHu81jEwLLGm47vCuQZef3",
    "results": [],
    "readingsHash": null,
    "timestamp": 1704835803181
  },
  "confidentialInput": {
    "commitment": "Ee35NnBwJNQTEhMv4m2EgpjgLj99sr1fVzEukVS7PuCS",
    "txId": "8HBTx3CZxzWusLY1Fp55HER7jAA9aQfucKJTTMbkfSc7",
    "contractId": {
      "byteStr": "9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7"
    },
    "commitmentKey": {
      "bytes": "9PshLtfpaKGDaxkHSGS6JjKRMRmFwSEg84aJPS9FiZdj"
    },
    "entries": [
      {
        "type": "integer",
        "value": 1,
        "key": "COUNTERS_COUNT"
      }
    ]
  },
  "confidentialOutput": {
    "commitment": "FwK5BbtHoQKo6r9uUaBPLYziV4j9YMKXQAAS4NMpqrWZ",
    "txId": "8HBTx3CZxzWusLY1Fp55HER7jAA9aQfucKJTTMbkfSc7",
    "contractId": {
      "byteStr": "9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7"
    },
    "commitmentKey": {
      "bytes": "9PshLtfpaKGDaxkHSGS6JjKRMRmFwSEg84aJPS9FiZdj"
    },
    "entries": [
      {
        "type": "integer",
        "value": 1,
        "key": "sum"
      }
    ]
  }
}

Response example for the addresses that are not policy members:

GET /confidential-contracts/tx/{executable-tx-id}:
{
  "error": 199,
  "message": "Node owner with address '3NtNJV44wyxRXv2jyW3yXLxjJxvY1vR88TF' is not in confidential groups for contract with id: '9KkLSJA8zXKtnCWSFMRSZ855xw6cJyDS29grtFWprVB7'"
}

Note

There is a similar method for regular (non-confidential) smart contracts: GET /contracts/executed-tx-for/{id}.

Note

The GET /confidential-contracts/tx/{executable-tx-id} REST method is similar to the ConfidentialExecutedTxByExecutableTxId gRPC method.

See also

REST API methods

Confidential smart contracts

Smart contracts

Development and usage of smart contracts