Transaction Messages

Overview

Transaction messages contain information about Solana transactions that match your subscription filters. Yellowstone provides both full transaction updates and early transaction status updates.

SubscribeUpdateTransaction

Wrapper message for full transaction updates in the subscription stream.

message SubscribeUpdateTransaction {
  SubscribeUpdateTransactionInfo transaction = 1;
  uint64 slot = 2;
}

Fields

transaction

SubscribeUpdateTransactionInfo

required

The detailed transaction information including signature, transaction data, and execution metadata.

slot

uint64

required

The slot number when this transaction was executed.

Example

{
  "transaction": {
    "signature": "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
    "is_vote": false,
    "transaction": {
      "signatures": ["..."],
      "message": { }
    },
    "meta": {
      "fee": 5000,
      "pre_balances": [1000000000, 2000000000],
      "post_balances": [999995000, 2000000000]
    },
    "index": 42
  },
  "slot": 250000000
}

SubscribeUpdateTransactionInfo

Detailed transaction information including the full transaction and execution metadata.

message SubscribeUpdateTransactionInfo {
  bytes signature = 1;
  bool is_vote = 2;
  solana.storage.ConfirmedBlock.Transaction transaction = 3;
  solana.storage.ConfirmedBlock.TransactionStatusMeta meta = 4;
  uint64 index = 5;
}

Fields

signature

bytes

required

The transaction signature (64 bytes). This is the unique identifier for the transaction. Convert to base58 for the familiar signature format.

is_vote

bool

required

Whether this is a vote transaction. Vote transactions are consensus-related and typically filtered out for application-level monitoring.

transaction

Transaction

required

The transaction data including signatures, message, and instructions.

Show Transaction structure

signatures

repeated bytes

Array of signatures. The first signature is the transaction ID.

message

Message

The transaction message containing account keys, instructions, and metadata.

TransactionStatusMeta

Execution metadata and results for a transaction.

message TransactionStatusMeta {
  TransactionError err = 1;
  uint64 fee = 2;
  repeated uint64 pre_balances = 3;
  repeated uint64 post_balances = 4;
  repeated InnerInstructions inner_instructions = 5;
  bool inner_instructions_none = 10;
  repeated string log_messages = 6;
  bool log_messages_none = 11;
  repeated TokenBalance pre_token_balances = 7;
  repeated TokenBalance post_token_balances = 8;
  repeated Reward rewards = 9;
  repeated bytes loaded_writable_addresses = 12;
  repeated bytes loaded_readonly_addresses = 13;
  ReturnData return_data = 14;
  bool return_data_none = 15;
  optional uint64 compute_units_consumed = 16;
  optional uint64 cost_units = 17;
}

Fields

err

TransactionError

Transaction error information if the transaction failed. If null/empty, the transaction succeeded.

fee

uint64

required

Transaction fee paid in lamports.

pre_balances

repeated uint64

required

Account balances (in lamports) before the transaction executed. Indexed by account position in the transaction.

post_balances

repeated uint64

required

Account balances (in lamports) after the transaction executed. Compare with pre_balances to see balance changes.

inner_instructions

repeated InnerInstructions

Array of inner instructions executed by Cross-Program Invocations (CPIs). Each entry contains instructions invoked by a top-level instruction.

inner_instructions_none

bool

If true, inner_instructions is explicitly empty (no CPIs occurred). Helps distinguish between “no inner instructions” and “inner instructions not tracked”.

log_messages

repeated string

Array of log messages emitted during transaction execution. Useful for debugging and understanding program execution flow.

log_messages_none

bool

If true, log_messages is explicitly empty.

pre_token_balances

repeated TokenBalance

SPL token balances before the transaction. Contains mint, owner, and amount information for each token account touched by the transaction.

post_token_balances

repeated TokenBalance

SPL token balances after the transaction.

rewards

repeated Reward

Rewards earned in this transaction (e.g., staking or voting rewards).

loaded_writable_addresses

repeated bytes

Addresses loaded from address lookup tables as writable accounts. Available for versioned transactions using address lookup tables.

loaded_readonly_addresses

repeated bytes

Addresses loaded from address lookup tables as readonly accounts.

return_data

ReturnData

Data returned by the transaction via the return_data instruction.

Show ReturnData structure

program_id

bytes

The program that returned the data.

data

bytes

The returned data.

return_data_none

bool

If true, return_data is explicitly empty.

compute_units_consumed

uint64

Total compute units consumed by the transaction. Available since Solana v1.10.35 / v1.11.6. Useful for understanding transaction complexity and cost.

cost_units

uint64

Total transaction cost in cost units.

Example: Successful Transaction Meta

{
  "fee": 5000,
  "pre_balances": [10000000000, 5000000000, 1000000000],
  "post_balances": [9999995000, 5000000000, 1000000000],
  "log_messages": [
    "Program 11111111111111111111111111111111 invoke [1]",
    "Program 11111111111111111111111111111111 success"
  ],
  "compute_units_consumed": 150,
  "cost_units": 150
}

Example: Failed Transaction Meta

{
  "err": {
    "err": "0x01"
  },
  "fee": 5000,
  "pre_balances": [10000000000],
  "post_balances": [9999995000],
  "log_messages": [
    "Program Failed: InsufficientFunds"
  ],
  "compute_units_consumed": 100
}

SubscribeUpdateTransactionStatus

Early transaction status update sent immediately when a transaction is received, before full execution details are available.

message SubscribeUpdateTransactionStatus {
  uint64 slot = 1;
  bytes signature = 2;
  bool is_vote = 3;
  uint64 index = 4;
  solana.storage.ConfirmedBlock.TransactionError err = 5;
}

Fields

slot

uint64

required

The slot number when this transaction status was received.

signature

bytes

required

The transaction signature (64 bytes).

is_vote

bool

required

Whether this is a vote transaction.

index

uint64

required

The position of this transaction within the block.

err

TransactionError

Transaction error if the transaction failed. If null/empty, the transaction succeeded.

Use Case

Transaction status updates are useful when you need the fastest possible notification that a transaction was included in a block, even before full metadata like logs and balance changes are available.

Example

{
  "slot": 250000000,
  "signature": "5j7s6NiJS3JAkvgkoc18WVAsiSaci2pxB2A6ueCJP4tprA2TFg9wSyTLeYouxPBJEMzJinENTkpA52YStRW5Dia7",
  "is_vote": false,
  "index": 42
}

Transaction Message Structure

Message

The core transaction message containing instructions and account references.

message Message {
  MessageHeader header = 1;
  repeated bytes account_keys = 2;
  bytes recent_blockhash = 3;
  repeated CompiledInstruction instructions = 4;
  bool versioned = 5;
  repeated MessageAddressTableLookup address_table_lookups = 6;
}

header

MessageHeader

required

Message header containing signature and account permissions metadata.

account_keys

repeated bytes

required

Array of account public keys (32 bytes each) referenced by this transaction. Instructions reference accounts by index into this array.

recent_blockhash

bytes

required

Recent blockhash used for transaction expiration.

instructions

repeated CompiledInstruction

required

Array of instructions to execute.

versioned

bool

required

Whether this is a versioned transaction (supports address lookup tables).

address_table_lookups

repeated MessageAddressTableLookup

Address lookup table references for versioned transactions. Allows transactions to reference more accounts than would fit in the message.

CompiledInstruction

message CompiledInstruction {
  uint32 program_id_index = 1;
  bytes accounts = 2;
  bytes data = 3;
}

program_id_index

uint32

required

Index into the transaction’s account keys array identifying the program to execute.

accounts

bytes

required

Compact array of indices into the transaction’s account keys array. Each byte is an index identifying an account used by this instruction.

data

bytes

required

Instruction data passed to the program.

Processing Transactions

Checking Transaction Success

if (update.transaction) {
  const tx = update.transaction.transaction;
  const isSuccess = !tx.meta.err || !tx.meta.err.err;
  
  if (isSuccess) {
    console.log('Transaction succeeded:', base58.encode(tx.signature));
  } else {
    console.log('Transaction failed:', base58.encode(tx.signature));
  }
}

Analyzing Balance Changes

const meta = tx.meta;
for (let i = 0; i < meta.pre_balances.length; i++) {
  const change = meta.post_balances[i] - meta.pre_balances[i];
  if (change !== 0) {
    console.log(`Account ${i} balance changed by ${change} lamports`);
  }
}

Processing Logs

if (tx.meta.log_messages && !tx.meta.log_messages_none) {
  console.log('Transaction logs:');
  tx.meta.log_messages.forEach(log => console.log(log));
}

Filter Messages - Transaction filter configuration
SubscribeRequest - How to subscribe to transaction updates
SubscribeUpdate - Parent message containing transaction updates

gRPC Methods

Message Types

Configuration

Overview

SubscribeUpdateTransaction

Fields

Example

SubscribeUpdateTransactionInfo

Fields

TransactionStatusMeta

Fields

Example: Successful Transaction Meta

Example: Failed Transaction Meta

SubscribeUpdateTransactionStatus

Fields

Use Case

Example

Transaction Message Structure

Message

CompiledInstruction

Processing Transactions

Checking Transaction Success

Analyzing Balance Changes

Processing Logs

Build docs developers (and LLMs) love

gRPC Methods

Message Types

Configuration

​Overview

​SubscribeUpdateTransaction

​Fields

​Example

​SubscribeUpdateTransactionInfo

​Fields

​TransactionStatusMeta

​Fields

​Example: Successful Transaction Meta

​Example: Failed Transaction Meta

​SubscribeUpdateTransactionStatus

​Fields

​Use Case

​Example

​Transaction Message Structure

​Message

​CompiledInstruction

​Processing Transactions

​Checking Transaction Success

​Analyzing Balance Changes

​Processing Logs

​Related

Build docs developers (and LLMs) love

Overview

SubscribeUpdateTransaction

Fields

Example

SubscribeUpdateTransactionInfo

Fields

TransactionStatusMeta

Fields

Example: Successful Transaction Meta

Example: Failed Transaction Meta

SubscribeUpdateTransactionStatus

Fields

Use Case

Example

Transaction Message Structure

Message

CompiledInstruction

Processing Transactions

Checking Transaction Success

Analyzing Balance Changes

Processing Logs

Related