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

REST API: работа с транзакциями

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

Для работы с транзакциями предусмотрены методы группы transactions:

  • Подписание и отправка транзакций:

  • Получение информации о транзакциях:

Подписание и отправка транзакций

REST API ноды использует JSON-представление транзакции для отправки запросов.

Основные принципы работы с транзакциями приведены в разделе Транзакции блокчейн-платформы. Описание полей для каждой транзакции приведено в разделе Описание транзакций.

POST /transactions/sign

Для подписания транзакций предназначен метод POST /transactions/sign. Этот метод подписывает транзакцию закрытым ключом отправителя, сохраненным в keystore ноды. Для подписания запросов ключом из keystore ноды обязательно укажите пароль к ключевой паре в поле password.

Важно

Метод ​/transactions​/sign недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. В тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF) метод можно использовать.

Пример запроса на подписание транзакции 3:

POST /transactions/sign:
{
   "type": 3,
   "version": 2,
   "name": "Test Asset 1",
   "quantity": 100000000000,
   "description": "Some description",
   "sender": "3FSCKyfFo3566zwiJjSFLBwKvd826KXUaqR",
   "decimals": 8,
   "reissuable": true,
   "password": "1234",
   "fee": 100000000
}

Метод POST /transactions/sign в ответе возвращает поля, необходимые для публикации транзакции.

Пример ответа с транзакцией 3:

POST /transactions/sign:
{
    "type": 3,
    "id": "DnK5Xfi2wXUJx9BjK9X6ZpFdTLdq2GtWH9pWrcxcmrhB",
    "sender": "3N65yEf31ojBZUvpu4LCo7n8D73juFtheUJ",
    "senderPublicKey": "C1ADP1tNGuSLTiQrfNRPhgXx59nCrwrZFRV4AHpfKBpZ",
    "fee": 100000000,
    "timestamp": 1549378509516,
    "proofs": [ "NqZGcbcQ82FZrPh6aCEjuo9nNnkPTvyhrNq329YWydaYcZTywXUwDxFAknTMEGuFrEndCjXBtrueLWaqbJhpeiG" ],
    "version": 2,
    "assetId": "DnK5Xfi2wXUJx9BjK9X6ZpFdTLdq2GtWH9pWrcxcmrhB",
    "name": "Test Asset 1",
    "quantity": 10000,
    "reissuable": true,
    "decimals": 8,
    "description": "Some description",
    "chainId": 84,
    "script": "base64:AQa3b8tH",
    "height": 60719
}

POST /transactions/broadcast

Для публикации транзакции предназначен метод POST /transactions/broadcast. На вход этого метода подаются поля ответа метода sign. Также транзакция может быть отправлена в блокчейн при помощи других инструментов, приведенных в статье Транзакции блокчейн-платформы.

Когда новый пользователь, который не является владельцем ноды (node-owner), делает свою первую транзакцию, ему необходимо в запросе в поле certificates приложить цепочку своих сертификатов. В других случаях поле certificates является необязательным.

Примечание

Поле certificates в запросе на публикацию транзакции RegisterNode является обязательным при использовании PKI или тестового режима PKI (то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON или TEST. В этом случае поле certificates должно содержать цепочку сертификатов, которая соответствует публичному ключу в поле target транзакции.

Пример запроса метода POST /transactions/broadcast

POST /transactions/broadcast:
{
    "type": 3,
    "id": "DnK5Xfi2wXUJx9BjK9X6ZpFdTLdq2GtWH9pWrcxcmrhB",
    "sender": "3N65yEf31ojBZUvpu4LCo7n8D73juFtheUJ",
    "senderPublicKey": "C1ADP1tNGuSLTiQrfNRPhgXx59nCrwrZFRV4AHpfKBpZ",
    "fee": 100000000,
    "timestamp": 1549378509516,
    "proofs": [ "NqZGcbcQ82FZrPh6aCEjuo9nNnkPTvyhrNq329YWydaYcZTywXUwDxFAknTMEGuFrEndCjXBtrueLWaqbJhpeiG" ],
    "version": 2,
    "assetId": "DnK5Xfi2wXUJx9BjK9X6ZpFdTLdq2GtWH9pWrcxcmrhB",
    "name": "Test Asset 1",
    "quantity": 10000,
    "reissuable": true,
    "decimals": 8,
    "description": "Some description",
    "chainId": 84,
    "script": "base64:AQa3b8tH",
    "height": 60719
    "certificates": ["a", "b", ...]
}

В случае успешной публикации транзакции метод возвращает json с транзакцией и сообщение 200ОК.

Примечание

Для отправки транзакций в блокчейн также можно использовать gRPC методы Broadcast или BroadcastWithCerts.

POST /transactions/signAndBroadcast

Помимо отдельных методов подписания и отправки транзакций (POST /transactions/sign и POST /transactions/broadcast), предусмотрен комбинированный метод POST ​/transactions​/signAndBroadcast.

Этот метод подписывает транзакцию закрытым ключом отправителя и отправляет её в блокчейн без промежуточной передачи информации между методами.

В запросе метод signAndBroadcast принимает json транзакции, которую нужно подписать. JSON-представления транзакций приведены в разделе Описание транзакций. В ответе метод возвращает код 200, если транзакция успешно подписана и отправлена, или код ошибки.

Важно

Метод ​/transactions​/signAndBroadcast недоступен при использовании PKI, то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение ON. Метод можно использовать в тестовом режиме PKI (node.crypto.pki.mode = TEST) или при отключенном PKI (node.crypto.pki.mode = OFF).

Примечание

При использовании тестового режима PKI (то есть когда в конфигурационном файле ноды параметру node.crypto.pki.mode присвоено значение TEST) когда новый пользователь, который не является владельцем ноды (node-owner), публикует свою первую транзакцию, он должен приложить к ней цепочку своих сертификатов, которая соответствует публичному ключу в поле target транзакции. Для этого предназначено поле certificates в запросе на публикацию транзакции.

Сертификаты прикладываются только для первой транзакции от нового адреса; затем они автоматически считываются из стейта.

Пример запроса метода с транзакцией 103 CreateContract:

POST ​/transactions​/signAndBroadcast:
{
  "type": 103,
  "version": 4,
  "sender": "3NpN3HyHzGj7Ny1k5F9zMMQ2n54TZg86G9D",
  "password": "signing-key-password",
  "image": "registry.yourdomain.com/test-docker-repo/contract:v1.0.0",
  "contractName": "Your contract name",
  "imageHash": "573387bbf50cfdeda462054b8d85d6c24007f91044501250877392e43ff5ed50",
  "params": [
  {
    "type": "string",
    "key": "test_key",
    "value": "test_value"
  }
  ],
  "fee": 100000000,
  "timestamp": 1651487626477,
  "feeAssetId": null,
  "atomicBadge": null,
  "validationPolicy": {
  "type": "majority"
  },
  "apiVersion": "1.0"
}

Информация о транзакциях

Группа transactions также включает следующие методы получения информации о транзакциях в блокчейне:

GET /transactions/info/{id}

Получение информации о транзакции по ее идентификатору {id}. Идентификатор транзакции указывается в ответе методов POST /transactions/sign или POST ​/transactions​/signAndBroadcast.

Метод возвращает данные транзакции, аналогичные ответам методов POST ​/transactions​/broadcast и POST ​/transactions​/signAndBroadcast.

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

GET /transactions/info/{id}:
{
  "type": 4,
  "id": "52GG9U2e6foYRKp5vAzsTQ86aDAABfRJ7synz7ohBp19",
  "sender": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "senderPublicKey": "CRxqEuxhdZBEHX42MU4FfyJxuHmbDBTaHMhM3Uki7pLw",
  "recipient": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "assetId": "E9yZC4cVhCDfbjFJCc9CqkAtkoFy5KaCe64iaxHM2adG",
  "amount": 100000,
  "fee": 100000,
  "timestamp": 1549365736923,
  "attachment": "string",
  "signature": "GknccUA79dBcwWgKjqB7vYHcnsj7caYETfncJhRkkaetbQon7DxbpMmvK9LYqUkirJp17geBJCRTNkHEoAjtsUm",
  "height": 7782
}

GET /transactions/address/{address}/limit/{limit}

Метод возвращает данные последних {limit} транзакций адреса {address}.

Для каждой транзакции возвращаются данные, аналогичные ответам методов POST ​/transactions​/broadcast и POST ​/transactions​/signAndBroadcast.

Пример ответа для одной транзакции:

GET /transactions/address/{address}/limit/{limit}:
[
[
  {
    "type": 2,
    "id": "4XE4M9eSoVWVdHwDYXqZsXhEc4q8PH9mDMUBegCSBBVHJyP2Yb1ZoGi59c1Qzq2TowLmymLNkFQjWp95CdddnyBW",
    "fee": 100000,
    "timestamp": 1549365736923,
    "signature": "4XE4M9eSoVWVdHwDYXqZsXhEc4q8PH9mDMUBegCSBBVHJyP2Yb1ZoGi59c1Qzq2TowLmymLNkFQjWp95CdddnyBW",
    "sender": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
    "senderPublicKey": "CRxqEuxhdZBEHX42MU4FfyJxuHmbDBTaHMhM3Uki7pLw",
    "recipient": "3N9iRMou3pgmyPbFZn5QZQvBTQBkL2fR6R1",
    "amount": 1000000000
  }
]
]

GET /transactions/unconfirmed

Метод возвращает данные всех транзакций из UTX-пула ноды.

Для каждой транзакции возвращаются данные, аналогичные ответам методов POST ​/transactions​/broadcast и POST ​/transactions​/signAndBroadcast.

Пример ответа для одной транзакции:

GET /transactions/unconfirmed:
[
  {
    "type": 4,
    "id": "52GG9U2e6foYRKp5vAzsTQ86aDAABfRJ7synz7ohBp19",
    "sender": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
    "senderPublicKey": "CRxqEuxhdZBEHX42MU4FfyJxuHmbDBTaHMhM3Uki7pLw",
    "recipient": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
    "assetId": "E9yZC4cVhCDfbjFJCc9CqkAtkoFy5KaCe64iaxHM2adG",
    "amount": 100000,
    "fee": 100000,
    "timestamp": 1549365736923,
    "attachment": "string",
    "signature": "GknccUA79dBcwWgKjqB7vYHcnsj7caYETfncJhRkkaetbQon7DxbpMmvK9LYqUkirJp17geBJCRTNkHEoAjtsUm"
  }
]

GET /transactions/unconfirmed/size

Метод возвращает число транзакций, находящихся в UTX-пуле, то есть количество транзакций, которые были отправлены в сеть, но еще не валидированы и не записаны в блок блокчейна в ходе раунда майнинга.

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

GET /transactions/unconfirmed/size:
{
  "size": 4
}

Примечание

Данные о размере UTX-пула в байтах и килобайтах можно получить с помощью gRPC метода UtxInfo.

GET /unconfirmed/info/{id}

Метод возвращает данные транзакции, находящейся в UTX-пуле, по ее {id}.

В ответе метода содержатся данные транзакции, аналогичные ответам методов POST ​/transactions​/broadcast и POST ​/transactions​/signAndBroadcast.

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

GET /unconfirmed/info/{id}:
{
  "type": 4,
  "id": "52GG9U2e6foYRKp5vAzsTQ86aDAABfRJ7synz7ohBp19",
  "sender": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "senderPublicKey": "CRxqEuxhdZBEHX42MU4FfyJxuHmbDBTaHMhM3Uki7pLw",
  "recipient": "3NBVqYXrapgJP9atQccdBPAgJPwHDKkh6A8",
  "assetId": "E9yZC4cVhCDfbjFJCc9CqkAtkoFy5KaCe64iaxHM2adG",
  "amount": 100000,
  "fee": 100000,
  "timestamp": 1549365736923,
  "attachment": "string",
  "signature": "GknccUA79dBcwWgKjqB7vYHcnsj7caYETfncJhRkkaetbQon7DxbpMmvK9LYqUkirJp17geBJCRTNkHEoAjtsUm",
  "height": 7782
}

POST /transactions/calculateFee

Метод возвращает сумму комиссии за отправленную транзакцию.

В запросе указываются параметры, аналогичные запросу POST /transactions/broadcast. В ответе метода возвращается идентификатор ассета, в котором взимается комиссия (null для WAVES).

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

POST /transactions/calculateFee:
{
  "feeAssetId": null,
  "feeAmount": 10000
}
Смотрите также

Методы REST API

Транзакции блокчейн-платформы

Описание транзакций