EIP-8072: Transaction Inclusion Subscription

Abstract

---

This EIP extends the existing eth_subscribe JSON-RPC method with a new subscription type transactionInclusion that enables clients to receive real-time notifications when transactions are included in blocks. This subscription-based approach provides efficient transaction confirmation monitoring without blocking connections, supporting both combined transaction submission and monitoring in a single call, as well as monitoring of already-submitted transactions.

Motivation

---

Current transaction submission workflows require separate calls to eth_sendRawTransaction followed by repeated polling of eth_getTransactionReceipt, creating unnecessary latency and network overhead. While EIP-7966 proposes eth_sendRawTransactionSync to address this through a synchronous blocking approach, blocking HTTP connections presents significant drawbacks:

• Connection hogging: Each transaction blocks one HTTP connection until confirmation or timeout
• Limited scalability: Cannot efficiently monitor multiple transactions over a single connection
• Timeout complexity: Requires careful tuning of timeout parameters for different blockchain slot times
• Resource inefficiency: Repeated polling consumes bandwidth and server resources

The subscription-based approach leverages the battle-tested eth_subscribe mechanism already implemented across all major Ethereum clients, providing superior resource efficiency and scalability while maintaining feature parity with synchronous approaches.

Specification

---

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 and RFC 8174.

New Subscription Type

A new subscription type transactionInclusion is added to the eth_subscribe method.

Subscription Request

Or for monitoring an already-submitted transaction:

Parameters

The subscription parameters object accepts the following fields:

• transaction (DATA, optional): Signed transaction data to submit and monitor. When provided, the node MUST immediately submit this transaction to the network.
• hash (DATA, 32 bytes, optional): Transaction hash to monitor for already-submitted transactions.
• includeReorgs (boolean, optional, default: false): Controls reorg monitoring behavior.
  • If false: Subscription auto-unsubscribes immediately after first inclusion notification. Reorgs are not monitored.
  • If true: Subscription actively monitors for reorgs and sends notifications for reorgs, re-inclusions, and finalization.

Exactly one of transaction or hash MUST be provided. If both or neither are provided, the node MUST return a JSON-RPC error with code -32602 (Invalid params).

Subscription Response

Upon successful subscription, the node MUST return a subscription ID:

Notification Format

When the transaction status changes, the node MUST send a notification:

The status field MAY be one of:

• "included": Transaction has been included in a block
• "finalized": Transaction's block has reached finality (only sent when includeReorgs is true)
• "reorged": Transaction was removed from the canonical chain (only sent if includeReorgs is true)

The receipt field MUST contain the complete transaction receipt object as defined by eth_getTransactionReceipt.

Behavior

The node MUST implement the following behavior:

1. When transaction is provided:

   • The node MUST immediately submit the transaction to the network using the same semantics as eth_sendRawTransaction
   • The node MUST derive the transaction hash and begin monitoring for inclusion
   • If submission fails, the node MUST return a JSON-RPC error and MUST NOT create the subscription

2. Transaction Already Included:

   • If the monitored transaction is already included in a block at subscription time:
     • If includeReorgs is false: The node MUST immediately send an inclusion notification and automatically unsubscribe
     • If includeReorgs is true: The node MUST immediately send an inclusion notification and continue monitoring until finalization

3. Pending Transaction:

   • The node MUST monitor the transaction pool and canonical chain
   • When the transaction is included in a block, the node MUST send an inclusion notification
   • If includeReorgs is false, the node MUST then automatically unsubscribe
   • If includeReorgs is true, the node MUST continue monitoring

4. Reorg Monitoring (when includeReorgs is true):

   • The node MUST continue monitoring the transaction after initial inclusion
   • If the transaction is removed from the canonical chain due to a reorg, the node MUST send a notification with "status": "reorged"
   • If the transaction is re-included in a different block, the node MUST send a new inclusion notification with "status": "included"
   • When the block containing the transaction reaches finality, the node MUST send a finalization notification with "status": "finalized"
   • The node MUST automatically unsubscribe after sending the finalization notification

5. Auto-unsubscribe:

   • If includeReorgs is false, the node MUST automatically unsubscribe after sending the first inclusion notification
   • The node SHOULD send an eth_subscription unsubscribe confirmation

6. Transaction Not Found:

   • If monitoring a transaction by hash that doesn't exist in the mempool or chain, the subscription remains active
   • The node SHOULD monitor for the transaction appearing in the future
   • Clients MAY manually unsubscribe if desired

Rationale

---

Why Subscription Over Synchronous?

Subscriptions provide several advantages over the synchronous approach proposed in EIP-7966:

• Non-blocking: Clients can perform other operations while waiting for confirmation
• Multiplexing: Multiple transactions can be monitored over a single WebSocket connection
• No timeout complexity: Subscriptions naturally handle varying confirmation times without timeout parameters
• Proven infrastructure: Leverages existing eth_subscribe implementation present in all major clients

The addition of the transaction parameter provides complete feature parity with eth_sendRawTransactionSync by enabling submission and monitoring in a single call.

Why Extend eth_subscribe?

The eth_subscribe mechanism is battle-tested and already implemented across all major Ethereum clients. Extending it with a new subscription type requires minimal implementation effort compared to introducing entirely new RPC methods.

Why Support Both transaction and hash?

Supporting both parameters provides maximum flexibility:

• transaction: Optimal for new transactions, matching the convenience of synchronous methods
• hash: Enables monitoring of transactions submitted through other means or by other parties

Why Support Reorg Monitoring?

Applications requiring high confidence in transaction finality benefit from reorg notifications. This is particularly important on chains with faster block times where reorgs may be more common. The optional nature of this feature allows applications to choose the appropriate trade-off between functionality and resource usage.

Resource Efficiency

A single WebSocket connection can support unlimited concurrent transaction subscriptions, whereas synchronous approaches require one blocking HTTP connection per transaction. This represents a significant improvement in resource utilization for applications monitoring multiple transactions.

Why Always Auto-unsubscribe?

Both modes auto-unsubscribe to prevent unbounded subscription accumulation and provide clear lifecycle management:

• includeReorgs: false: Unsubscribes immediately after first inclusion for fast feedback with minimal resource usage. Users accepting this mode understand the transaction may still be reorged and can manually monitor if needed.
• includeReorgs: true: Unsubscribes after finalization when reorgs are no longer possible, providing complete transaction lifecycle monitoring.

The key difference is the level of guarantee:

• includeReorgs: false: Fast notification, transaction is included (may still reorg)
• includeReorgs: true: Complete lifecycle tracking until finality (cannot reorg)

Backwards Compatibility

---

This EIP is fully backwards compatible. It extends the existing eth_subscribe method with a new subscription type. Clients that have not implemented this feature will return a standard JSON-RPC error indicating the subscription type is not supported. Existing applications continue to function unchanged.

Test Cases

---

Test Case 1: Submit and Monitor

Request:

Expected Behavior:

1. Node submits transaction to network
2. Node returns subscription ID
3. When transaction is included, node sends notification with "status": "included" and receipt
4. Subscription automatically closes immediately

Test Case 2: Monitor Existing Transaction

Request:

Expected Behavior:

1. If transaction already included, immediately send notification with "status": "included"
2. If transaction pending, wait and send notification upon inclusion
3. Subscription automatically closes immediately after notification

Test Case 3: Reorg Monitoring

Request:

Expected Behavior:

1. Send inclusion notification when transaction is included (with "status": "included")
2. Continue monitoring for reorgs
3. If reorg occurs, send reorg notification (with "status": "reorged")
4. If re-included, send new inclusion notification (with "status": "included")
5. When block is finalized, send finalization notification (with "status": "finalized")
6. Subscription automatically closes after finalization

Test Case 4: Invalid Parameters

Request:

Expected Response:

Reference Implementation

---

A minimal reference implementation can be realized by:

1. For transaction parameter: Call internal eth_sendRawTransaction logic and capture the transaction hash
2. Register the transaction hash in a subscription manager
3. Monitor the transaction pool and canonical chain for the transaction
4. When the transaction is included in a block, query the receipt and send notification
5. If includeReorgs is false, automatically unsubscribe after first inclusion
6. If includeReorgs is true, continue monitoring for chain reorganizations

Implementation pseudo-code:

Security Considerations

---

Transaction Submission Validation

When transaction is provided, nodes MUST perform the same validation as eth_sendRawTransaction before creating the subscription. Invalid transactions MUST result in an error response without creating a subscription.

Privacy Considerations

Monitoring transactions by hash does not introduce new privacy concerns beyond existing eth_getTransactionReceipt polling. However, applications should be aware that subscribing to transaction hashes reveals interest in those transactions to the node operator.

Reorg Attack Considerations

Applications using includeReorgs: true should implement appropriate logic to handle reorg notifications, particularly on chains where reorgs may be used maliciously. The notification mechanism provides transparency but does not prevent reorg-based attacks.

Copyright

---

Copyright and related rights waived via CC0.