Установка и использование платформы

REST API: информация о смарт-контрактах

Для получения информации о смарт-контрактах, загруженных в сеть, предусмотрен набор методов группы contracts.

GET /contracts

Метод возвращает информацию по всем смарт-контрактам, загруженным в сеть. Для каждого смарт-контракта в ответе возвращаются следующие параметры:

• contractId – идентификатор смарт-контракта;

• image – имя Docker-образа смарт-контракта, либо его абсолютный путь в репозитории;

• imageHash – хэш-сумма смарт-контракта;

• version – версия смарт-контракта;

• active – статус смарт-контракта на момент отправки запроса:

  • true – запущен;

  • false – не запущен.

Пример ответа для одного смарт-контракта:

GET /contracts:

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

POST /contracts

Метод возвращает набор полей «ключ:значение», записанных в стейт одного или нескольких смарт-контрактов. ID запрашиваемых смарт-контрактов указываются в поле contracts запроса.

Пример ответа для одного смарт-контракта:

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}.

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

В ответе метода возвращаются следующие параметры:

• sender – адрес отправителя транзакции;

• senderPublicKey – публичный ключ отправителя транзакции;

• txId – идентификатор транзакции вызова смарт-контракта;

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

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

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

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

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

• message – сообщение о статусе транзакции; содержит дополнительную информацию о статусе, указанном в поле status, например,

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

• timestamp – временная метка в формате Unix Timestamp, в миллисекундах, отмечающая время вызова смарт-контракта;

• signature – подпись транзакции.

Пример ответа:

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"
  }
]

Примечание

gRPC метод ContractExecutionStatuses возвращает ту же информацию, что и REST метод GET /contracts/status/{id}.

GET /contracts/{contractId}

Метод возвращает результат исполнения смарт-контракта по его идентификатору {contractId}. Результат исполнения смарт-контракта возвращается как key-value пары в виде массива объектов с указанием типа данных.

Пример ответа:

GET /contracts/{contractId}:

[
  {
    "type": "string",
    "key": "avg",
    "value": "3897.80146957"
  },
  {
    "type": "string",
    "key": "buy_price",
    "value": "3842"
  }
]

Методы GET /contracts/{contractId} и POST /contracts/{contractId} возвращают одинаковый ответ.

Примечание

Существует аналогичный метод для конфиденциальных смарт-контрактов: GET ​/confidential-contracts/{contractId}.

POST /contracts/{contractId}

Метод возвращает значения выбранных ключей из стейта смарт-контракта {contractId}. В запросе указываются следующие данные:

• contractId – идентификатор смарт-контракта;

• limit – ограничение количества выводимых блоков данных;

• offset – количество блоков данных для пропуска в выводе;

• matches – опциональный параметр для составления регулярного выражения, по которому фильтруются ключи.

Пример ответа:

POST /contracts/{contractId}:

[
  {
    "type": "string",
    "key": "avg",
    "value": "3897.80146957"
  },
  {
    "type": "string",
    "key": "buy_price",
    "value": "3842"
  }
]

Методы POST /contracts/{contractId} и GET /contracts/{contractId} возвращают одинаковый ответ.

Примечание

Существует аналогичный метод для конфиденциальных смарт-контрактов: GET ​/confidential-contracts/{contractId}.

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

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

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

Пример ответа:

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"
 }

Примечание

Существует аналогичный метод для конфиденциальных смарт-контрактов: GET /confidential-contracts/tx/{executable-tx-id}.

GET /contracts/{contractId}/{key}

Метод возвращает значение ключа {key} исполненного смарт-контракта по его идентификатору.

Пример ответа:

GET /contracts/{contractId}/{key}:

{
  "key": "updated",
  "type": "integer",
  "value": 1545835909
}

GET /contracts/balance/details/{ContractID}

Метод возвращает развернутую информацию о балансе смарт-контракта в системных токенах по его идентификатору {ContractID}. Ответ метода содержит следующую информацию о балансе смарт-контракта:

• regular – фактический баланс смарт-контракта. В частности, это может быть количество системных токенов WEST, переведенных на баланс смарт-контракта с помощью поля payments транзакции 103. CreateContract Transaction версии 5 или транзакции 104. CallContract Transaction версии 5;

• leasedOut – количество системных токенов, которые были переданы смарт-контрактом какому-либо адресу в лизинг. После отмены лизинга баланс смарт-контракта обновляется и средства возвращаются на баланс смарт-контракта;

• available – количество доступных для использования системных токенов на балансе смарт-контракта. Значение этого поля вычисляется по значениям полей выше:

  available = regular - leasedOut

  После отмены лизинга значение этого параметра также обновляется.

Например, если при создании смарт-контракта на его баланс передано 10 WEST, а затем смарт-контракт передал в лизинг какому-либо адресу 4 WEST, то метод вернёт следующие значения:

• Regular = 10

• LeasedOut = 4

• Available = 6

После отмены лизинга метод вернёт следующие значения:

• Regular = 10

• LeasedOut = 0

• Available = 10

Пример ответа:

GET /contracts/balance/details/{ContractID}:

{
  "contractId": "CbGnXsi84QrwZYqJ4jpjVvwyBhXXCiS9axVMci4YNRDq",
  "regular": 40,
  "leasedOut": 20,
  "available": 20
}

GET /contracts/balance/{contractId}

Метод возвращает краткую информацию о балансе смарт-контракта, идентификатор которого передан как contractId, в системных токенах WEST:

• assetId – идентификатор ассета; поскольку метод возвращает баланс в системных токенах, поле всегда будет пустым;

• balance – баланс смарт-контракта; значение типа int;

• decimals – количество разрядов после запятой у используемого токена; для WEST имеет значение 8.

Пример ответа:

GET /contracts/balance/{contractId}:

{

  "assetId": "",
  "balance": "2100000000000000",
  "decimals": 8

}

Примечание

gRPC метод GetContractBalances также возвращает информацию о балансе смарт-контракта, как и REST метод GET /contracts/balance/{contractId}.

GET /contracts/asset-balance/{contractId}/{assetId}

Метод возвращает баланс контракта, идентификатор которого передан как contractId, в токене, идентификатор которого передан как assetId:

• assetId – идентификатор ассета;

• balance – баланс смарт-контракта; значение типа int;

• decimals – количество разрядов после запятой у используемого токена.

Пример ответа:

GET /contracts/asset-balance/{contractId}/{assetId}:

{
  "assetId": "9ekQuYn92natMnMq8KqeGK3Nn7cpKd3BvPEGgD6fFyyz",
  "balance": "2100000000000000",
  "decimals": 8
}

Примечание

gRPC метод GetContractBalances также возвращает информацию о балансе смарт-контракта, как и REST метод GET /contracts/asset-balance/{contractId}/{assetId}.

POST /contracts/asset-balances

Метод возвращает балансы контракта, идентификатор которого передан как contractId, во всех токенах, идентификаторы которых переданы как множество строк в поле assetIds. Для каждого ассета возвращается следующая информация:

• assetId – идентификатор ассета;

• balance – баланс смарт-контракта в этом ассете; значение типа int;

• decimals – количество разрядов после запятой у используемого токена.

Примеры запроса и ответа:

POST /contracts/asset-balances:

Пример запроса:

{

  "contractId": "9ekQuYn92natMnMq8KqeGK3Nn7cpKd3BvPEGgD6fFyyz",
  "assetIds":

  [
    "string"
  ]

}

Пример ответа:

[
  {
    "assetId": "9ekQuYn92natMnMq8KqeGK3Nn7cpKd3BvPEGgD6fFyyz",
    "balance": "2100000000000000",
    "decimals": 8
  }
]

Примечание

gRPC метод GetContractBalances также возвращает информацию о балансе смарт-контракта, как и REST метод POST /contracts/asset-balances.

Смотрите также

Методы REST API

Смарт-контракты

Разработка и применение смарт-контрактов

×

Нашли несоответствие?
Будем рады получить от вас развернутый отзыв!



Отправить

Введите текст отзыва

Максимум - 4000 символов.

Эта статья была вам полезна?

Да Нет