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

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

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

Для получения информации о смарт-контрактах, загруженных в сеть, предусмотрен набор методов группы 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 (создания смарт-контракта) или другой транзакции вызова контракта (Call, Update) по идентификатору транзакции {id}. Однако если после отправки транзакции в блокчейн нода перезапускается, метод не вернет корректное состояние этой транзакции.

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

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

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

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

  • status – статус транзакции: успешно попала в блок, подтверждена, отклонена;

    • 0 – контракт успешно исполнен (SUCCESS);

    • 1 – бизнес ошибка, контракт не исполнен, вызов отклонён (ERROR);

    • 2 – системная ошибка в ходе исполнения смарт-контракта (FAILURE).

  • code – код ошибки в ходе выполнения смарт-контракта (при наличии);

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

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

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

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

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

GET /contracts/status/{id}:
{
  "sender": "3GLWx8yUFcNSL3DER8kZyE4TpyAyNiEYsKG",
  "senderPublicKey": "4WnvQPit2Di1iYXDgDcXnJZ5yroKW54vauNoxdNeMi2g",
  "txId": "4q5Q8vLeGBpcdQofZikyrrjHUS4pB1AB4qNEn2yHRKWU",
  "status": "Success",
  "code": null,
  "message": "Smart contract transaction successfully mined",
  "timestamp": 1558961372834,
  "signature": "4gXy7qtzkaHHH6NkksnZ5pnv8juF65MvjQ9JgVztpgNwLNwuyyr27Db3gCh5YyADqZeBH72EyAkBouUoKvwJ3RQJ"
 }

Примечание

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.

В ответе метода возвращаются данные транзакции 105, а также результаты исполнения в поле results.

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

GET /contracts/executed-tx-for/{id}:
{
  "type": 105,
  "id": "2UAHvs4KsfBbRVPm2dCigWtqUHuaNQou83CXy6DGDiRa",
  "sender": "3PKyW5FSn4fmdrLcUnDMRHVyoDBxybRgP58",
  "senderPublicKey": "2YvzcVLrqLCqouVrFZynjfotEuPNV9GrdauNpgdWXLsq",
  "fee": 500000,
  "timestamp": 1549365523980,
  "proofs": [
    "4BoG6wQnYyZWyUKzAwh5n1184tsEWUqUTWmXMExvvCU95xgk4UFB8iCnHJ4GhvJm86REB69hKM7s2WLAwTSXquAs"
  ],
  "version": 1,
  "tx": {
      "type": 103,
      "id": "ULcq9R7PvUB2yPMrmBdxoTi3bcRmQPT3JDLLLZVj4Ky",
      "sender": "3N3YTj1tNwn8XUJ8ptGKbPuEFNa9GFnhqew",
      "senderPublicKey": "3kW7vy6nPC59BXM67n5N56rhhAv38Dws5skqDsjMVT2M",
      "fee": 500000,
      "timestamp": 1550591678479,
      "proofs": [ "yecRFZm9iBLyDy93bDVaNo1PR5Qkkic7196GAgUt9TNH1cnQphq4yGQQ8Fxj4BYA4TaqYVw5qxtWzGMPQyVeKYv" ],
      "version": 1,
      "image": "stateful-increment-contract:latest",
      "imageHash": "7d3b915c82930dd79591aab040657338f64e5d8b842abe2d73d5c8f828584b65",
      "contractName": "stateful-increment-contract",
      "params": [],
      "height": 1619
  },
  "results": []
}

Примечание

Существует аналогичный метод для конфиденциальных смарт-контрактов: 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
}
Смотрите также

Методы REST API

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

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