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 alguma dessas contas aparecer (ou lógico)
accountRequired — corresponde apenas se todas essas contas aparecerem (e lógico)
accountExclude — descarta se alguma dessas contas aparecer
vote / failed — flags booleanos para transações de voto e falhas
tokenAccounts — expansão opcional da conta de token associada (ATA) ("balanceChanged", "all", ou "none"), então uma carteira accountInclude também corresponde a transações onde possui um saldo de token SPL. Veja Filtragem de Conta de Token (ATA) e a aba Assistindo uma Carteira abaixo.

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

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 — captura qualquer conta de token que a carteira possua (incluindo as não canônicas), não apenas o endereço ATA derivado. O SDK converte a string para o enum de nível de wire TokenAccountExpansionControlFlag para você.

Exemplos Práticos

Exemplo 1: Monitorar Transações de DEX

Acompanhar transações que tocam programas 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

Acompanhar transações com falha para identificar problemas de 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

Acompanhar 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: Assistir uma Carteira (incl. transferências de tokens)

Monitore tudo que movimenta dinheiro para uma carteira — incluindo transferências recebidas de tokens SPL que tocam suas ATAs — adicionando tokenAccounts a um filtro accountInclude comum:

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 de Transação

Estrutura da Mensagem de Transação

{
  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[];
  };
}

Mudanças de Saldo de Token

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

Detalhes da Instrução

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

Referência de Lógica de Filtragem

Lógica de Inclusão (OU)

accountInclude: A transação deve envolver QUALQUER uma dessas contas.["A", "B"] corresponde a transações envolvendo a conta A OU a conta B.

Lógica Obrigatória (E)

accountRequired: A transação deve envolver TODAS essas contas.["A", "B"] corresponde a transações envolvendo a conta A E a conta B.

Lógica de Exclusão (NÃO)

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

Lógica Combinada

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

Considerações de Desempenho

Gestão de Volume
Processamento de Dados

Streams de transações podem ser de alto volume. Para manter o ritmo:

Comece com filtros específicos de programa (não assine “todas as transações”)
Use confirmed ao invés de processed quando puder tolerar ~1.5s de latência extra
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 que você precisa para manter a memória baixa:

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

Muitas Transações

Sintoma: Volume de transações avassalador.Soluções: Adicione filtros mais rigorosos (accountRequired, accountExclude); use comprometimento mais alto; implemente amostragem ou limitação de taxa; processe assincronamente.

Transações Ausentes

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

Erros de Análise

Sintoma: Não consegue analisar dados de transação.Soluções: Lide com campos ausentes graciosamente; valide a estrutura antes de processar; envolva a análise em try/catch; veja Decodificando Dados de Transação.

Próximos Passos

Monitoramento de Slot e Bloco

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

Stream Pump AMM Data

Exemplo do mundo real: monitore transações Pump.fun AMM.

Decodificação de Dados de Transação

Analise as cargas de transação binárias em transações legíveis de Solana.

Referência do protocolo Yellowstone

O mesmo fluxo de trabalho contra o protocolo gRPC Yellowstone bruto.

Primeiros Passos

Transmissão de Dados e Audição de Eventos

APIs de Dados & RPCs

Negociação

Enviando Transações

Carteira como Serviço

Privacidade

Recursos

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: Assistir uma Carteira (incl. transferências de tokens)

Estrutura de Dados de Transação

Referência de Lógica de Filtragem

Lógica de Inclusão (OU)

Lógica Obrigatória (E)

Lógica de Exclusão (NÃO)

Lógica Combinada

Considerações de Desempenho

Tratamento de Erros

Próximos Passos

Monitoramento de Slot e Bloco

Stream Pump AMM Data

Decodificação de Dados de Transação

Referência do protocolo Yellowstone

​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: Assistir uma Carteira (incl. transferências de tokens)

​Estrutura de Dados de Transação

​Referência de Lógica de Filtragem

Lógica de Inclusão (OU)

Lógica Obrigatória (E)

Lógica de Exclusão (NÃO)

Lógica Combinada

​Considerações de Desempenho

​Tratamento de Erros

​Próximos Passos

Monitoramento de Slot e Bloco

Stream Pump AMM Data

Decodificação de Dados de Transação

Referência do protocolo Yellowstone

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: Assistir uma Carteira (incl. transferências de tokens)

Estrutura de Dados de Transação

Referência de Lógica de Filtragem

Considerações de Desempenho

Tratamento de Erros

Próximos Passos