Monitoramento de Transações - Helius LaserStream

O monitoramento de transações permite que você acompanhe a execução de transações, status de sucesso/falha, interações com programas e mudanças de saldo de tokens na Solana em tempo real. Este guia abrange estratégias de filtragem e implementações práticas usando o SDK helius-laserstream.

Pré-requisitos: Este guia assume que você completou o Quickstart do LaserStream gRPC e possui uma chave de API.

Opções de Filtragem de Transação

O LaserStream usa a mesma forma de filtro que o Yellowstone gRPC, incluindo o filtro tokenAccounts (expansão ATA). Os campos que você definirá dentro de transactions.<label>:

accountInclude — corresponde se qualquer uma destas contas aparecer (OU lógico)
accountRequired — corresponde somente se todas estas contas aparecerem (E lógico)
accountExclude — descarta se qualquer uma destas contas aparecer
vote / failed — sinalizadores booleanos para transações de voto e com falha
tokenAccounts — habilita a expansão da conta de token associada (ATA) ("balanceChanged", "all" ou "none"), para que uma carteira em accountInclude também corresponda às transações nas quais ela possui um saldo de token SPL. Consulte Filtragem por conta de token (ATA) e a guia Watching a Wallet abaixo.
matchMints — sinalizador opcional que também compara as listas de contas aos mints nos saldos de token anteriores/posteriores de uma transação, para que um mint em accountInclude capture cada transferência, swap, mint e burn desse token. Consulte Filtragem por mint de token e a guia Watching a Token abaixo.

Filtragem de Programa
Específico de Conta
Filtragem Avançada
Assistindo uma Carteira
Watching a Token

Monitore transações envolvendo programas específicosAcompanhe todas as transações que tocam programas de seu interesse:

import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';

const subscriptionRequest: SubscribeRequest = {
  transactions: {
    "program-filter": {
      accountInclude: [
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Token Program
        "11111111111111111111111111111111",              // System Program
        "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8"  // Your program
      ],
      accountExclude: [],
      accountRequired: [],
      vote: false,
      failed: false
    }
  },
  commitment: CommitmentLevel.CONFIRMED,
  accounts: {},
  slots: {},
  transactionsStatus: {},
  blocks: {},
  blocksMeta: {},
  entry: {},
  accountsDataSlice: [],
};

Melhor para: Monitoramento específico de programa, rastreamento de protocolo DeFi, interações com contratos inteligentes.

Monitore transações afetando contas específicas

const subscriptionRequest: SubscribeRequest = {
  transactions: {
    "wallet-filter": {
      accountInclude: [
        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint
        "YourWalletAddress"                                // Your wallet
      ],
      accountExclude: [],
      accountRequired: [],
      vote: false,
      failed: true // Include failures to track errors
    }
  },
  commitment: CommitmentLevel.CONFIRMED,
  accounts: {}, slots: {}, transactionsStatus: {},
  blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};

Uso: Monitoramento de carteira, rastreamento de emissão de token, dashboards de atividade de conta.

Combine múltiplos critérios de filtragem

const subscriptionRequest: SubscribeRequest = {
  transactions: {
    "advanced-filter": {
      accountInclude: ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"],
      accountRequired: ["YourProgramId"], // Must include this program
      accountExclude: ["VoteProgram"],     // Exclude vote-related txs
      vote: false,
      failed: false
    }
  },
  commitment: CommitmentLevel.CONFIRMED,
  accounts: {}, slots: {}, transactionsStatus: {},
  blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};

Lógica de filtragem: accountInclude (OU) E accountRequired (E) E NÃO accountExclude.

Capture transferências de tokens recebidas, não apenas atividade diretaaccountInclude só corresponde a transações onde a carteira aparece diretamente nas chaves de conta. Quando alguém envia um token SPL para a carteira, a transferência toca na conta de token associada (ATA) da carteira, não na chave pública da carteira — então uma accountInclude: [wallet] comum nunca vê isso.Defina tokenAccounts para expandir a correspondência para transações onde a carteira possui um saldo de token. Ele aceita uma string:

"balanceChanged" — corresponde quando um saldo de token possuído mudou (ou sua conta de token foi fechada). Melhor para “me diga quando o dinheiro realmente se moveu” — mais estreito, menor volume, o padrão recomendado.
"all" — corresponde a qualquer transação que faça referência a um saldo de token possuído, mesmo que não alterado. Volume substancialmente maior.
"none" — sem expansão (igual a omitir o campo).

const subscriptionRequest: SubscribeRequest = {
  transactions: {
    "wallet-with-tokens": {
      accountInclude: ["YourWalletAddress"],
      accountExclude: [],
      accountRequired: [],
      vote: false,
      failed: false,
      tokenAccounts: "balanceChanged" // also match the wallet's ATAs
    }
  },
  commitment: CommitmentLevel.CONFIRMED,
  accounts: {}, slots: {}, transactionsStatus: {},
  blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};

A correspondência é baseada no proprietário — ela captura qualquer conta de token pertencente à carteira (incluindo as não canônicas), não apenas o endereço ATA derivado. O SDK converte a string para o enum TokenAccountExpansionControlFlag no nível do protocolo para você.

Capture todas as transações de um mint, não apenas aquelas que o mencionamUm accountInclude: [mint] simples corresponde apenas às transações cujas chaves de conta contêm o mint, como MintTo, Burn ou TransferChecked. Um Transfer SPL clássico nunca referencia o mint, portanto, a maioria das transferências do token não é capturada.Defina matchMints: true, e as listas de contas também serão comparadas aos mints em preTokenBalances e postTokenBalances da transação:

const USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';

const subscriptionRequest: SubscribeRequest = {
  transactions: {
    "usdc-activity": {
      accountInclude: [USDC],
      accountExclude: [],
      accountRequired: [],
      vote: false,
      failed: false,
      matchMints: true // also match via pre/post token-balance mints
    }
  },
  commitment: CommitmentLevel.CONFIRMED,
  accounts: {}, slots: {}, transactionsStatus: {},
  blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
};

Combine-o com tokenAccounts para monitorar um token de uma carteira: coloque a carteira em accountInclude com tokenAccounts: "balanceChanged" e o mint em accountRequired com matchMints: true. Requer helius-laserstream 0.8.5+ (JS), 0.6.4+ (Rust) ou go/v0.3.0+ (Go). Consulte Filtragem por mint de token para ver a semântica completa.

Exemplos práticos

Exemplo 1: monitorar transações de DEX

Acompanhe transações que envolvem programas de DEX populares:

import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';
import bs58 from 'bs58';

async function monitorDEXTransactions() {
  const subscriptionRequest: SubscribeRequest = {
    transactions: {
      "dex-filter": {
        accountInclude: [
          "675kPX9MHTjS2zt1qfr1NYHuzeLXfQM9H24wFSUt1Mp8", // Raydium
          "CAMMCzo5YL8w4VFF8KVHrK22GGUsp5VTaW7grrKgrWqK", // Raydium CLMM
          "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4"   // Jupiter
        ],
        accountExclude: [],
        accountRequired: [],
        vote: false,
        failed: false
      }
    },
    commitment: CommitmentLevel.CONFIRMED,
    accounts: {}, slots: {}, transactionsStatus: {},
    blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
  };

  const config: LaserstreamConfig = {
    apiKey: 'YOUR_API_KEY',
    endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com', // Choose your closest region
  };

  await subscribe(config, subscriptionRequest, async (data) => {
    if (!data.transaction?.transaction) return;
    const tx = data.transaction.transaction;
    console.log(`\n🔄 DEX Transaction:`);
    console.log(`  Signature: ${bs58.encode(tx.signature)}`);
    console.log(`  Slot: ${data.transaction.slot}`);
    console.log(`  Status: ${tx.meta?.err ? 'Failed' : 'Success'}`);
    console.log(`  Fee: ${tx.meta?.fee || 0} lamports`);
    console.log(`  Compute Units: ${tx.meta?.computeUnitsConsumed || 0}`);

    // Token balance changes
    if (tx.meta?.preTokenBalances?.length > 0) {
      console.log(`  Token Balance Changes:`);
      tx.meta.preTokenBalances.forEach((preBalance: any, index: number) => {
        const postBalance = tx.meta.postTokenBalances[index];
        if (preBalance && postBalance) {
          const change = postBalance.uiTokenAmount.uiAmount - preBalance.uiTokenAmount.uiAmount;
          if (change !== 0) {
            console.log(`    ${preBalance.mint}: ${change > 0 ? '+' : ''}${change}`);
          }
        }
      });
    }
  }, async (error) => {
    console.error('Stream error:', error);
  });
}

monitorDEXTransactions().catch(console.error);

Exemplo 2: monitorar transações com falha

Acompanhe transações com falha para identificar problemas na aplicação:

async function monitorFailedTransactions() {
  const subscriptionRequest: SubscribeRequest = {
    transactions: {
      "failures": {
        accountInclude: ["YourProgramId"],
        accountExclude: [],
        accountRequired: [],
        vote: false,
        failed: true // Only failed transactions
      }
    },
    commitment: CommitmentLevel.CONFIRMED,
    accounts: {}, slots: {}, transactionsStatus: {},
    blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
  };

  const config: LaserstreamConfig = {
    apiKey: 'YOUR_API_KEY',
    endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
  };

  await subscribe(config, subscriptionRequest, async (data) => {
    if (!data.transaction?.transaction?.meta?.err) return;
    const tx = data.transaction.transaction;
    console.log(`\n❌ Failed Transaction:`);
    console.log(`  Signature: ${bs58.encode(tx.signature)}`);
    console.log(`  Slot: ${data.transaction.slot}`);
    console.log(`  Error: ${JSON.stringify(tx.meta.err)}`);
    console.log(`  Fee: ${tx.meta.fee} lamports`);
    console.log(`  Compute Units: ${tx.meta.computeUnitsConsumed || 0}`);
  }, async (error) => {
    console.error('Stream error:', error);
  });
}

Exemplo 3: monitorar transações de alto valor

Acompanhe transações com transferências significativas de SOL:

async function monitorHighValueTransactions() {
  const subscriptionRequest: SubscribeRequest = {
    transactions: {
      "system-program": {
        accountInclude: ["11111111111111111111111111111111"],
        accountExclude: [],
        accountRequired: [],
        vote: false,
        failed: false
      }
    },
    commitment: CommitmentLevel.CONFIRMED,
    accounts: {}, slots: {}, transactionsStatus: {},
    blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
  };

  const config: LaserstreamConfig = {
    apiKey: 'YOUR_API_KEY',
    endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
  };

  await subscribe(config, subscriptionRequest, async (data) => {
    if (!data.transaction?.transaction?.meta) return;
    const tx = data.transaction.transaction;
    const preBalances = tx.meta.preBalances || [];
    const postBalances = tx.meta.postBalances || [];

    let maxChange = 0;
    preBalances.forEach((preBalance: number, index: number) => {
      const postBalance = postBalances[index] || 0;
      maxChange = Math.max(maxChange, Math.abs(postBalance - preBalance));
    });

    const changeInSOL = maxChange / 1e9;
    if (changeInSOL > 10) {
      console.log(`\n💰 High-Value Transaction:`);
      console.log(`  Signature: ${bs58.encode(tx.signature)}`);
      console.log(`  Slot: ${data.transaction.slot}`);
      console.log(`  Max SOL Transfer: ${changeInSOL.toFixed(2)} SOL`);
      console.log(`  Fee: ${tx.meta.fee / 1e9} SOL`);
    }
  }, async (error) => {
    console.error('Stream error:', error);
  });
}

Exemplo 4: monitorar uma carteira (incluindo transferências de tokens)

Monitore tudo o que movimenta fundos de uma carteira — incluindo transferências recebidas de tokens SPL que envolvem suas ATAs — adicionando tokenAccounts a um filtro accountInclude simples:

import { subscribe, CommitmentLevel, LaserstreamConfig, SubscribeRequest } from 'helius-laserstream';
import bs58 from 'bs58';

async function watchWallet(wallet: string) {
  const subscriptionRequest: SubscribeRequest = {
    transactions: {
      "wallet-activity": {
        accountInclude: [wallet],
        accountExclude: [],
        accountRequired: [],
        vote: false,
        failed: false,
        // Also match txs touching token accounts this wallet owns.
        // "balanceChanged" = only when an owned token balance actually moved.
        tokenAccounts: "balanceChanged"
      }
    },
    commitment: CommitmentLevel.CONFIRMED,
    accounts: {}, slots: {}, transactionsStatus: {},
    blocks: {}, blocksMeta: {}, entry: {}, accountsDataSlice: [],
  };

  const config: LaserstreamConfig = {
    apiKey: 'YOUR_API_KEY',
    endpoint: 'https://laserstream-mainnet-ewr.helius-rpc.com',
  };

  await subscribe(config, subscriptionRequest, async (data) => {
    if (!data.transaction?.transaction) return;
    const tx = data.transaction.transaction;
    console.log(`\n👛 Wallet activity:`);
    console.log(`  Signature: ${bs58.encode(tx.signature)}`);
    console.log(`  Slot: ${data.transaction.slot}`);

    // Surface token balances this wallet owns that changed in the tx
    const owned = (tx.meta?.postTokenBalances || []).filter((b: any) => b.owner === wallet);
    owned.forEach((post: any) => {
      const pre = (tx.meta.preTokenBalances || []).find(
        (b: any) => b.accountIndex === post.accountIndex
      );
      const before = pre?.uiTokenAmount?.uiAmount || 0;
      const after = post.uiTokenAmount?.uiAmount || 0;
      if (after !== before) {
        console.log(`  ${post.mint}: ${after - before > 0 ? '+' : ''}${after - before}`);
      }
    });
  }, async (error) => {
    console.error('Stream error:', error);
  });
}

Estrutura de dados da transação

Transaction Message Structure

{
  signature: string;
  isVote: boolean;
  transaction: {
    message: {
      accountKeys: string[];        // All accounts involved
      instructions: Instruction[];  // Program instructions
      recentBlockhash: string;
    };
    signatures: string[];
  };
  meta: {
    err: any;                      // Error details if failed
    fee: number;                   // Transaction fee in lamports
    computeUnitsConsumed: number;
    preBalances: number[];
    postBalances: number[];
    preTokenBalances: TokenBalance[];
    postTokenBalances: TokenBalance[];
    logMessages: string[];
  };
}

Token Balance Changes

{
  accountIndex: number;
  mint: string;
  owner: string;
  uiTokenAmount: {
    amount: string;
    decimals: number;
    uiAmount: number;
    uiAmountString: string;
  };
}

Instruction Details

{
  programIdIndex: number; // Index in accountKeys array
  accounts: number[];
  data: string;           // Instruction data (base58)
}

Referência da lógica de filtragem

Include Logic (OR)

accountInclude: A transação deve envolver QUALQUER uma destas contas.["A", "B"] corresponde às transações que envolvem a conta A OU a conta B.

Required Logic (AND)

accountRequired: A transação deve envolver TODAS estas contas.["A", "B"] corresponde às transações que envolvem a conta A E a conta B.

Exclude Logic (NOT)

accountExclude: A transação NÃO deve envolver nenhuma destas contas.

Combined Logic

Filtro final: (accountInclude OR empty) AND (accountRequired AND all) AND NOT (accountExclude OR any).

Considerações de desempenho

Volume Management
Data Processing

Os streams de transações podem ter alto volume. Para acompanhar:

Comece com filtros de programa específicos (não assine “todas as transações”)
Use confirmed em vez de processed quando puder tolerar cerca de 1,5 s de latência adicional
Monitore sua capacidade de processamento com um contador
Considere executar consumidores paralelos por trás de uma fila

let count = 0;
const startTime = Date.now();
// inside your subscribe handler:
count++;
if (count % 100 === 0) {
  const elapsed = (Date.now() - startTime) / 1000;
  console.log(`Processing ${(count / elapsed).toFixed(1)} tx/sec`);
}

Extraia apenas o necessário para manter baixo o uso de memória:

import bs58 from 'bs58';

function extractTransactionData(tx: any) {
  return {
    signature: bs58.encode(tx.signature),
    slot: tx.slot,
    success: !tx.meta?.err,
    fee: tx.meta?.fee || 0,
    computeUnits: tx.meta?.computeUnitsConsumed || 0,
  };
}

Tratamento de erros

Too Many Transactions

Sintoma: Volume excessivo de transações.Soluções: Adicione filtros mais rigorosos (accountRequired, accountExclude); use um nível de confirmação mais alto; implemente amostragem ou limitação de taxa; processe de forma assíncrona.

Missing Transactions

Sintoma: As transações esperadas não aparecem.Soluções: Verifique se os endereços dos programas estão corretos; confirme se as transações realmente existem; experimente processed para obter atualizações mais rápidas; torne os filtros restritivos accountRequired/accountExclude menos rigorosos.

Parse Errors

Sintoma: Não é possível analisar os dados da transação.Soluções: Trate os campos ausentes de forma adequada; valide a estrutura antes do processamento; envolva a análise em try/catch; consulte Decodificação de dados de transação.

Próximas etapas

Slot & Block Monitoring

Acompanhe o consenso da rede e a produção de blocos.

Stream Pump AMM Data

Exemplo real: monitore transações de AMM da Pump.fun.

Decoding Transaction Data

Analise os payloads binários de transações e transforme-os em transações legíveis da Solana.

Yellowstone protocol reference

O mesmo fluxo de trabalho usando diretamente o protocolo gRPC Yellowstone.

Comece aqui

Dados em tempo real

Negociação de baixa latência

Dados históricos e de carteiras

Guias de métodos RPC

Preparação para produção

Como usar o Orb

Outros tutoriais

Monitoramento de Transações com LaserStream

Opções de Filtragem de Transação

Exemplos práticos

Exemplo 1: monitorar transações de DEX

Exemplo 2: monitorar transações com falha

Exemplo 3: monitorar transações de alto valor

Exemplo 4: monitorar uma carteira (incluindo transferências de tokens)

Estrutura de dados da transação

Referência da lógica de filtragem

Include Logic (OR)

Required Logic (AND)

Exclude Logic (NOT)

Combined Logic

Considerações de desempenho

Tratamento de erros

Próximas etapas

Slot & Block Monitoring

Stream Pump AMM Data

Decoding Transaction Data

Yellowstone protocol reference

​Opções de Filtragem de Transação

​Exemplos práticos

​Exemplo 1: monitorar transações de DEX

​Exemplo 2: monitorar transações com falha

​Exemplo 3: monitorar transações de alto valor

​Exemplo 4: monitorar uma carteira (incluindo transferências de tokens)

​Estrutura de dados da transação

​Referência da lógica de filtragem

Include Logic (OR)

Required Logic (AND)

Exclude Logic (NOT)

Combined Logic

​Considerações de desempenho

​Tratamento de erros

​Próximas etapas

Slot & Block Monitoring

Stream Pump AMM Data

Decoding Transaction Data

Yellowstone protocol reference

Opções de Filtragem de Transação

Exemplos práticos

Exemplo 1: monitorar transações de DEX

Exemplo 2: monitorar transações com falha

Exemplo 3: monitorar transações de alto valor

Exemplo 4: monitorar uma carteira (incluindo transferências de tokens)

Estrutura de dados da transação

Referência da lógica de filtragem

Considerações de desempenho

Tratamento de erros

Próximas etapas