Apresentamos a Parsed Events API e o Parsed Streams

Por que é difícil ler transações da Solana?

Quando você consulta nós RPC padrão para saber o que aconteceu em uma transação, recebe uma lista de endereços de contas sem nomes e os dados das instruções como um blob base58 opaco.

Para transformar isso em "esta carteira trocou 1.500 SOL por PUMP na Jupiter", tradicionalmente você precisa:

1. Buscar a transação e identificar todos os programas com os quais ela interagiu
2. Encontrar a IDL de cada programa (sua interface publicada), caso exista
3. Decodificar os dados da instrução (geralmente Borsh) usando essa IDL
4. Mapear as contas posicionais para suas funções: o terceiro endereço é a autoridade ou o destino? Somente a interface do programa sabe
5. Percorrer recursivamente as instruções internas (CPIs), onde ocorre a maior parte da atividade real, como as movimentações de tokens dentro de um swap
6. Repetir o processo para cada programa relevante e manter seus decodificadores atualizados à medida que os programas lançam novas versões

São semanas de trabalho de engenharia antes mesmo de você responder a uma única pergunta, e essa é uma das curvas de aprendizado mais íngremes para quem começa na Solana. Os dados da blockchain são públicos, mas não são legíveis.

Criamos uma camada de decodificação no servidor para que você não precise fazer isso.

O que uma resposta da Parsed Events inclui?

Cada transação é retornada decodificada pelo catálogo de IDLs da Helius. 

Este é um swap real da Jupiter, reduzido aos principais pontos:

{
  "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…" }
        ]
      }
    }
  ]
}

Em vez de tentar adivinhar o significado do terceiro endereço em uma lista de contas, você lê "name": "user_transfer_authority". 

Os argumentos também chegam decodificados: "slippage_bps": 2200 em vez de bytes brutos.

E o summary no nível da transação pode ser exibido aos usuários sem alterações.

Cada resultado também inclui a taxa e seu pagador, transferências nativas de SOL, transferências de SPL e Token-2022 e erros decodificados de programas personalizados quando os metadados estão disponíveis. 

Para programas que não estão no catálogo, as instruções usam como fallback os dados e as contas em formato bruto, então você sempre tem algo com que trabalhar.

Parsed Streams: transações decodificadas enviadas a você

O Parsed Streams é um serviço WebSocket que monitora todas as transações confirmadas, as decodifica e envia a você aquelas que correspondem ao seu filtro no nível da instrução, diretamente no servidor.

Você nunca precisa lidar com um fluxo completo de dados nem manter um decodificador.

Um filtro é composto por cinco campos:

1. programs
2. instructionNames
3. accounts (por inclusão ou função nomeada)
4. includeCpi
5. includeFailed

Por exemplo, "todas as instruções de rota da Jupiter que interagem com esta carteira" fica assim:

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

Cada notificação contém a transação decodificada completa, e matchedIndexes aponta para as instruções que corresponderam ao seu filtro.

Como obter os nomes das instruções de programas da Solana?

Adivinhar nomes de instruções é a maneira mais comum de criar um filtro que, silenciosamente, não encontra nada. Para obter os nomes das instruções de programas da Solana, chame describeProgram com o endereço de qualquer programa. Ele retorna as instruções, os eventos e as funções das contas que o mecanismo compara:

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

Consulte o programa, adicione os nomes ao seu filtro e faça a assinatura. 

O guia para acompanhar swaps da Jupiter explica esse fluxo de trabalho do início ao fim.

A Parsed Events API: transações decodificadas sob demanda

Para consultas em vez de dados em tempo real, a Parsed Events API aplica, mediante solicitação, a mesma decodificação baseada no catálogo de IDLs.

O Parse Transactions recebe assinaturas e as retorna decodificadas.

O Parsed Transaction History percorre por páginas todo o histórico decodificado de um endereço e retorna primeiro as transações mais recentes.

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"]}'

Os dois métodos também estão disponíveis via GraphQL, permitindo que você selecione apenas os campos decodificados necessários para seu aplicativo.

Parsed Events vs. Enhanced Transaction API

A Parsed Events é a sucessora da Enhanced Transactions API. 

Enquanto a Enhanced Transactions classificava as transações em uma lista fixa de tipos de eventos, a Parsed Events decodifica cada instrução por meio do catálogo de IDLs, usando dados brutos como fallback em vez de UNKNOWN para programas não reconhecidos.

Se você usa a Enhanced Transactions API atualmente, o guia de migração mapeia todos os endpoints, parâmetros e campos de resposta, além de incluir um prompt que seu agente pode executar para concluir a migração por você.

Qual ferramenta de análise é ideal para mim?

Os dois novos produtos usam o mesmo mecanismo de decodificação, então uma transação tem a mesma aparência, seja ela recebida por um stream ou por uma chamada REST. Mais importante: você pode criar um protótipo com dados históricos na Parsed Events e migrar para dados em tempo real com o Parsed Streams sem alterar seu código de análise.

Comece agora

O Parsed Streams e a Parsed Events API estão em beta aberto e disponíveis em todos os planos pagos. Obtenha sua chave de API no painel da Helius.

Para se conectar, use os seguintes endpoints:

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

Guias

O guia de início rápido do Parsed Streams ajuda você a receber sua primeira notificação decodificada em poucos minutos, e o guia de início rápido da Parsed Events faz o mesmo para sua primeira assinatura decodificada. 

Se tiver dúvidas, entre em contato conosco pelo Telegram ou Discord.