getSignatureStatuses позволяет получить статус обработки и подтверждения списка подписей транзакций. Это полезно, чтобы определить, были ли транзакции обработаны, подтверждены или финализированы сетью.
Если параметр searchTransactionHistory не включен, этот метод преимущественно обращается к кешу недавних статусов на RPC-узле. Для более старых транзакций крайне важно включить searchTransactionHistory.
Распространенные сценарии использования
- Подтверждение финальности транзакции: проверка того, достигла ли отправленная транзакция требуемого уровня подтверждения (например,
confirmedилиfinalized). - Пакетная проверка статусов: эффективная одновременная проверка статуса нескольких транзакций, например после пакетной отправки.
- Обновление пользовательского интерфейса на основе состояния транзакции: отображение пользователю статуса транзакции в реальном времени.
- Проверка ошибок: определение того, завершилась ли какая-либо транзакция из списка с ошибкой и почему.
Параметры запроса
signatures(arrayизstring): (Обязательный) Массив подписей транзакций в кодировке base-58. В одном запросе можно проверить до 256 подписей.options(object, необязательный): необязательный объект конфигурации со следующим полем:searchTransactionHistory(boolean, необязательный): если указаноtrue, RPC-узел выполнит поиск подписей по всей истории транзакций. Если указаноfalse(значение по умолчанию), поиск выполняется только в кеше недавних статусов. Для старых или потенциально отброшенных транзакций задайте значениеtrue.
Структура ответа
Полеresult ответа JSON-RPC содержит объект с двумя полями:
context(object): объект, содержащий:slot(u64): слот, в котором RPC-узел обработал этот запрос.
value(arrayизobject|null): массив объектов статуса, порядок которых соответствует порядку подписей в запросе. Каждый элемент может быть:- Объектом со следующими полями, если подпись найдена:
slot(u64): слот, в котором была обработана транзакция.confirmations(number|null): количество блоков, подтвержденных после обработки транзакции. Значениеnull, если транзакция финализирована, поскольку финальность означает, что она не будет отменена и точное количество подтверждений уже не столь важно.err(object|null): объект ошибки, если транзакция завершилась с ошибкой (например,{"InstructionError":[0,{"Custom":1}]}), илиnull, если она выполнена успешно.status(object): объект, указывающий статус выполнения транзакции. Обычно{"Ok":null}для успешно выполненных транзакций или объект с подробными сведениями об ошибке для неудачных.confirmationStatus(string|null): статус подтверждения транзакции в кластере (например,processed,confirmed,finalized). Может иметь значениеnull, если статус отсутствует в кеше, аsearchTransactionHistoryимеет значение false.
null: если подпись не найдена в кеше статусов иsearchTransactionHistoryимеет значениеfalse(или если она действительно не существует даже при поиске по истории).
- Объектом со следующими полями, если подпись найдена:
Примеры
1. Получение статуса списка подписей (кеш недавних данных)
В этом примере извлекается статус двух подписей из кеша недавних данных узла.2. Получение статуса с поиском по истории транзакций
В этом примере извлекается статус подписей и явно запрашивается поиск по истории транзакций узла.Рекомендации разработчикам
searchTransactionHistory: критически важно для надежности. Если установлено значениеfalse(по умолчанию), метод проверяет только ограниченный кеш недавних данных. Если транзакция старая или потенциально была отброшена и отсутствует в этом кеше, для статуса этой подписи будет возвращеноnull. Всегда задавайтеtrue, если необходимо подтвердить статус транзакций, которые могут быть не совсем новыми.- Ограничение количества подписей: за один вызов можно проверить не более 256 подписей.
- Статус
null: значениеnullв массивеvalueдля определенной подписи означает, что ее статус не найден. Причиной может быть отсутствие транзакции в кеше недавних данных (еслиsearchTransactionHistoryимеет значение false), то, что транзакция никогда не попала в блок, или то, что она слишком старая и отсутствует в истории узла даже при использованииsearchTransactionHistory: true. confirmations: null: обычно это означает, что транзакция достигла статусаfinalized. На этом этапе конкретное количество подтверждений уже не столь важно, поскольку блок считается необратимым.- Обработка ошибок: проверьте поле
errв каждом объекте статуса, чтобы определить, завершилась ли транзакция с ошибкой. Полеstatusтакже содержит подробные сведения (например,{"Err":...}).
getSignatureStatuses — эффективный способ отслеживать состояние нескольких транзакций Solana. Для надежной проверки статуса используйте searchTransactionHistory: true.