Parsed Events API와 Parsed Streams를 소개합니다

Solana 트랜잭션을 읽기 어려운 이유는 무엇인가요?

표준 RPC 노드에 트랜잭션에서 어떤 일이 발생했는지 쿼리하면 이름이 없는 계정 주소 목록과 불투명한 base58 blob 형태의 명령어 데이터가 반환됩니다.

이를 "이 지갑이 Jupiter에서 1,500 SOL을 PUMP로 스왑했습니다"라는 정보로 변환하려면 기존에는 다음 작업이 필요했습니다.

1. 트랜잭션을 가져와 상호작용한 모든 프로그램 식별
2. 각 프로그램의 IDL(공개된 인터페이스)이 있다면 검색
3. 해당 IDL을 기준으로 명령어 데이터(일반적으로 Borsh) 디코딩
4. 위치 기반 계정을 역할에 매핑: 세 번째 주소가 권한 계정인가요, 아니면 대상 계정인가요? 프로그램의 인터페이스만 이를 알 수 있습니다
5. 스왑 내부의 토큰 이동처럼 실제 활동 대부분이 일어나는 내부 명령어(CPI)를 재귀적으로 분석
6. 필요한 모든 프로그램에 대해 이 작업을 반복하고, 프로그램의 새 버전이 출시될 때마다 디코더 업데이트

질문 하나에 답하기도 전에 몇 주의 엔지니어링 작업이 필요합니다. 이는 Solana를 처음 시작할 때 마주하는 가장 가파른 학습 곡선 중 하나입니다. 체인의 데이터는 공개되어 있지만 쉽게 읽을 수 없습니다.

이제 직접 처리하지 않아도 되도록 서버 측 디코딩 레이어를 구축했습니다.

Parsed Events 응답에는 무엇이 포함되나요?

모든 트랜잭션은 Helius IDL 카탈로그를 통해 디코딩되어 반환됩니다. 

다음은 실제 Jupiter 스왑에서 핵심 부분만 추린 예시입니다.

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

계정 목록의 세 번째 주소가 무엇을 의미하는지 추측하는 대신 "name": "user_transfer_authority"을 읽으면 됩니다. 

인수도 디코딩된 상태로 제공됩니다. 원시 바이트 대신 "slippage_bps": 2200을 확인할 수 있습니다.

트랜잭션 수준의 summary은 사용자에게 그대로 표시할 수도 있습니다.

각 결과에는 수수료와 수수료 지불자, 기본 SOL 전송, SPL 및 Token-2022 전송, 메타데이터가 있는 경우 디코딩된 커스텀 프로그램 오류도 포함됩니다. 

카탈로그에 없는 프로그램의 명령어는 원시 데이터와 원시 계정으로 대체되므로 항상 활용할 수 있는 정보가 제공됩니다.

Parsed Streams: 디코딩된 트랜잭션을 바로 전송합니다

Parsed Streams는 확정된 모든 트랜잭션을 감시하고 디코딩한 뒤, 서버 측에서 명령어 수준의 필터와 일치하는 트랜잭션을 전송하는 WebSocket 서비스입니다.

대규모 원시 데이터 스트림을 직접 처리하거나 디코더를 유지 관리할 필요가 없습니다.

필터는 다음 다섯 필드로 구성됩니다.

1. programs
2. instructionNames
3. accounts (포함 여부 또는 지정된 역할 기준)
4. includeCpi
5. includeFailed

예를 들어 "이 지갑과 상호작용하는 모든 Jupiter 경로 명령어"는 다음과 같습니다.

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

모든 알림에는 디코딩된 전체 트랜잭션이 포함되며, matchedIndexes은 필터와 일치한 명령어를 가리킵니다.

Solana 프로그램의 명령어 이름은 어떻게 확인하나요?

명령어 이름을 추측하면 필터가 아무 항목과도 일치하지 않은 채 조용히 실패하기 쉽습니다. Solana 프로그램의 명령어 이름을 확인하려면 프로그램 주소로 describeProgram을 호출하세요. 매칭 시 비교되는 명령어, 이벤트, 계정 역할이 반환됩니다.

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

프로그램을 조회하고 필터에 이름을 추가한 다음 구독하세요. 

Jupiter 스왑 추적 가이드에서 전체 워크플로를 단계별로 확인할 수 있습니다.

Parsed Events API: 요청 시 트랜잭션 디코딩

실시간 데이터 대신 조회가 필요하다면 Parsed Events API가 요청 시 동일한 IDL 카탈로그 기반 디코딩을 적용합니다.

Parse Transactions는 서명을 받아 디코딩된 결과를 반환합니다.

Parsed Transaction History는 주소의 디코딩된 전체 기록을 페이지 단위로 제공하며 최신 트랜잭션부터 반환합니다.

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

두 메서드 모두 GraphQL로도 사용할 수 있어 앱에 필요한 파싱 필드만 선택할 수 있습니다.

Parsed Events와 Enhanced Transaction API 비교

Parsed Events는 Enhanced Transactions API의 후속 제품입니다. 

Enhanced Transactions가 트랜잭션을 고정된 이벤트 유형 목록으로 분류했다면, Parsed Events는 IDL 카탈로그를 통해 각 명령어를 디코딩합니다. 인식되지 않는 프로그램에는 UNKNOWN 대신 원시 데이터를 반환합니다.

현재 Enhanced Transactions API를 사용하고 있다면 마이그레이션 가이드에서 모든 엔드포인트, 매개변수, 응답 필드의 매핑을 확인할 수 있습니다. 에이전트가 마이그레이션을 대신 완료하도록 실행할 수 있는 프롬프트도 포함되어 있습니다.

어떤 파싱 도구를 사용해야 하나요?

두 신제품은 하나의 디코딩 엔진을 공유하므로 스트림과 REST 호출 중 어떤 방식으로 수신하더라도 트랜잭션 형식이 같습니다. 특히 Parsed Events로 과거 데이터를 사용해 프로토타입을 만든 뒤 파싱 코드를 변경하지 않고 Parsed Streams의 실시간 데이터로 전환할 수 있습니다.

시작하기

Parsed Streams와 Parsed Events API는 오픈 베타이며 모든 유료 플랜에서 사용할 수 있습니다. Helius Dashboard에서 API 키를 발급받으세요.

연결하려면 다음 엔드포인트를 사용하세요.

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

가이드

Parsed Streams 빠른 시작을 따라 몇 분 안에 첫 번째 디코딩 알림을 받아보세요. Parsed Events 빠른 시작에서는 첫 번째 서명을 파싱하는 방법을 확인할 수 있습니다. 

궁금한 점이 있다면 Telegram 또는 Discord로 문의해 주세요.