Установка и использование платформы
REST API: информация о смарт-контрактах¶
Для получения информации о смарт-контрактах, загруженных в сеть, предусмотрен набор методов группы contracts
.
GET /contracts¶
Метод возвращает информацию по всем смарт-контрактам, загруженным в сеть. Для каждого смарт-контракта в ответе возвращаются следующие параметры:
contractId
– идентификатор смарт-контракта;image
– имя Docker-образа смарт-контракта, либо его абсолютный путь в репозитории;imageHash
– хэш-сумма смарт-контракта;version
– версия смарт-контракта;active
– статус смарт-контракта на момент отправки запроса:true
– запущен;false
– не запущен.
Пример ответа для одного смарт-контракта:
POST /contracts¶
Метод возвращает набор полей «ключ:значение», записанных в стейт одного или нескольких смарт-контрактов.
ID запрашиваемых смарт-контрактов указываются в поле contracts
запроса.
Пример ответа для одного смарт-контракта:
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
– подпись транзакции.
Пример ответа:
Примечание
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 ExecutedContract Transaction.
В ответе метода возвращаются данные транзакции 105, включая результаты исполнения смарт-контракта в поле resultsMap
(если была использована версия 5 транзакции 105) или results
(если была использована версия 4 или более ранняя) и statusCode
.
Пример ответа:
Примечание
Существует аналогичный метод для конфиденциальных смарт-контрактов: 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
Пример ответа:
GET /contracts/balance/{contractId}¶
Метод возвращает краткую информацию о балансе смарт-контракта, идентификатор которого передан как contractId
, в системных токенах WEST:
assetId
– идентификатор ассета; поскольку метод возвращает баланс в системных токенах, поле всегда будет пустым;
balance
– баланс смарт-контракта; значение типаint
;
decimals
– количество разрядов после запятой у используемого токена; для WEST имеет значение 8.
Пример ответа:
Примечание
gRPC метод GetContractBalances также возвращает информацию о балансе смарт-контракта, как и REST метод GET /contracts/balance/{contractId}.
GET /contracts/asset-balance/{contractId}/{assetId}¶
Метод возвращает баланс контракта, идентификатор которого передан как contractId
, в токене, идентификатор которого передан как assetId
:
assetId
– идентификатор ассета;
balance
– баланс смарт-контракта; значение типаint
;
decimals
– количество разрядов после запятой у используемого токена.
Пример ответа:
Примечание
gRPC метод GetContractBalances также возвращает информацию о балансе смарт-контракта, как и REST метод GET /contracts/asset-balance/{contractId}/{assetId}.
POST /contracts/asset-balances¶
Метод возвращает балансы контракта, идентификатор которого передан как contractId
, во всех токенах, идентификаторы которых переданы как множество строк в поле assetIds
. Для каждого ассета возвращается следующая информация:
assetId
– идентификатор ассета;
balance
– баланс смарт-контракта в этом ассете; значение типаint
;
decimals
– количество разрядов после запятой у используемого токена.
Примеры запроса и ответа:
Примечание
gRPC метод GetContractBalances также возвращает информацию о балансе смарт-контракта, как и REST метод POST /contracts/asset-balances.