Skip to content

eth_subscribe.md

Latest commit

 

History

History
158 lines (121 loc) · 5.18 KB

eth_subscribe.md

File metadata and controls

158 lines (121 loc) · 5.18 KB
description eth_subscribe — WebSocket subscriptions for real-time logs, state changes, mini-blocks, and block headers on MegaETH.

eth_subscribe

Creates a WebSocket subscription that streams data as mini-blocks are produced. This is the lowest-latency way to receive transaction results — logs, state changes, and block contents arrive within ~10ms of execution.

Call eth_unsubscribe with the subscription ID when a subscription is no longer needed.

{% hint style="info" %} WebSocket connections require periodic client activity to remain open. Send eth_chainId at least once every 30 seconds to keep the connection alive. Idle connections may be closed by the server. {% endhint %}

Subscription Types

logs

Streams event logs as transactions are packaged into mini-blocks. Set both fromBlock and toBlock to "pending" for real-time delivery.

Parameters:

Field Type Required Notes
fromBlock BlockTag No Set to "pending" for real-time logs
toBlock BlockTag No Set to "pending" for real-time logs
address Data | Data[] No Contract address(es) to filter
topics Data[] No Position-sensitive topic filter

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "topics": [
        "0xd78a0cb8bb633d06981248b816e7bd33c2a35a6089241d099fa519e361cab902"
      ],
      "fromBlock": "pending",
      "toBlock": "pending"
    }
  ]
}

Each notification uses the same schema as eth_getLogs.

stateChanges

Streams account state changes as transactions are packaged into mini-blocks. Takes a list of account addresses to monitor.

Parameters:

Position Type Required Notes
0 Data[] Yes List of account addresses to monitor

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["stateChanges", ["0x2ef038991d64c72646d4f06ba78d93f4f1654e3f"]]
}

Notification schema:

Field Type Notes
address Data (20 bytes) Account address
nonce Number Latest nonce
balance Quantity Latest balance
storage Object Changed storage slots (slot → value)

Example notification:

{
  "address": "0x2ef038991d64c72646d4f06ba78d93f4f1654e3f",
  "nonce": 1,
  "balance": "0x16345785d8a0000",
  "storage": {
    "0xb6318d15e99499c465cc5e3d630975bf37b5641a8beb2614b018219310f4ea12": "0x68836e425f5",
    "0xbf0f571b7368c19b53ab5ef0ff767ed8e0aef55a462778a6119b7871b017ce8f": "0x71094412456b0"
  }
}

miniBlocks

Streams mini-blocks as they are produced by the sequencer.

Parameters: None.

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["miniBlocks"]
}

Notification schema:

Field Type Notes
block_number Quantity EVM block number that this mini-block belongs to
block_timestamp Quantity EVM block timestamp
index Quantity Index of this mini-block within the EVM block
mini_block_number Quantity Global mini-block height
mini_block_timestamp Quantity Creation timestamp (Unix microseconds)
gas_used Quantity Gas consumed in this mini-block
transactions Transaction[] Transactions (same schema as eth_getTransactionByHash)
receipts Receipt[] Receipts (same schema as eth_getTransactionReceipt)

newHeads

Streams EVM block headers as they are sealed. Standard Ethereum subscription — works the same as on other EVM chains. On MegaETH, headers include an additional miniBlockCount field.

Parameters: None.

Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": ["newHeads"]
}

Errors

Code Cause Fix
-32602 Invalid subscription type or malformed parameters Fix the request
-32000 WebSocket connection required Use a WebSocket endpoint, not HTTP

See also Error reference.