Skip to main content

Зачем выполнять миграцию?

Стандартный способ получения истории транзакций адреса в Solana состоит из двух шагов: вызовите getSignaturesForAddress, чтобы получить список подписей, а затем вызовите getTransaction по одному разу для каждой подписи, чтобы получить подробные данные. Для 1 000 транзакций потребуется 1 001 HTTP-запрос. getTransactionsForAddress — эксклюзивный RPC-метод Helius, объединяющий оба шага в один вызов. Он возвращает до 1 000 полных транзакций на запрос и поддерживает фильтрацию, двунаправленную сортировку и счета токенов, недоступные в стандартных методах. Результат: примерно в 10 раз меньше кредитов, в 1 000 раз меньше сетевых запросов и отсутствие необходимости в пакетной обработке на стороне клиента, управлении ограничениями частоты запросов и логике повторных попыток для множества вызовов getTransaction.

До и после

Ниже показано, как выполнить одну и ту же задачу — получить последние 1 000 транзакций адреса со всеми подробными данными — обоими способами:
getTransactionsForAddress не входит в стандартный RPC Solana, поэтому в @solana/web3.js нет вспомогательного метода Connection для него. Вызывайте его с помощью необработанного JSON-RPC-запроса, как показано выше. Он работает на той же конечной точке Helius, что и остальной RPC-трафик.

Сопоставление параметров

Каждому параметру старого двухэтапного процесса соответствует параметр в новом методе. Большинство названий не изменились — иначе работает только пагинация.

Из getSignaturesForAddress

Из getTransaction

Две возможности вообще не имеют эквивалентов в старом процессе:
  • filters — ограничивайте результаты на стороне сервера по blockTime, slot, status, tokenTransfer или tokenAccounts вместо получения всех данных и их фильтрации в коде.
  • sortOrder: "asc" — результаты в хронологическом порядке (сначала старые), которые стандартные методы могут вернуть только после получения всей истории и изменения ее порядка.

Этапы миграции

1

Confirm you're on a Helius endpoint

getTransactionsForAddress доступен только в Helius. Он работает на https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY (и в devnet) — на той же конечной точке, которую уже используют ваши существующие вызовы, если вы являетесь клиентом Helius. Изменять ключ API или тарифный план не требуется.
2

Replace the two-step fetch with one call

Удалите вызов getSignaturesForAddress и цикл getTransaction. Выполните один запрос getTransactionsForAddress с transactionDetails: "full", перенеся значения encoding, maxSupportedTransactionVersion и commitment, как показано в разделе сопоставления параметров.Если вам нужны только подписи (например, для передачи в существующий конвейер), используйте вместо этого transactionDetails: "signatures" — каждый вызов всегда стоит 10 кредитов.
3

Update the response handling

Структура ответа изменяется в трех аспектах:
  • Результаты находятся в result.data (массиве), а не непосредственно в result.
  • Каждая запись в полном режиме представляет собой { slot, transactionIndex, blockTime, transaction, meta }. Объекты transaction и meta имеют ту же структуру, что и возвращаемые getTransaction, поэтому код синтаксического анализа можно перенести без изменений.
  • Записи в режиме подписей соответствуют выходным данным getSignaturesForAddress (signature, slot, err, memo, blockTime, confirmationStatus), но содержат дополнительное поле transactionIndex.
Учтите одно отличие в поведении: при использовании старого подхода вызов getTransaction мог вернуть null для подписи. При использовании getTransactionsForAddress каждая запись в result.data представляет собой полную транзакцию — удалите обработку null для отсутствующих подробных данных.
4

Replace signature-based pagination

Замените цикл с курсором before на paginationToken:
Цикл завершается, когда paginationToken получает значение null. Больше не нужно сравнивать списки подписей или самостоятельно отслеживать последнюю подпись.Если вы использовали until для остановки на известной подписи, замените его на filters.signature: { gt: "KNOWN_SIGNATURE" }. Если вы использовали его для остановки в определенный момент времени, обычно удобнее использовать filters.blockTime или filters.slot.
5

Optional: enable complete token history

Старый подход полностью пропускает активность связанных счетов токенов (ATA), если вы дополнительно не вызывали getTokenAccountsByOwner и не получали подписи для каждого счета токенов. Чтобы включить эту активность, добавьте один фильтр:
balanceChanged возвращает транзакции, которые ссылаются на кошелек или изменяют баланс любого принадлежащего ему счета токенов, отфильтровывая спам. Описание параметров none/balanceChanged/all и оговорку о данных до 2022 года см. в разделе связанных счетов токенов.
6

Verify against the old output

Для тестового адреса получите историю обоими способами и сравните наборы подписей. Если filters.tokenAccounts не задан (по умолчанию используется none), getTransactionsForAddress возвращает те же транзакции, что и getSignaturesForAddress для того же диапазона. Затем разверните изменения и удалите старый путь выполнения кода.

Отличия в поведении, которые нужно проверить

В большинстве случаев миграция сводится к прямой замене, но перед выпуском проверьте следующее:
  • Уровень подтверждения. processed не поддерживается; используйте confirmed или finalized. Если старый код опрашивал недавнюю историю с уровнем processed, перейдите на confirmed.
  • Тарификация. Ответы с полными транзакциями стоят 10 кредитов за каждые 100 возвращенных транзакций (минимум 10 кредитов); ответы только с подписями всегда стоят 10 кредитов. Старый подход стоил 1 кредит за вызов — дешевле за запрос, но значительно дороже за каждую полученную транзакцию. Неудачные ответы бесплатны. См. раздел тарификации.
  • Поддержка сетей. В mainnet срок хранения не ограничен. Devnet поддерживается со сроком хранения 2 недели. Testnet не поддерживается.
  • Зарезервированные адреса. Небольшой набор системных адресов (Vote Program, System Program, системные переменные) перенаправляется на резервные архивные пути или возвращает пустой результат. Если вы индексируете такие адреса, ознакомьтесь с разделом ограничений и пограничных случаев.
  • Несколько адресов. Как и в старом процессе, один запрос охватывает один адрес. Запрашивайте адреса параллельно и объединяйте результаты; см. раздел нескольких адресов.

Часто задаваемые вопросы

Является ли getTransactionsForAddress стандартным RPC-методом Solana?

Нет. Это эксклюзивный метод Helius, доступный на конечных точках RPC Helius. Стандартный RPC Solana и другие поставщики предлагают только getSignaturesForAddress и getTransaction. Это не влияет на другие ваши RPC-вызовы: метод доступен на той же конечной точке вместе с полным набором стандартных RPC-методов.

Нужен ли getTransaction после миграции?

Только для единичных запросов, когда у вас уже есть подпись, но нет контекста адреса, например при проверке конкретной транзакции, вставленной пользователем. Для любой истории на основе адреса — заполнения историческими данными, индексирования, лент активности кошелька — getTransactionsForAddress заменяет оба метода.

Работает ли метод с @solana/web3.js?

Метод отсутствует в классе Connection, но работает с любым HTTP-клиентом, отправляющим запросы на ваш RPC URL Helius. Используйте fetch (или эквивалент для вашего языка) со стандартным телом JSON-RPC, как показано в примерах выше. Для всего остального можно продолжать использовать Connection.

Вернет ли он те же транзакции, что и getSignaturesForAddress?

Да. С настройками по умолчанию (filters.tokenAccounts: "none") он возвращает транзакции, которые ссылаются на запрашиваемый адрес, — тот же набор, что и getSignaturesForAddress. Если установить для tokenAccounts значение balanceChanged или all, метод вернет больше данных: он добавит активность связанных счетов токенов кошелька, которую стандартный метод не видит.

Сколько это стоит по сравнению со старым подходом?

Получение 1 000 полных транзакций с помощью getTransactionsForAddress стоит 100 кредитов, а с помощью getSignaturesForAddress + getTransaction — примерно 1 001 кредит (и 1 001 запрос). Ответы только с подписями всегда стоят 10 кредитов за вызов. Полные сведения о ценах см. на странице кредитов Helius.

Поручите миграцию AI-агенту

Если вы используете Claude Code, Cursor или другого агента для написания кода, вставьте приведенный ниже промпт в сеанс агента для вашего репозитория. Агент найдет старый шаблон в кодовой базе и перепишет его.
Промпт самодостаточен — агенту не нужен доступ к этой странице. Документацию для агентов, поиск MCP и навыки см. в разделе Helius для AI-агентов.

Следующие шаги

getTransactionsForAddress guide

Полное руководство по фильтрам, сортировке, пагинации и счетам токенов.

API reference

Полная схема запроса и ответа.

Indexing guide

Используйте getTransactionsForAddress для заполнения историческими данными и синхронизации индекса Solana.

Historical data overview

Сравнение всех методов работы с историческими данными Solana.