Представляем Parsed Events API и Parsed Streams

Почему транзакции Solana сложно читать?

Когда вы запрашиваете у стандартных RPC-нод информацию о том, что произошло в транзакции, то получаете список адресов аккаунтов без названий, а данные инструкций — в виде непрозрачной строки base58.

Чтобы преобразовать это в «этот кошелёк обменял 1 500 SOL на PUMP через Jupiter», раньше требовалось:

1. Получить транзакцию и определить все задействованные программы
2. Найти IDL каждой программы — её опубликованный интерфейс, если он существует
3. Декодировать данные инструкций, обычно в формате Borsh, с помощью этого IDL
4. Сопоставить позиционные аккаунты с их ролями: третий адрес — это полномочия или получатель? Ответ есть только в интерфейсе программы
5. Рекурсивно обработать внутренние инструкции (CPI), где происходит большая часть реальных действий, например перемещения токенов внутри обмена
6. Повторить это для каждой нужной программы и обновлять декодеры по мере выхода новых версий программ

Это недели инженерной работы ещё до того, как вы получите ответ на первый вопрос. А также один из самых сложных этапов начала работы с Solana. Данные блокчейна публичны, но их трудно читать.

Мы создали серверный слой декодирования, чтобы вам не приходилось делать это самостоятельно.

Что входит в ответ Parsed Events?

Каждая транзакция возвращается декодированной с помощью каталога IDL Helius. 

Вот реальный обмен через Jupiter, сокращённый до главного:

{
  "summary": {
    "type": "swap",
    "description": "GV6UUm… swapped 1500 SOL for 64672839.26195 PUMP via Jupiter",
    "parsedData": {
      "protocol": "jupiter",
      "in_amount": "1500000000000",
      "actual_out_amount": "64672839261950",
      "input_mint": "So11111111111111111111111111111111111111112",
      "output_mint": "pumpCmXqMfrsAkQ5r49WcJnRayYRqmXz6ae8H7H9Dfn"
    }
  },
  "instructions": [
    {
      "programName": "jupiter",
      "instructionName": "shared_accounts_route_v2",
      "decoded": {
        "args": { "in_amount": "1500000000000", "slippage_bps": 2200 },
        "accounts": [
          { "name": "user_transfer_authority", "pubkey": "GV6UUm…", "isSigner": true },
          { "name": "source_mint", "pubkey": "So1111…" }
        ]
      }
    }
  ]
}

Вместо догадок о значении третьего адреса в списке аккаунтов вы читаете "name": "user_transfer_authority". 

Аргументы также поступают в декодированном виде: "slippage_bps": 2200 вместо необработанных байтов.

А summary на уровне транзакции можно дословно показать пользователям.

Каждый результат также содержит комиссию и её плательщика, нативные переводы SOL, переводы SPL и Token-2022, а также декодированные пользовательские ошибки программ, если доступны метаданные. 

Для программ вне каталога инструкции возвращаются в виде необработанных данных и аккаунтов, поэтому у вас всегда будет информация для дальнейшей работы.

Parsed Streams: декодированные транзакции с автоматической доставкой

Parsed Streams — это WebSocket-сервис, который отслеживает каждую подтверждённую транзакцию, декодирует её и на стороне сервера выбирает и отправляет вам транзакции, соответствующие вашему фильтру на уровне инструкций.

Вам не нужно обрабатывать весь поток данных или поддерживать декодер.

Фильтр состоит из пяти полей:

1. programs
2. instructionNames
3. accounts (по наличию или именованной роли)
4. includeCpi
5. includeFailed

Например, фильтр «каждая инструкция маршрута Jupiter, затрагивающая этот кошелёк» выглядит так:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "parsedTransactionSubscribe",
  "params": [
    {
      "programs": ["JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"],
      "instructionNames": ["route", "shared_accounts_route"]
    }
  ]
}

Каждое уведомление содержит всю декодированную транзакцию, а matchedIndexes указывает на инструкции, которые соответствуют вашему фильтру.

Как получить названия инструкций программ Solana?

Неверно угаданные названия инструкций — самая распространённая причина, по которой фильтр неявно не находит совпадений. Чтобы получить названия инструкций программ Solana, вызовите describeProgram с адресом любой программы. Метод вернёт инструкции, события и роли аккаунтов, с которыми выполняется сопоставление:

{
  "id": "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4",
  "name": "jupiter",
  "instructions": ["route", "shared_accounts_route", "exact_out_route"],
  "events": ["SwapEvent"],
  "roles": ["user_transfer_authority", "destination_token_account"]
}

Найдите программу, добавьте названия в фильтр, а затем оформите подписку. 

В руководстве «Отслеживание обменов Jupiter» этот процесс разобран от начала до конца.

Parsed Events API: декодированные транзакции по запросу

Для разовых запросов вместо потоковых данных Parsed Events API по запросу применяет такое же декодирование на основе каталога IDL.

Parse Transactions принимает подписи и возвращает их в декодированном виде.

Parsed Transaction History постранично возвращает полную декодированную историю адреса, начиная с самых новых транзакций.

curl -X POST "https://mainnet.helius-rpc.com/v1/parsed-events/transactions?api-key=YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"transactions": ["5xSKzM8bvpudE521jikHqASzMr23Ms4X4ieY3K8oFPFrJWCSSgYocJmHznrR8b12voDxKDH8ykdCLXSRrx6duVLH"]}'

Оба метода также доступны через GraphQL, поэтому вы можете выбрать только те разобранные поля, которые нужны вашему приложению.

Parsed Events и Enhanced Transaction API

Parsed Events — преемник Enhanced Transactions API. 

Enhanced Transactions классифицировал транзакции по фиксированному списку типов событий. Parsed Events декодирует каждую инструкцию через каталог IDL, а для неизвестных программ возвращает необработанные данные вместо UNKNOWN.

Если вы используете Enhanced Transactions API, руководство по миграции сопоставляет все эндпоинты, параметры и поля ответов. Оно также содержит промпт, с помощью которого ваш агент может выполнить миграцию за вас.

Какой инструмент разбора мне подходит?

Оба новых продукта используют единый механизм декодирования, поэтому транзакция выглядит одинаково независимо от того, получена она через поток или вызов REST. Что особенно важно, вы можете создать прототип на исторических данных с помощью Parsed Events, а затем перейти к потоковым данным через Parsed Streams, не меняя код разбора.

Начало работы

Parsed Streams и Parsed Events API находятся в открытой бета-версии и доступны на всех платных планах. Получите ключ API в панели управления Helius.

Для подключения используйте следующие эндпоинты:

Parsed Streams: 

wss://fs-beta.helius-rpc.com/?api-key=YOUR_API_KEY

Parsed Events API: 

https://mainnet.helius-rpc.com/v1/parsed-events/...?api-key=YOUR_API_KEY

Руководства

Краткое руководство по Parsed Streams поможет за несколько минут получить первое декодированное уведомление, а краткое руководство по Parsed Events — разобрать первую подпись. 

Если у вас есть вопросы, свяжитесь с нами в Telegram или Discord.