Migrate your transaction submission code
Update code that relies on eth_sendRawTransaction returning after inclusion, or on its inclusion-time errors. Switch to eth_sendRawTransactionSync, handle transactions dropped without a receipt, and test the change on Arbitrum Sepolia.
Update your transaction submission code for the new behavior of eth_sendRawTransaction and eth_sendRawTransactionSync on Arbitrum chains. For how each method behaves, see Transaction submission behavior.
This behavior reaches Arbitrum Sepolia first and Arbitrum One later. Make and test your changes on Arbitrum Sepolia before the change reaches the chain you use in production.
eth_sendRawTransactionConditional behavior and semantics are out of scope for these changes. Offchain Labs plans to disable that method. See the notice: Deprecation of eth_sendRawTransactionConditional.
Do you need to change anything?
Find the row that matches how you submit transactions today.
| If you… | What changes | What to do |
|---|---|---|
Treat an eth_sendRawTransaction response as "received," then confirm through a receipt, the sequencer feed, or a nonce check | You get the transaction hash sooner. | Nothing. |
| Submit user operations through ZeroDev's UltraRelay bundler | You get user operation receipts sooner. | Nothing. |
Poll eth_getTransactionReceipt and don't need the blockHash | One eth_sendRawTransactionSync call returns the receipt and logs sooner. | Switch. See Replace receipt polling with one call. |
Run custom infrastructure to serve eth_sendRawTransactionSync calls | An upgraded Nitro node serves these calls natively. | See Retire custom infrastructure. |
Treat an eth_sendRawTransaction response as "included" | A successful response means the sequencer admitted the transaction into its queue. It no longer means the transaction is in a block. | See Stop treating a successful response as "included". |
Retry based on eth_sendRawTransaction errors from inclusion time | eth_sendRawTransaction no longer returns execution-time or inclusion-time errors. | See Move retry logic. |
Need the canonical receipt with the blockHash | The eth_sendRawTransactionSync receipt has a 32-byte zero blockHash (0x00…00). | Keep polling eth_getTransactionReceipt. |
Before you begin
- Find out which node serves your calls. After the change, the early receipt from
eth_sendRawTransactionSyncneeds 3.13.x on that node, with--execution.rpc.tx-sync-forward=trueset. Nitro 3.13.x isn't released yet. If you use a third-party RPC (remote procedure call) provider, callweb3_clientVersionon its endpoint to check its Nitro version. - Send
eth_sendRawTransactionSynccalls to an RPC node. The public endpoint accepts onlyeth_sendRawTransactionandeth_sendRawTransactionConditional. - Have a funded test account on Arbitrum Sepolia. You verify each change there before mainnet. The Arbitrum Sepolia RPC URL is
https://sepolia-rollup.arbitrum.io/rpc.
The examples call the JSON-RPC API with curl, so they work with any library. JSON-RPC is the JSON-based remote procedure call interface that Ethereum nodes expose. Set these variables first:
export RPC_URL="https://sepolia-rollup.arbitrum.io/rpc"
export SIGNED_TX="0x..." # a signed transaction, RLP-encoded (Recursive Length Prefix)Stop treating a successful eth_sendRawTransaction response as "included"
A successful eth_sendRawTransaction response means the sequencer admitted the transaction into its queue. It doesn't mean the transaction is in a block. If your code moves on as soon as the call succeeds, pick one of these options.
Option 1: Switch to eth_sendRawTransactionSync
If your workflow needs the transaction's outcome from the receipt after submission, use this option. eth_sendRawTransactionSync returns sooner than eth_sendRawTransaction did before the change, so switching doesn't slow your submission path.
-
Replace the
eth_sendRawTransactioncall witheth_sendRawTransactionSync. The second parameter is an optional timeout in milliseconds:curl -s "$RPC_URL" -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "eth_sendRawTransactionSync", "params": ["'"$SIGNED_TX"'", 5000] }' -
Read the result as a transaction receipt, not a hash. Take the hash from
result.transactionHash. -
Check
result.status.0x1means the transaction succeeded.0x0means it reverted. -
Don't rely on
result.blockHash. It's the zero hash, because the node returns the receipt before the block is complete. If your client validates the block hash, handle the zero value. If you need the block hash, polleth_getTransactionReceipt. -
Verify on Arbitrum Sepolia. Send a valid transaction. The call returns a receipt with
statusset and a zeroblockHash.
Option 2: Keep eth_sendRawTransaction and confirm separately
If you only need to know that the sequencer admitted the transaction into its queue, and you already confirm inclusion later or can, use this option.
-
Keep the
eth_sendRawTransactioncall. Store the transaction hash it returns. -
Poll
eth_getTransactionReceiptwith that hash until it returns a receipt:curl -s "$RPC_URL" -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "eth_getTransactionReceipt", "params": ["0xYOUR_TX_HASH"] }' -
If the receipt is still
nullat your deadline, follow Handle transactions with no receipt. -
Verify on Arbitrum Sepolia. Send a valid transaction. The call returns a hash, and a receipt appears when you poll.
Move retry logic to eth_sendRawTransactionSync
eth_sendRawTransaction doesn't report errors that happen at inclusion time. eth_sendRawTransactionSync reports most of them. If your retry logic depends on those errors, move it to eth_sendRawTransactionSync.
-
Replace the
eth_sendRawTransactioncall witheth_sendRawTransactionSync, as shown in Option 1. -
Route the admission-check errors to your existing handlers. Both methods return these errors right away:
- Nonce already used
- Insufficient funds
- Fee cap
- Queue full
-
Add handling for the inclusion-time errors in the
eth_sendRawTransactionSyncresponse:Cause How to retry Nonce gap Submit the missing nonce first, then retry. Fee cap below base fee Re-sign with the same nonce and a higher fee cap, then retry. Queue timeout Retry the same signed transaction with backoff. -
Handle a timeout. If the call times out, the transaction can still land afterward. EIP-7966 specifies error code
4for a timeout, with the transaction hash inerror.data. Before you retry, polleth_getTransactionReceiptwith that hash. Retry only with the same signed transaction or the same nonce, so the transaction can't land twice. -
Verify on Arbitrum Sepolia. Send a transaction whose nonce is one higher than the sender's next nonce. The call returns an error, not a receipt.
Handle transactions with no receipt
If you keep using eth_sendRawTransaction, a transaction can pass the admission checks and still be dropped at block time. You get no error and no receipt that the transaction was dropped. A deadline check keeps these transactions from waiting forever.
-
Set a deadline for each submitted transaction. Make it longer than the queue timeout and the nonce retry window, so the sequencer is done with the transaction. The queue timeout is 12 seconds by default. See Queue timeout. If your client timeout is shorter than the queue timeout, the sequencer can admit the transaction after your client stops waiting.
-
At the deadline, query the receipt once more. If it returns a receipt, the transaction is in a block.
-
If the receipt is still
null, read the sender's next nonce:curl -s "$RPC_URL" -H 'Content-Type: application/json' -d '{ "jsonrpc": "2.0", "id": 1, "method": "eth_getTransactionCount", "params": ["0xYOUR_ADDRESS", "latest"] }' -
Compare the result with your transaction's nonce,
N:- Greater than
N: a transaction with nonceNis in a block. Query the receipt again, because your node might have been behind. If it still returnsnull, a different transaction used nonceN. Don't resubmit yours. - Equal to
N: your transaction was dropped, and nothing else used nonceN. Compare its fee cap with the current base fee. Then resubmit the same signed transaction, or re-sign it with nonceNand a higher fee cap. - Less than
N: an earlier nonce is missing. Submit the missing transaction first, then resubmit yours. See Nonce management.
- Greater than
-
Verify on Arbitrum Sepolia. Send a transaction whose nonce is one higher than the sender's next nonce, and don't send the missing nonce. The call returns a hash, no receipt appears, and your deadline check reports the "less than
N" case.
Track outstanding nonces in your own code. On Arbitrum, eth_getTransactionCount doesn't count transactions the sequencer hasn't included. For details, see Nonce management.
Replace receipt polling with one call
If you poll eth_getTransactionReceipt after every submission and don't need the blockHash, one eth_sendRawTransactionSync call can replace both, and it returns sooner.
- Replace the submit-then-poll code with one
eth_sendRawTransactionSynccall, as shown in Option 1. - Read the status and logs from the returned receipt.
- Keep polling
eth_getTransactionReceiptonly in these cases:- You need the
blockHash. - You need to rule out a retracted receipt, a rare case.
- You need the
- Verify on Arbitrum Sepolia. Send a transaction that emits an event. The receipt includes its status and logs.
Retire custom infrastructure for eth_sendRawTransactionSync
An upgraded Nitro node serves eth_sendRawTransactionSync calls natively. If you don't upgrade, the node still serves these calls, but without the early receipt.
- Upgrade the node that serves your calls to Nitro 3.13.x.
- Set
--execution.rpc.tx-sync-forward=trueon that node. - Send a test transaction with
eth_sendRawTransactionSyncdirectly to that node. - Check that the receipt's
blockHashis zero. A zeroblockHashshows that the node returns the early receipt. - Route your
eth_sendRawTransactionSynctraffic to the node, then retire the custom setup.
To set how long a call can wait, see Timeouts.
How is this guide?
Transaction submission
Learn when eth_sendRawTransaction and eth_sendRawTransactionSync return on Arbitrum chains, which errors each method returns, why a transaction can be dropped without a receipt, and which method to use for latency-sensitive workflows.
Oracles
Overview of blockchain oracles on Arbitrum, the external providers that supply offchain data to smart contracts: how they work, trust models, and providers.