Зачем выполнять миграцию?
Стандартный способ получения истории транзакций адреса в 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 или другого агента для написания кода, вставьте приведенный ниже промпт в сеанс агента для вашего репозитория. Агент найдет старый шаблон в кодовой базе и перепишет его.Следующие шаги
getTransactionsForAddress guide
Полное руководство по фильтрам, сортировке, пагинации и счетам токенов.
API reference
Полная схема запроса и ответа.
Indexing guide
Используйте getTransactionsForAddress для заполнения историческими данными и синхронизации индекса Solana.
Historical data overview
Сравнение всех методов работы с историческими данными Solana.