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

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

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

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

GET /contracts

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

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

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

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

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

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

    • true – запущен;

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

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

POST /contracts

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

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

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 – подпись транзакции.

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

Примечание

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

GET /contracts/{contractId}

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

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

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

Примечание

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

POST /contracts/{contractId}

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

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

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

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

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

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

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

Примечание

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

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

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

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

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

Примечание

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

GET /contracts/{contractId}/{key}

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

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

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

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