EIP-8072 Transaction inclusion subscription

No call decision · Networking & nodes · EIP status Draft · created 2025-10-31

It adds a transactionInclusion type to the node's subscription feature (eth_subscribe), so a real-time notification and receipt are delivered the moment a transaction is included in a block.

Why it is needed

Today, finding out the result after sending a transaction takes two steps. First you submit it with eth_sendRawTransaction, and then you repeatedly call receipt lookups (eth_getTransactionReceipt) to check whether it has been included. This repeated polling causes unnecessary delay and network overhead. EIP-7966's eth_sendRawTransactionSync, proposed to solve this, is a synchronous approach that waits for a response until inclusion, but it comes with other costs. Each transaction ties up one HTTP connection, one connection cannot watch multiple transactions, and timeouts must be tuned for each chain's differing block time. This EIP extends the subscription approach that is already implemented and proven on all major clients, offering a way to receive inclusion notifications without blocking the connection. Submission and monitoring can be bundled into a single call, or an already-submitted transaction can be watched by its hash.

What changes

Today

After EIP-8072

Who is affected

In depth

New subscription type and parameters

Adds a transactionInclusion subscription type to eth_subscribe. The parameter object accepts three fields. transaction (DATA, optional) is the signed transaction data to submit and monitor at once; when this field is present, the node must submit it to the network immediately. hash (DATA, 32 bytes, optional) is the hash used to watch a transaction that has already been submitted. includeReorgs (boolean, optional, default false) determines whether reorg monitoring is enabled. Exactly one of transaction and hash must be provided; if both or neither are given, the node must return JSON-RPC error code -32602 (Invalid params).

Notification Format and status Values

When the status changes, the node sends an eth_subscription notification. The result contains status, blockHash, blockNumber, transactionIndex, and receipt, where receipt must be the complete receipt object as defined by eth_getTransactionReceipt. There are three status values. "included" means the transaction has been included in a block, "finalized" means that block has reached finality, and "reorged" means the transaction was removed from the canonical chain due to a reorg. "finalized" and "reorged" are only sent when includeReorgs is true.

Node Behavior Rules

If transaction is provided, the node submits it immediately with the same semantics as eth_sendRawTransaction, derives the hash, and begins monitoring. If submission fails, the node must return an error and must not create a subscription. If the transaction is already included in a block at subscription time, the node immediately sends an inclusion notification. If includeReorgs is false, it then unsubscribes right away; if true, it keeps watching until finality. If the transaction is still pending, the node monitors the transaction pool and the canonical chain and sends a notification at the point of inclusion. If a transaction watched by hash is in neither the mempool nor the chain, the subscription remains active, and it is recommended that the node continue watching for it to appear later; the client may unsubscribe manually if desired.

Reorg Monitoring and Automatic Unsubscription

If includeReorgs is true, monitoring continues even after the first inclusion. If a reorg removes the transaction from the canonical chain, a "reorged" notification is sent; if it is included again in a different block, a new "included" notification is sent; and once the block reaches finality, a "finalized" notification is sent followed by automatic unsubscription. Both modes auto-unsubscribe to prevent subscriptions from accumulating indefinitely and to keep the lifecycle well defined. The false mode is meant for fast feedback, with the user accepting that the transaction could still be reorged after inclusion, while the true mode tracks the full lifecycle through to finality, at which point a reorg is no longer possible.

Comparison with the EIP-7966 Synchronous Approach

The source cites four advantages of the subscription approach. It does not block the connection, so other work can proceed while waiting; a single WebSocket connection can multiplex many transactions; it needs no timeout parameter even when confirmation times vary widely; and since it builds on eth_subscribe, which all major clients already support, the implementation burden is small. Adding the transaction parameter, which combines submission and monitoring into a single call, gives it full feature parity with eth_sendRawTransactionSync. The synchronous approach needs one blocking HTTP connection per transaction, whereas a subscription places no limit on the number of concurrent subscriptions over a single connection.

Security and Privacy Considerations

If transaction is provided, the node must perform the same validation as eth_sendRawTransaction before creating the subscription, and an invalid transaction must fail with an error without creating a subscription. Monitoring by hash introduces no new privacy issues beyond existing receipt polling, but it is worth noting that which hash is subscribed to reveals to the node operator an interest in that transaction. Applications that use includeReorgs must implement logic to handle reorg notifications; the notifications only provide transparency and do not themselves prevent reorg-based attacks.

Backwards compatibility and status

This simply adds one more subscription type to the existing eth_subscribe, so it is fully backward compatible. Clients that do not support this feature return the standard JSON-RPC error for an unsupported subscription type, and existing applications continue to work unchanged. This EIP is an interface standard created on October 31, 2025, and is currently in Draft status, so the specification may still change.

Original EIP · ← EIPs