거래 모니터링 - Helius LaserStream

거래 모니터링을 통해 거래 실행, 성공/실패 상태, 프로그램 상호 작용 및 토큰 잔액 변경을 Solana 전반에 걸쳐 실시간으로 추적할 수 있습니다. 이 가이드에서는 helius-laserstream SDK를 사용한 필터링 전략 및 실제 구현을 다룹니다.

사전 조건: 이 가이드는 LaserStream gRPC 빠른 시작을 완료하고 API 키를 보유하고 있다고 가정합니다.

거래 필터링 옵션

LaserStream은 Yellowstone gRPC와 동일한 필터 모양을 사용하며 tokenAccounts (ATA 확장) 필터를 포함합니다. 설정할 필드는 다음과 같습니다:

accountInclude — 이 계정 중 하나라도 나타나면 일치합니다(논리 OR).
accountRequired — 이 계정이 모두 나타나는 경우에만 일치합니다(논리 AND).
accountExclude — 이 계정 중 하나라도 나타나면 제외합니다.
vote / failed — 투표 및 실패한 트랜잭션에 대한 불리언 플래그입니다.
tokenAccounts — 선택적으로 연결 토큰 계정(ATA) 확장을 활성화합니다("balanceChanged", "all" 또는 "none"). 그러면 accountInclude 지갑이 SPL 토큰 잔액을 소유한 트랜잭션과도 일치합니다. 토큰 계정(ATA) 필터링 및 아래의 지갑 감시 탭을 참조하세요.
matchMints — 계정 목록을 트랜잭션의 사전/사후 토큰 잔액에 있는 민트와도 대조하도록 선택적으로 활성화하는 플래그입니다. 따라서 accountInclude에 있는 민트는 해당 토큰의 모든 전송, 스왑, 민팅 및 소각을 포착합니다. 토큰 민트 필터링 및 아래의 토큰 감시 탭을 참조하세요.

프로그램 필터링
계정 특정
고급 필터링
지갑 모니터링
Watching a Token

특정 프로그램 관련 거래 모니터링관심 있는 프로그램과 관련된 모든 거래 추적:

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

최적의 용도: 프로그램 특정 모니터링, DeFi 프로토콜 추적, 스마트 계약 상호 작용.

특정 계정에 영향을 미치는 거래 모니터링

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

사용 사례: 지갑 모니터링, 토큰 발행 추적, 계정 활동 대시보드.

여러 필터 기준 결합

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

필터 논리: accountInclude (OR) AND accountRequired (AND) AND NOT accountExclude.

직접적인 활동뿐만 아니라 들어오는 토큰 전송까지 포착accountInclude는 지갑이 계정 키에 직접 나타나는 거래와만 일치합니다. 누군가 지갑에 SPL 토큰을 보낼 때 전송은 지갑의 **연결된 토큰 계정(ATA)**을 건드리고 지갑 공개키가 아닙니다. 그래서 단순 accountInclude: [wallet]는 이를 볼 수 없습니다.지갑이 토큰 잔고를 소유하는 거래까지 일치시킬 수 있도록 tokenAccounts를 설정하세요. 문자열을 받습니다:

"balanceChanged" — 소유한 토큰 잔고가 변했을 때 (또는 해당 토큰 계정이 폐쇄되었을 때) 일치. “실제로 돈이 움직였을 때 알려주세요”에 최적 — 좁고, 낮은 볼륨, 권장 기본값입니다.
"all" — 소유한 토큰 잔고와 관련된 모든 거래와 일치, 변경되지 않은 경우에도. 상당히 높은 볼륨.
"none" — 확장 없음 (필드를 생략한 것과 동일).

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

소유자 기준으로 일치시킵니다. 파생된 ATA 주소뿐만 아니라 지갑이 소유한 모든 토큰 계정(비표준 계정 포함)을 포착합니다. SDK가 문자열을 유선 수준의 TokenAccountExpansionControlFlag 열거형으로 변환해 줍니다.

민트가 명시된 트랜잭션뿐만 아니라 해당 민트와 관련된 모든 트랜잭션을 포착합니다일반 accountInclude: [mint]은 계정 키에 민트가 포함된 트랜잭션(예: MintTo, Burn 또는 TransferChecked)만 일치시킵니다. 기존 SPL Transfer은 민트를 참조하지 않으므로 해당 토큰 전송 대부분을 놓칩니다.matchMints: true을 설정하면 계정 목록을 트랜잭션의 preTokenBalances 및 postTokenBalances에 있는 민트와도 대조합니다.

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

tokenAccounts과 결합하여 지갑 하나에서 토큰 하나를 감시할 수 있습니다. tokenAccounts: "balanceChanged"과 함께 지갑을 accountInclude에 넣고, matchMints: true과 함께 민트를 accountRequired에 넣으세요. helius-laserstream 0.8.5 이상(JS), 0.6.4 이상(Rust) 또는 go/v0.3.0 이상(Go)이 필요합니다. 전체 동작 방식은 토큰 민트 필터링을 참조하세요.

실용적인 예시

예시 1: DEX 트랜잭션 모니터링

인기 DEX 프로그램과 관련된 트랜잭션을 추적합니다.

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

예시 2: 실패한 트랜잭션 모니터링

실패한 트랜잭션을 추적하여 애플리케이션 문제를 파악합니다.

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

예시 3: 고액 트랜잭션 모니터링

대규모 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);
  });
}

예시 4: 지갑 감시(토큰 전송 포함)

일반 accountInclude 필터에 tokenAccounts을 추가하여 지갑의 자금 이동과 관련된 모든 활동을 모니터링합니다. 여기에는 해당 지갑의 ATA와 관련된 수신 SPL 토큰 전송도 포함됩니다.

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

트랜잭션 데이터 구조

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

필터 논리 참조

Include Logic (OR)

accountInclude: 트랜잭션에 이 계정 중 하나라도 포함되어야 합니다.["A", "B"]은 계정 A 또는 계정 B가 포함된 트랜잭션과 일치합니다.

Required Logic (AND)

accountRequired: 트랜잭션에 이 계정이 모두 포함되어야 합니다.["A", "B"]은 계정 A와 계정 B가 모두 포함된 트랜잭션과 일치합니다.

Exclude Logic (NOT)

accountExclude: 트랜잭션에 이 계정 중 어느 것도 포함되어서는 안 됩니다.

Combined Logic

최종 필터: (accountInclude OR empty) AND (accountRequired AND all) AND NOT (accountExclude OR any).

성능 고려 사항

Volume Management
Data Processing

트랜잭션 스트림의 데이터 양이 많을 수 있습니다. 이를 원활하게 처리하려면 다음을 따르세요.

구체적인 프로그램 필터부터 사용하세요(“모든 트랜잭션”을 구독하지 마세요).
약 1.5초의 추가 지연 시간을 허용할 수 있다면 processed 대신 confirmed을 사용하세요.
카운터로 처리 용량을 모니터링하세요.
큐 뒤에서 병렬 컨슈머를 실행하는 방안을 고려하세요.

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

메모리 사용량을 낮게 유지하려면 필요한 데이터만 추출하세요.

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

오류 처리

Too Many Transactions

증상: 트랜잭션 양이 너무 많습니다.해결 방법: 더 엄격한 필터(accountRequired, accountExclude)를 추가하고, 더 높은 확정 수준을 사용하세요. 샘플링 또는 속도 제한을 구현하고 비동기식으로 처리하세요.

Missing Transactions

증상: 예상한 트랜잭션이 나타나지 않습니다.해결 방법: 프로그램 주소가 올바른지 확인하고 트랜잭션이 실제로 존재하는지 확인하세요. 더 빠른 업데이트를 위해 processed을 사용해 보고, 제한적인 accountRequired/accountExclude 필터의 조건을 완화하세요.

Parse Errors

증상: 트랜잭션 데이터를 파싱할 수 없습니다.해결 방법: 누락된 필드를 적절히 처리하고, 처리 전에 구조를 검증하세요. 파싱을 try/catch로 감싸고 트랜잭션 데이터 디코딩을 참조하세요.

다음 단계

Slot & Block Monitoring

네트워크 합의와 블록 생성을 추적합니다.

Stream Pump AMM Data

실제 사례: Pump.fun AMM 트랜잭션을 모니터링합니다.

Decoding Transaction Data

바이너리 트랜잭션 페이로드를 읽을 수 있는 Solana 트랜잭션으로 파싱합니다.

Yellowstone protocol reference

원시 Yellowstone gRPC 프로토콜에서 동일한 워크플로를 사용합니다.

여기서 시작하기

실시간 데이터

저지연 트레이딩

과거 데이터 및 지갑 데이터

RPC 메서드 가이드

프로덕션 준비

Orb 사용하기

기타 사용 가이드

LaserStream을 통한 거래 모니터링

거래 필터링 옵션

실용적인 예시

예시 1: DEX 트랜잭션 모니터링

예시 2: 실패한 트랜잭션 모니터링

예시 3: 고액 트랜잭션 모니터링

예시 4: 지갑 감시(토큰 전송 포함)

트랜잭션 데이터 구조

필터 논리 참조

Include Logic (OR)

Required Logic (AND)

Exclude Logic (NOT)

Combined Logic

성능 고려 사항

오류 처리

다음 단계

Slot & Block Monitoring

Stream Pump AMM Data

Decoding Transaction Data

Yellowstone protocol reference

​거래 필터링 옵션

​실용적인 예시

​예시 1: DEX 트랜잭션 모니터링

​예시 2: 실패한 트랜잭션 모니터링

​예시 3: 고액 트랜잭션 모니터링

​예시 4: 지갑 감시(토큰 전송 포함)

​트랜잭션 데이터 구조

​필터 논리 참조

Include Logic (OR)

Required Logic (AND)

Exclude Logic (NOT)

Combined Logic

​성능 고려 사항

​오류 처리

​다음 단계

Slot & Block Monitoring

Stream Pump AMM Data

Decoding Transaction Data

Yellowstone protocol reference

거래 필터링 옵션

실용적인 예시

예시 1: DEX 트랜잭션 모니터링

예시 2: 실패한 트랜잭션 모니터링

예시 3: 고액 트랜잭션 모니터링

예시 4: 지갑 감시(토큰 전송 포함)

트랜잭션 데이터 구조

필터 논리 참조

성능 고려 사항

오류 처리

다음 단계