Transaction Events — Transactions, Logs, Calls

Subscribe

{"subscribe": ["TxnHeaderStart", "TxnLog", "TxnEvmOutput"]}

Available types: TxnHeaderStart, TxnEvmOutput, TxnLog, TxnCallFrame, NativeTransfer, TxnEnd, TxnReject.

Message Format

All events are delivered inside an Events batch:

{
  "seq": 50,
  "Events": [
    {
      "event_name": "TxnLog",
      "block_number": 56147820,
      "txn_idx": 5,
      "txn_hash": "0xabc...",
      "commit_stage": "Proposed",
      "payload": {
        "type": "TxnLog",
        "txn_index": 5,
        "log_index": 0,
        "address": "0x0000000000000000000000000000000000001000",
        "topics": "0xe4d4df1e...",
        "data": "0x..."
      },
      "seqno": 9876543250,
      "timestamp_ns": 1708345678100000000
    }
  ]
}

Event Types

TxnHeaderStart

Transaction execution begins. Full transaction header.

Payload Field	Type	Description
txn_index	number	Index within block
txn_hash	string	Transaction hash
sender	string	Sender address
txn_type	number	Type (0=legacy, 2=EIP-1559)
chain_id	string	Chain ID (hex U256)
nonce	number	Nonce
gas_limit	number	Gas limit
max_fee_per_gas	string	Max fee (hex U256)
max_priority_fee_per_gas	string	Max priority fee (hex U256)
value	string	Transfer value (hex U256)
data	string	Calldata (hex bytes)
to	string	Recipient address
is_contract_creation	boolean	Contract creation flag
r, s	string	ECDSA signature
y_parity	boolean	Signature y-parity
access_list_count	number	EIP-2930 entries
auth_list_count	number	EIP-7702 entries

TxnEvmOutput

EVM execution result.

Payload Field	Type	Description
txn_index	number	Transaction index
log_count	number	Number of logs
status	boolean	true = success, false = revert
gas_used	number	Gas consumed

TxnLog

EVM log (Solidity emit). Real-time equivalent of eth_getLogs.

Payload Field	Type	Description
txn_index	number	Transaction index
log_index	number	Log index within transaction
address	string	Emitting contract address
topics	string	Concatenated 32-byte topics (hex)
data	string	Log data (hex bytes)

topics is a concatenated string, not an array. Each topic = 64 hex characters (32 bytes). topic[0] = first 64 characters after 0x.

TxnCallFrame

Internal call (CALL, DELEGATECALL, STATICCALL, CREATE).

Payload Field	Type	Description
txn_index	number	Transaction index
depth	number	Call stack depth
caller	string	Caller address
call_target	string	Target address
value	string	Value transferred (hex U256)
input	string	Call input data (hex)
output	string	Call return data (hex)

NativeTransfer

Virtual event, a subscription filter alias for TxnCallFrame where value > 0. Useful for tracking ETH transfers.

{"subscribe": ["NativeTransfer"]}

Delivers TxnCallFrame events with non-zero value.

TxnEnd

Transaction processing complete. No payload fields.

TxnReject

Transaction rejected before execution.

Payload Field	Type	Description
txn_index	number	Index
reason	number	Reason code

Blocked Events (available with --unrestricted)

• TxnHeaderEnd: end of header processing
• TxnAccessListEntry: EIP-2930 access list entry
• TxnAuthListEntry: EIP-7702 authorization entry
• TxnPerfEvmEnter / TxnPerfEvmExit: EVM profiling markers

Filtering

By Contract Address (TxnLog)

{
  "subscribe": {
    "events": ["TxnLog"],
    "filters": [{
      "event_name": "TxnLog",
      "field_filters": [
        {"field": "address", "filter": {"values": ["0xTOKEN_ADDRESS"]}}
      ]
    }]
  }
}

By Topics (Event Signature)

{
  "subscribe": {
    "events": ["TxnLog"],
    "filters": [{
      "event_name": "TxnLog",
      "field_filters": [
        {"field": "topics", "filter": {"values": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]}}
      ]
    }]
  }
}

0xddf252ad... = keccak256("Transfer(address,address,uint256)").

By Sender (TxnHeaderStart)

{
  "subscribe": {
    "events": ["TxnHeaderStart"],
    "filters": [{
      "event_name": "TxnHeaderStart",
      "field_filters": [
        {"field": "sender", "filter": {"values": ["0xYOUR_WALLET"]}}
      ]
    }],
    "correlate": true
  }
}

With correlate: true, the server auto-delivers all events for matching transactions (TxnLog, TxnCallFrame, TxnEvmOutput, TxnEnd).

By Function Selector (TxnHeaderStart)

{
  "subscribe": {
    "events": ["TxnHeaderStart"],
    "filters": [{
      "event_name": "TxnHeaderStart",
      "field_filters": [
        {"field": "to", "filter": {"values": ["0x0000000000000000000000000000000000001000"]}},
        {"field": "function_selector", "filter": {"values": ["0x84994fec"]}}
      ]
    }],
    "correlate": true
  }
}

0x84994fec = delegate(uint64).

Event Ordering Within a Transaction

TxnHeaderStart
  TxnAccessListEntry*
  TxnAuthListEntry*
TxnHeaderEnd
  TxnPerfEvmEnter
    AccountAccess* / StorageAccess*
    TxnLog*
    TxnCallFrame*
  TxnPerfEvmExit
TxnEvmOutput
TxnEnd

Optional events (*) may appear 0 or more times.

Transaction Correlation

With "correlate": true, if TxnHeaderStart passes the filter, the server automatically delivers all subsequent events for that transaction:

Event	Action
BlockStart / BlockEnd	Clear correlation set
TxnHeaderStart (match)	Add txn_idx to set
Any event with txn_idx in set	Auto-deliver
TxnEnd	Deliver, remove from set

Frequency

Depends on network load. At 2000 TPS with a TxnLog subscription, expect thousands of events per second. Use filters to reduce the stream.