Подписка на аккаунты
В этой подписке передаются новые транзакции и состояния аккаунтов из воркчейнов -1 и 0 по возрастанию seqno блоков. Вы можете настроить список аккаунтов и выбрать, какие именно данные аккаунта получать.
Структура уведомления
Когда новый блок будет сформирован, вы получите уведомление, которое содержит данные только для аккаунтов, которые указаны в подписке и имеются в блоке.
Пример реального уведомления можно посмотреть тут.
{
"jsonrpc": "2.0",
"method": "account",
"params": {
"id": {
"@type": "tonNode.blockIdExt",
"workchain": 0,
"shard": -9223372036854775808,
"seqno": 1234567890,
"root_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
"file_hash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
},
"accounts": {
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=": { // хэш аккаунта
"state": {
/* TL-B-схема 'ShardAccount' в 'block.tlb' */
},
"transactions": {
"AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=": { // хэш транзакции
/* TL-B-схема 'Transaction' в 'block.tlb' */
}
}
}
}
}
} | Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| id | object | Да | Расширенный идентификатор блока. TL-схема tonNode.blockIdExt в ton_api.tl. |
| accounts | object | Да | Список аккаунтов, которые имеют обработанные транзакции в блоке. Ключ - хэш аккаунта (часть адреса аккаунта), значение - данные аккаунта. |
| state | object | Нет | Измененное состояние аккаунта в блоке. TL-B-схема ShardAccount в block.tlb. Поле присутствует, если include_account_states установлен true. |
| transactions | object | Нет | Список обработанных транзакций в блоке для этого аккаунта, отсортированных по возрастанию параметра lt транзакции. Ключ - хэш транзакции, значение - TL-B-схема Transaction в block.tlb. Поле присутствует, если include_transactions установлен true. |
Создание подписки
Подписка на аккаунты
Чтобы подписаться на определенные аккаунты, укажите их адреса списком в параметре addresses.
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": {
"subscription": "account",
"addresses": [
"Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF",
"-1:5555555555555555555555555555555555555555555555555555555555555555"
],
"include_transactions": true
},
"id": 1
} При создании подписки обязательно нужно указать как минимум один аккаунт. Адреса аккаунтов можно указывать в любом формате.
При создании подписки обязательно нужно установить true как минимум для одного параметра include_*.
Настройка получаемых данных
Чтобы получать только определенные данные аккаунтов, установите true для нужного параметра include_*.
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": {
"subscription": "account",
"addresses": [
"Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF",
"-1:5555555555555555555555555555555555555555555555555555555555555555"
],
"include_account_states": true
},
"id": 1
} Ответ сервера
После каждого запроса в ответ вы будете получать сообщение с текущими параметрами подписки, чтобы видеть актуальную подписку на сервере.
Адреса в ответе возвращаются в raw-формате.
{
"jsonrpc": "2.0",
"result": {
"subscription": "account",
"addresses": [
"-1:3333333333333333333333333333333333333333333333333333333333333333",
"-1:5555555555555555555555555555555555555555555555555555555555555555"
],
"include_transactions": false,
"include_account_states": true
},
"id": 1
} | Поле | Тип | Обязательное | Описание |
|---|---|---|---|
| subscription | string | Да | Имя подписки. По умолчанию всегда account. |
| addresses | string[] | Нет | Список аккаунтов. |
| include_transactions | bool | Нет | Включать ли транзакции аккаунтов в уведомления. |
| include_account_states | bool | Нет | Включать ли состояния аккаунтов в уведомления. |
Уникальность адресов
Подписка может содержать только уникальные адреса аккаунтов. Адреса сравниваются по воркчейну и хэшу аккаунта. Если запрос будет содержать дубликаты адресов, в подписку будет добавлен только один.
Ниже представлены одинаковые адреса аккаунтов, разница только в их формате.
Raw-формат:
-1:3333333333333333333333333333333333333333333333333333333333333333 Friendly-формат с флагом bounceable:
Ef8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzM0vF Friendly-формат с флагом non-bounceable:
Uf8zMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMzMxYA Управление подпиской
Допустим, у вас есть подписка с такими параметрами.
{
"subscription": "account",
"addresses": [
"-1:3333333333333333333333333333333333333333333333333333333333333333"
],
"include_transactions": false,
"include_account_states": true
} Добавление аккаунтов
Чтобы добавить к этой подписке другие аккаунты, укажите их в параметре addresses.
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": {
"subscription": "account",
"addresses": [
"-1:5555555555555555555555555555555555555555555555555555555555555555"
]
},
"id": 2
} В ответ вы получите сообщение с обновленными параметрами подписки.
{
"jsonrpc": "2.0",
"result": {
"subscription": "account",
"addresses": [
"-1:3333333333333333333333333333333333333333333333333333333333333333",
"-1:5555555555555555555555555555555555555555555555555555555555555555"
],
"include_transactions": false,
"include_account_states": true
},
"id": 2
} Если адрес, указанный в запросе, уже есть в подписке, он будет проигнорирован.
Добавление параметров
Чтобы добавить параметры include_*, укажите true для нужного параметра, а в addresses укажите [].
{
"jsonrpc": "2.0",
"method": "subscribe",
"params": {
"subscription": "account",
"addresses": [],
"include_transactions": true
},
"id": 3
} В ответ вы получите сообщение с обновленными параметрами подписки.
{
"jsonrpc": "2.0",
"result": {
"subscription": "account",
"addresses": [
"-1:3333333333333333333333333333333333333333333333333333333333333333",
"-1:5555555555555555555555555555555555555555555555555555555555555555"
],
"include_transactions": true,
"include_account_states": true
},
"id": 3
} Добавление аккаунтов и параметров include_* можно делать в одном запросе.
Удаление аккаунтов
Чтобы убрать аккаунты из подписки, укажите их в параметре addresses.
Если в параметр addresses указать все аккаунты, которые есть в подписке, она будет полностью удалена.
{
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": {
"subscription": "account",
"addresses": [
"-1:5555555555555555555555555555555555555555555555555555555555555555"
]
},
"id": 4
} В ответ вы получите сообщение с обновленными параметрами подписки.
{
"jsonrpc": "2.0",
"result": {
"subscription": "account",
"addresses": [
"-1:3333333333333333333333333333333333333333333333333333333333333333"
],
"include_transactions": true,
"include_account_states": true
},
"id": 4
} Удаление параметров
Чтобы удалить параметры include_*, укажите true для нужного параметра, а в addresses укажите [].
В запросе unsubscribe значение true удаляет соответствующий тип данных из подписки.
{
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": {
"subscription": "account",
"addresses": [],
"include_transactions": true
},
"id": 5
} В ответ вы получите сообщение с обновленными параметрами подписки.
{
"jsonrpc": "2.0",
"result": {
"subscription": "account",
"addresses": [
"-1:3333333333333333333333333333333333333333333333333333333333333333"
],
"include_transactions": false,
"include_account_states": true
},
"id": 5
} Если в параметр addresses указать null или опустить его, подписка будет полностью удалена.
Удаление аккаунтов и параметров include_* можно делать в одном запросе.
Удаление подписки
Чтобы полностью удалить подписку, укажите только её название без других параметров.
{
"jsonrpc": "2.0",
"method": "unsubscribe",
"params": {
"subscription": "account"
},
"id": 6
} В ответ вы получите сообщение об удалении подписки.
{
"jsonrpc": "2.0",
"result": {
"subscription": "account",
"include_transactions": false,
"include_account_states": false
},
"id": 6
}