Bundles & Revert Protection
Advanced transaction submission with bundles, block ranges and revert protection.
eth_sendBundle
The eth_sendBundle
method allows developers to submit transactions with advanced execution controls, including block/timestamp ranges and revert protection. This feature is particularly useful for arbitrageurs and advanced users who need precise timing or want to avoid paying gas for failed transactions.
Overview
eth_sendBundle
enables you to:
- Control execution timing: Specify exactly when your transaction should execute using block numbers or timestamps
- Revert protection: Avoid paying gas fees for transactions that revert
- Atomic execution: Ensure your transaction executes in a specific window or not at all
Current Limitation: Bundles are limited to a single transaction. This limitation may be removed in future versions.
Why Use eth_sendBundle?
Traditional transaction submission can result in:
- Transactions executing at undesirable times
- Paying gas fees even when transactions revert due to changed market conditions
- Uncertainty about execution timing for time-sensitive operations
eth_sendBundle
solves these issues by providing:
- Conditional execution: Transactions only execute within your specified parameters
- Cost protection: No gas fees for reverted transactions (when revert protection is enabled)
- Precise timing: Execute transactions within specific block ranges or time windows
Method Signature
Response Format
A successful eth_sendBundle
call returns:
Important: The bundleHash
is equivalent to the transaction hash and can be used with standard methods like eth_getTransactionReceipt
to check execution status.
Parameters
txs (required)
- Type: Array of strings
- Description: Array containing a single signed transaction
- Format: Hex-encoded signed transaction data
Important: At this time, bundles only support a single transaction per submission.
Block Number Range (optional)
- minBlockNumber: Hex-encoded string of the minimum block number
- maxBlockNumber: Hex-encoded string of the maximum block number
- Behavior: Transaction executes when
minBlockNumber ≤ current block ≤ maxBlockNumber
- Default: If not specified, bundle expires after 10 blocks from submission
Timestamp Range (optional)
- minTimestamp: JSON number representing Unix timestamp
- maxTimestamp: JSON number representing Unix timestamp
- Behavior: Transaction executes when
minTimestamp ≤ current block timestamp ≤ maxTimestamp
Important: Block number ranges and timestamp ranges are mutually exclusive. Do not specify both.
revertingTxHashes (optional)
- Type: Array of strings
- Description: Transaction hashes that are allowed to revert without failing the bundle
- Behavior: If omitted, reverted transactions will not charge gas fees
Endpoints
You can submit bundles to either endpoint:
https://mainnet.unichain.org
- Standard endpointhttps://mainnet-sequencer.unichain.org
- Provides detailed error codes for transaction receipts
Bundle Lifecycle
- Submission: Bundle is submitted and enters the mempool
- Execution Window: Bundle remains active for up to 10 blocks (or until maxBlockNumber/maxTimestamp)
- Expiration: After the execution window, bundles are dropped from the mempool
- Receipt Queries: Expired bundles return error code
-32602: the transaction was dropped from the pool
Code Examples
Basic Bundle with Block Range
Bundle with Timestamp Range
Bundle with Revert Protection
Error Handling
Transaction Receipt Errors
When querying receipts for expired or dropped bundles:
Common Error Scenarios
- Bundle expired: Error code
-32602
when querying receipt after 10+ blocks - Invalid range: Bundle with
minBlockNumber > maxBlockNumber
will be rejected - Past timestamps: Bundles with
maxTimestamp
in the past are immediately invalid
Best Practices
-
Use appropriate time windows: Don't make ranges too narrow (may miss execution) or too wide (unnecessary delay)
-
Monitor bundle status: Check transaction receipts to confirm execution or detect expiration
-
Handle revert protection carefully: Understand that omitting
revertingTxHashes
provides automatic revert protection -
Use sequencer endpoint for debugging: Use
https://mainnet-sequencer.unichain.org
when you need detailed error information -
Plan for expiration: Implement logic to resubmit bundles if they expire without execution
Limitations
- Single transaction per bundle: Currently limited to one transaction per bundle (temporary limitation)
- 10-block default lifetime: Bundles automatically expire after 10 blocks if no
maxBlockNumber
specified - Mutually exclusive ranges: Cannot specify both block number and timestamp ranges
- No bundle cancellation: Once submitted, bundles cannot be cancelled (they must expire)
Use Cases
Arbitrage Operations
Time-Sensitive DeFi Operations
MEV Protection
Last updated on