Installation and usage of the platform

REST API: information about smart contracts

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

A set of methods from the contracts group is provided to obtain information about smart contracts loaded on the network.

GET /contracts

The method returns information on all smart contracts uploaded to the network. For each smart contract, the following parameters are returned in the response:

  • contract_id – smart contract identifier;

  • image – name of the Docker image of the smart contract, or its absolute path in the repository;

  • imageHash – hash sum of the smart contract;

  • version – smart contract version;

  • active – smart contract status at the time of sending the query:

    • true – running;

    • false – not running.

Response example for one smart contract:

GET /contracts:
[
  {
    "contractId": "dmLT1ippM7tmfSC8u9P4wU6sBgHXGYy6JYxCq1CCh8i",
    "image": "registry.wvservices.com/wv-sc/may14_1:latest",
    "imageHash": "ff9b8af966b4c84e66d3847a514e65f55b2c1f63afcd8b708b9948a814cb8957",
    "version": 1,
    "active": false
   }
 ]

POST /contracts

The method returns a set of “key:value” fields written to the stack of one or more smart contracts. The IDs of the requested smart contracts are specified in the contracts field of the request.

Response example for one smart contract:

POST /contracts:
{
  "8vBJhy4eS8oEwCHC3yS3M6nZd5CLBa6XNt4Nk3yEEExG": [
   {
   "type": "string",
   "value": "Only description",
   "key": "Description"
   },
   {
   "type": "integer",
   "value": -9223372036854776000,
   "key": "key_may"
   }
  ]
 }

GET /contracts/status/{id}

Метод возвращает статус исполняемой транзакции создания смарт-контракта 103 Create Contract, вызова контракта Call Contract или обновления контракта Update Contract по идентификатору транзакции {id}.

Даже если после отправки транзакции в блокчейн нода перезапустится, метод вернёт корректное состояние этой транзакции.

Parameters returned in the method response:

  • sender – transaction sender address;

  • senderPublicKey – the public key of the transaction sender;

  • contract_id – smart contract call identifier;

  • status – статус исполнения транзакции:

    • SUCCESS – транзакция успешно попала в блок;

    • ERROR – некритическая ошибка, вызов отклонён; например, бизнес ошибка, контракт не исполнен;

    • FAILURE – критическая ошибка, вызов отклонён; например, системная ошибка в ходе исполнения смарт-контракта.

  • code – числовой код ошибки в ходе выполнения смарт-контракта (при наличии); в случае WASM смарт-контракта метод вернёт код ошибки WASM смарт-контракта; в случае Docker смарт-контракта может быть возвращён код ошибки, заданный пользователем, или другой ошибки.

  • message – transaction status message; contains additional information about the status specified in the status field, for example,

    "message": "Smart contract transaction successfully mined";

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

  • signature – transaction signature.

Response example:

GET /contracts/status/{id}:
[
  {
    "sender": "3NqTPTybHjETw2g37vee4WuYjdB6rje1mNa",
    "senderPublicKey": "4nYb9pKHjndhCkCSCLFoP5GXwH8VTNNyzduFDShUtpD9",
    "txId": "Qvp3ZBfvJKoKdrPiChheb3bKyQ4qAcMvBo38fgvAboi",
    "status": "Error",
    "code": 503,
    "message": "contract failed with error code 503",
    "timestamp": 1709300210974,
    "signature": "3XpAtn9RP7bskzWs4x8ZmpptiWdP1X2b77fV4NWpXiJxgsBy18cVUwhd9LJkDTHWY17LtSt6zzr3aG2gTCedTKfx"
  },
  {
    "sender": "3NqTPTybHjETw2g37vee4WuYjdB6rje1mNa",
    "senderPublicKey": "4nYb9pKHjndhCkCSCLFoP5GXwH8VTNNyzduFDShUtpD9",
    "txId": "Qvp3ZBfvJKoKdrPiChheb3bKyQ4qAcMvBo38fgvAboi",
    "status": "Success",
    "code": null,
    "message": "Contract transaction successfully mined",
    "timestamp": 1709300211066,
    "signature": "4TExJCaih9zZpoYgRfJRDtuhEJt6jBL5ykY1aBqCpwRfPrNQy6tqPWuL24oCYxG8gUCLimNAwf84rK1dtd1SLby8"
  }
]

Note

ContractExecutionStatuses gRPC method returns the same information as the GET /contracts/status/{id} REST method.

GET /contracts/{contractId}

The method returns the result of smart contract execution by its {contractId} identifier. The result is returned in key-value pairs as an array of objects with the data type specified.

Response example:

GET /contracts/{contractId}:
[
  {
    "type": "string",
    "key": "avg",
    "value": "3897.80146957"
  },
  {
    "type": "string",
    "key": "buy_price",
    "value": "3842"
  }
]

The GET /contracts/{contractId} and POST /contracts/{contractId} methods return the same response.

Note

There is a similar method for confidential smart contracts: GET /confidential-contracts/{contractId}.

POST /contracts/{contractId}

The method returns the selected key values from the {contractId} smart contract state. The query specifies the following data:

  • contract_id – smart contract identifier;

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

  • offset – 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:

POST /contracts/{contractId}:
[
  {
    "type": "string",
    "key": "avg",
    "value": "3897.80146957"
  },
  {
    "type": "string",
    "key": "buy_price",
    "value": "3842"
  }
]

The POST /contracts/{contractId} and GET /contracts/{contractId} methods return the same response.

Note

There is a similar method for confidential smart contracts: GET /confidential-contracts/{contractId}.

GET /contracts/executed-tx-for/{id}

Метод возвращает результат исполнения смарт-контракта по идентификатору транзакции 105 ExecutedContract Transaction.

В ответе метода возвращаются данные транзакции 105, включая результаты исполнения смарт-контракта в поле resultsMap (если была использована версия 5 транзакции 105) или results (если была использована версия 4 или более ранняя) и statusCode.

Response example:

GET /contracts/executed-tx-for/{id}:
{
  "type": 105,
  "version": 5,
  "id": "HydNFEUeCj5DXFfHm32CrpcohvRvTABqdoFERtosgf5a",
  "sender": "3NdJB3vGAAQm2xQc2SAEhGNqDtXpL7YCn3v",
  "senderPublicKey": "9e4poNdEc9KF1qRxRJLbhqx6hrcjieQP2YcPiBdd3fpT",
  "fee": 0,
  "timestamp": 1708355888775,
  "proofs": [
    "3VHTSQh5HKkt1KGwhZg39WhPVNbNE5GnmyAD82no92e8CbYthh1KepjECyAcXXVu8QPoduscdZnnnrPtyfHZYjSR"
  ],
  "tx":
      {
        "type": 104,
        "version": 7,
        "sender": "3Nremv58EXSYK2qa5bhMeGnm1f2pRqLnv34",
        "senderPublicKey": "4sCvMtLD9MJUaw6dQrjnzWhrM6D32nrQcgQk5ULtQUXw",
        "inputCommitment": null,
        "contractEngine": "docker",
        "callFunc": null,
        "fee": 10000000,
        "feeAssetId": null,
        "payments": [],
        "params": [
          {
            "type": "integer",
            "value": 1,
            "key": "error_code"
          }
        ],
        "contractVersion": 1,
        "atomicBadge": null,
        "proofs": [
          "emoXX9D1tknstbNjkxAdERQsVz59AM9XchH9fwfeyUYNdkwSmBEU1FRfH71gDyyPHs3t4e6hrXqNiNUTrLkQ7pc"
        ],
        "contractId": "4K6gRgAhnzzbHXaGSRbWnjtU2r4kYUw61uwPuKJq1ims",
        "id": "Ecectk1L6T6TFAtUcQH2XerXNGT4gm7tMKBf2NnNKBjK",
        "timestamp": 1708355888031
      },
  "resultsHash": "xyw95Bsby3s4mt6f4FmFDnFVpQBAeJxBFNGzu2cX4dM",
  "validationProofs": [],
  "readings": [],
  "readingsHash" : null,
  "outputCommitment" : null,
  "resultsMap": {},
  "assetOperationsMap": {},
  "statusCode": 2,
  "errorMessage": "Rejected because the CircuitBreaker is in the Open state, attempting to close in 53 millis"
 }

Note

There is a similar method for confidential smart contracts: GET /confidential-contracts/tx/{executable-tx-id}.

GET /contracts/{contractId}/{key}

The method returns the {key} value of the executed smart contract by its identifier.

Response example:

GET /contracts/{contractId}/{key}:
{
  "key": "updated",
  "type": "integer",
  "value": 1545835909
}

GET /contracts/balance/details/{ContractID}

The method returns the detailed information about the smart contract balance in system tokens by the {ContractID} smart contract identifier. The method response contains the following information about the smart contract balance:

  • regular – the actual smart contract balance. For instance, this may be the number of WEST system tokens transferred to the balance of the smart contract in the payments field of the 103. CreateContract Transaction version 5 or 104. CallContract Transaction version 5;

  • leasedOut – the number of system tokens that the smart contract leased to some address. After the lease is cancelled, the smart contract balance is updated and the funds are returned to the smart contract balance;

  • available – the number of system tokens available for use on the smart contract balance. The value of this field is calculated from the values of the two fields above:

    available = regular - leasedOut

    After the lease is canceled, the value of this parameter is also updated.

For example, if a smart contract was created and had 10 WEST transferred to its balance, and then the smart contract leased 4 WEST to some address, the method returns the following values:

  • Regular = 10

  • LeasedOut = 4

  • Available = 6

After the lease is cancelled, the method will return the following values:

  • Regular = 10

  • LeasedOut = 0

  • Available = 10

Response example:

GET /contracts/balance/details/{ContractID}:
{
  "contractId": "CbGnXsi84QrwZYqJ4jpjVvwyBhXXCiS9axVMci4YNRDq",
  "regular": 40,
  "leasedOut": 20,
  "available": 20
}
See also

REST API methods

Smart contracts

Development and usage of smart contracts