Surveillance des transactions - Helius LaserStream

La surveillance des transactions vous permet de suivre l’exécution des transactions, le statut de réussite/échec, les interactions de programme et les changements de solde de jetons sur Solana en temps réel. Ce guide couvre les stratégies de filtrage et les implémentations pratiques à l’aide du SDK helius-laserstream.

Prérequis : Ce guide suppose que vous avez complété le Démarrage rapide LaserStream gRPC et que vous avez une clé API.

Options de filtrage des transactions

LaserStream utilise la même structure de filtre que Yellowstone gRPC, y compris le filtre tokenAccounts (expansion ATA). Les champs à définir dans transactions.<label> :

accountInclude — correspond si l’un de ces comptes apparaît (OU logique)
accountRequired — correspond uniquement si tous ces comptes apparaissent (ET logique)
accountExclude — exclut si l’un de ces comptes apparaît
vote / failed — indicateurs booléens pour les transactions de vote et les transactions ayant échoué
tokenAccounts — active l’extension des comptes de jetons associés (ATA) ("balanceChanged", "all" ou "none"), afin qu’un portefeuille accountInclude corresponde également aux transactions dans lesquelles il détient un solde de jetons SPL. Consultez Filtrage des comptes de jetons (ATA) et l’onglet Surveiller un portefeuille ci-dessous.
matchMints — indicateur facultatif qui compare également les listes de comptes aux mints figurant dans les soldes de jetons avant et après une transaction, afin qu’un mint dans accountInclude capture chaque transfert, swap, mint et burn de ce jeton. Consultez Filtrage par mint de jeton et l’onglet Surveiller un jeton ci-dessous.

Filtrage par programme
Spécifique au compte
Filtrage avancé
Surveillance d'un portefeuille
Watching a Token

Surveiller les transactions impliquant des programmes spécifiquesSuivre toutes les transactions qui touchent les programmes qui vous intéressent :

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

Idéal pour : Surveillance spécifique aux programmes, suivi de protocoles DeFi, interactions avec des contrats intelligents.

Surveiller les transactions affectant des comptes spécifiques

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

Cas d’utilisation : Surveillance de portefeuille, suivi de la frappe de tokens, tableaux de bord d’activité de compte.

Combiner plusieurs critères de filtrage

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

Logique de filtrage : accountInclude (OU) ET accountRequired (ET) ET PAS accountExclude.

Attraper les transferts de tokens entrants, pas seulement l’activité directeaccountInclude ne correspond qu’aux transactions où le portefeuille apparaît directement dans les clés de compte. Lorsqu’une personne envoie un token SPL au portefeuille, le transfert touche le compte de tokens associé (ATA) du portefeuille, pas la clé publique du portefeuille — donc une accountInclude: [wallet] simple ne le voit jamais.Réglez tokenAccounts pour étendre la correspondance aux transactions où le portefeuille possède un solde de jetons. Cela prend une chaîne :

"balanceChanged" — correspond lorsque le solde de tokens possédé a changé (ou que son compte de tokens a été fermé). Idéal pour “me dire quand l’argent a vraiment bougé” — plus restrictif, de moindre volume, recommandé par défaut.
"all" — correspond à toute transaction faisant référence à un solde de tokens possédé, même si inchangé. Volume considérablement plus élevé.
"none" — pas d’expansion (identique à l’omission du champ).

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

La correspondance repose sur le propriétaire : elle capture tous les comptes de jetons détenus par le portefeuille (y compris ceux qui ne sont pas canoniques), et pas seulement l’adresse ATA dérivée. Le SDK convertit la chaîne en enum TokenAccountExpansionControlFlag au niveau du protocole pour vous.

Capturez chaque transaction d’un mint, et pas seulement celles qui le mentionnentUn simple accountInclude: [mint] correspond uniquement aux transactions dont les clés de compte contiennent le mint, telles que MintTo, Burn ou TransferChecked. Un Transfer SPL classique ne référence jamais le mint. La plupart des transferts du jeton ne sont donc pas détectés.Définissez matchMints: true. Les listes de comptes sont alors également comparées aux mints dans les champs preTokenBalances et postTokenBalances de la transaction :

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

Combinez-le avec tokenAccounts pour surveiller un jeton pour un portefeuille : placez le portefeuille dans accountInclude avec tokenAccounts: "balanceChanged", et le mint dans accountRequired avec matchMints: true. Nécessite helius-laserstream 0.8.5+ (JS), 0.6.4+ (Rust) ou go/v0.3.0+ (Go). Consultez Filtrage par mint de jeton pour connaître la sémantique complète.

Exemples pratiques

Exemple 1 : surveiller les transactions DEX

Suivez les transactions impliquant des programmes DEX populaires :

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);

Exemple 2 : surveiller les transactions ayant échoué

Suivez les transactions ayant échoué afin de détecter les problèmes de l’application :

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);
  });
}

Exemple 3 : surveiller les transactions de grande valeur

Suivez les transactions comportant des transferts importants 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);
  });
}

Exemple 4 : surveiller un portefeuille (y compris les transferts de jetons)

Surveillez tous les mouvements de fonds d’un portefeuille, y compris les transferts entrants de jetons SPL qui impliquent ses ATA, en ajoutant tokenAccounts à un filtre accountInclude simple :

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);
  });
}

Structure des données de transaction

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)
}

Référence de la logique de filtrage

Include Logic (OR)

accountInclude : la transaction doit impliquer AU MOINS UN de ces comptes.["A", "B"] correspond aux transactions impliquant le compte A OU le compte B.

Required Logic (AND)

accountRequired : la transaction doit impliquer TOUS ces comptes.["A", "B"] correspond aux transactions impliquant le compte A ET le compte B.

Exclude Logic (NOT)

accountExclude : la transaction ne doit impliquer AUCUN de ces comptes.

Combined Logic

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

Considérations relatives aux performances

Volume Management
Data Processing

Les flux de transactions peuvent être volumineux. Pour suivre le rythme :

Commencez par des filtres de programme spécifiques (ne vous abonnez pas à « toutes les transactions »)
Utilisez confirmed plutôt que processed si vous pouvez tolérer environ 1,5 s de latence supplémentaire
Surveillez votre capacité de traitement à l’aide d’un compteur
Envisagez d’exécuter des consommateurs en parallèle derrière une file d’attente

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`);
}

Extrayez uniquement les données nécessaires pour limiter l’utilisation de la mémoire :

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,
  };
}

Gestion des erreurs

Too Many Transactions

Symptôme : volume de transactions trop élevé.Solutions : ajoutez des filtres plus stricts (accountRequired, accountExclude) ; utilisez un niveau d’engagement supérieur ; mettez en œuvre un échantillonnage ou une limitation du débit ; traitez les données de manière asynchrone.

Missing Transactions

Symptôme : les transactions attendues n’apparaissent pas.Solutions : vérifiez que les adresses des programmes sont correctes ; vérifiez que les transactions existent réellement ; essayez processed pour obtenir des mises à jour plus rapides ; assouplissez les filtres restrictifs accountRequired/accountExclude.

Parse Errors

Symptôme : impossible d’analyser les données de transaction.Solutions : gérez correctement les champs manquants ; validez la structure avant le traitement ; placez l’analyse dans un bloc try/catch ; consultez Décodage des données de transaction.

Étapes suivantes

Slot & Block Monitoring

Suivez le consensus du réseau et la production des blocs.

Stream Pump AMM Data

Exemple concret : surveillez les transactions AMM de Pump.fun.

Decoding Transaction Data

Analysez les charges utiles binaires des transactions pour obtenir des transactions Solana lisibles.

Yellowstone protocol reference

Le même workflow avec le protocole gRPC Yellowstone brut.

Commencer ici

Données en temps réel

Trading à faible latence

Données historiques et de portefeuilles

Guides des méthodes RPC

Préparation à la production

Utilisation d’Orb

Autres guides pratiques

Surveillance des transactions avec LaserStream

Options de filtrage des transactions

Exemples pratiques

Exemple 1 : surveiller les transactions DEX

Exemple 2 : surveiller les transactions ayant échoué

Exemple 3 : surveiller les transactions de grande valeur

Exemple 4 : surveiller un portefeuille (y compris les transferts de jetons)

Structure des données de transaction

Référence de la logique de filtrage

Include Logic (OR)

Required Logic (AND)

Exclude Logic (NOT)

Combined Logic

Considérations relatives aux performances

Gestion des erreurs

Étapes suivantes

Slot & Block Monitoring

Stream Pump AMM Data

Decoding Transaction Data

Yellowstone protocol reference

​Options de filtrage des transactions

​Exemples pratiques

​Exemple 1 : surveiller les transactions DEX

​Exemple 2 : surveiller les transactions ayant échoué

​Exemple 3 : surveiller les transactions de grande valeur

​Exemple 4 : surveiller un portefeuille (y compris les transferts de jetons)

​Structure des données de transaction

​Référence de la logique de filtrage

Include Logic (OR)

Required Logic (AND)

Exclude Logic (NOT)

Combined Logic

​Considérations relatives aux performances

​Gestion des erreurs

​Étapes suivantes

Slot & Block Monitoring

Stream Pump AMM Data

Decoding Transaction Data

Yellowstone protocol reference

Options de filtrage des transactions

Exemples pratiques

Exemple 1 : surveiller les transactions DEX

Exemple 2 : surveiller les transactions ayant échoué

Exemple 3 : surveiller les transactions de grande valeur

Exemple 4 : surveiller un portefeuille (y compris les transferts de jetons)

Structure des données de transaction

Référence de la logique de filtrage

Considérations relatives aux performances

Gestion des erreurs

Étapes suivantes