Initiate a canonical L2 withdrawal
A canonical withdrawal is a three-phase protocol — initiate on L2, prove against a posted root on L1,
then finalise after the challenge window — and skipping or mis-ordering a phase means the funds sit
unclaimed on L1 until you redo it.
Procedure
Initiate on the L2. For OP Stack plus ETH or an ERC-20, call the L2 standard bridge; the money is
burned/escrowed on L2 and a message is appended to the L2-to-L1 message passer:
cast send $L2_STANDARD_BRIDGE "withdraw(address,uint256,uint32,bytes)" \
$TOKEN $AMOUNT 200000 0x --rpc-url $L2RPC --private-key $KEY
Native ETH on OP Stack: send to L2ToL1MessagePasser (0x4200000000000000000000000000000000000016)
via initiateWithdrawal.
Capture the withdrawal identity: the MessagePassed event on L2 gives the nonce, sender, target,
value, gasLimit, data, and the withdrawalHash. This hash keys everything downstream.
Wait for an L2 output root covering your L2 block to be posted on L1. On OP Stack this is the
L2OutputOracle (or the DisputeGameFactory under fault proofs); on Arbitrum, the rollup must
confirm the block. No root, no proof.
Prove on L1 with the withdrawal and its merkle proof against that output root:
cast send $OPTIMISM_PORTAL "proveWithdrawalTransaction((uint256,address,address,uint256,uint256,bytes),uint256,bytes32,bytes32[])" \
"($NONCE,$SENDER,$TARGET,$VALUE,$GASLIMIT,$DATA)" $OUTPUT_INDEX $ROOT $PROOF --rpc-url $L1RPC
Arbitrum: nothing to prove manually; the Outbox executes against the confirmed rollup block.
Wait the challenge window. OP mainnet: 604800 s (7 days). Arbitrum One: ~6.4 days (45818 L1 blocks).
Track provenWithdrawals[hash].timestamp.
Finalise on L1:
cast send $OPTIMISM_PORTAL "finalizeWithdrawalTransaction((uint256,address,address,uint256,uint256,bytes))" \
"($NONCE,$SENDER,$TARGET,$VALUE,$GASLIMIT,$DATA)" --rpc-url $L1RPC
Or Outbox.executeTransaction on Arbitrum. Confirm the target received the funds.
Record each transaction hash and the phase timestamps so the withdrawal is auditable end to end.
Pitfalls
- Using a third-party bridge when the user asked for the canonical one (or vice versa); they have
different trust and fee profiles. Confirm which is meant.
- Proving against an output root that is later disputed, invalidating finalisation; re-prove against
the winning root.
- Under-estimating the L2-to-L1 message gas on the finalise call, which can revert and strand the
proof (though it stays re-finalisable).
- Forgetting that Arbitrum withdrawals need no manual prove step but do need the rollup block to
confirm — assuming it is instant leads to failed
Outbox calls.
- Sending the L2
withdraw to the wrong bridge address (a lookalike); verify the canonical address
from the chain's docs, not a token list.
Verification
cast call $OPTIMISM_PORTAL "provenWithdrawals(bytes32)(bytes32,uint128,uint128)" $WITHDRAWAL_HASH --rpc-url $L1RPC
cast receipt $FINALIZE_TXHASH --rpc-url $L1RPC --field status # 1 == funds released
Report the withdrawal hash, the output index and root used, the challenge-period end time, and the
finalise transaction status.
1---2name: initiate-a-canonical-l2-withdrawal3description: Use when moving assets from an L2 back to L1 through the canonical bridge, following the initiate-prove-wait-finalise sequence rather than a third-party bridge.4metadata:5 source: https://skillmd.com/skills/jiayaoqijia/initiate-a-canonical-l2-withdrawal6---78# Initiate a canonical L2 withdrawal910A canonical withdrawal is a three-phase protocol — initiate on L2, prove against a posted root on L1,11then finalise after the challenge window — and skipping or mis-ordering a phase means the funds sit12unclaimed on L1 until you redo it.1314## Procedure15161. Initiate on the L2. For OP Stack plus ETH or an ERC-20, call the L2 standard bridge; the money is17 burned/escrowed on L2 and a message is appended to the L2-to-L1 message passer:1819 cast send $L2_STANDARD_BRIDGE "withdraw(address,uint256,uint32,bytes)" \20 $TOKEN $AMOUNT 200000 0x --rpc-url $L2RPC --private-key $KEY2122 Native ETH on OP Stack: send to `L2ToL1MessagePasser` (0x4200000000000000000000000000000000000016)23 via `initiateWithdrawal`.24252. Capture the withdrawal identity: the `MessagePassed` event on L2 gives the nonce, sender, target,26 value, gasLimit, data, and the `withdrawalHash`. This hash keys everything downstream.27283. Wait for an L2 output root covering your L2 block to be posted on L1. On OP Stack this is the29 `L2OutputOracle` (or the `DisputeGameFactory` under fault proofs); on Arbitrum, the rollup must30 confirm the block. No root, no proof.31324. Prove on L1 with the withdrawal and its merkle proof against that output root:3334 cast send $OPTIMISM_PORTAL "proveWithdrawalTransaction((uint256,address,address,uint256,uint256,bytes),uint256,bytes32,bytes32[])" \35 "($NONCE,$SENDER,$TARGET,$VALUE,$GASLIMIT,$DATA)" $OUTPUT_INDEX $ROOT $PROOF --rpc-url $L1RPC3637 Arbitrum: nothing to prove manually; the `Outbox` executes against the confirmed rollup block.38395. Wait the challenge window. OP mainnet: 604800 s (7 days). Arbitrum One: ~6.4 days (45818 L1 blocks).40 Track `provenWithdrawals[hash].timestamp`.41426. Finalise on L1:4344 cast send $OPTIMISM_PORTAL "finalizeWithdrawalTransaction((uint256,address,address,uint256,uint256,bytes))" \45 "($NONCE,$SENDER,$TARGET,$VALUE,$GASLIMIT,$DATA)" --rpc-url $L1RPC4647 Or `Outbox.executeTransaction` on Arbitrum. Confirm the target received the funds.48497. Record each transaction hash and the phase timestamps so the withdrawal is auditable end to end.5051## Pitfalls5253- Using a third-party bridge when the user asked for the canonical one (or vice versa); they have54 different trust and fee profiles. Confirm which is meant.55- Proving against an output root that is later disputed, invalidating finalisation; re-prove against56 the winning root.57- Under-estimating the L2-to-L1 message gas on the finalise call, which can revert and strand the58 proof (though it stays re-finalisable).59- Forgetting that Arbitrum withdrawals need no manual prove step but do need the rollup block to60 confirm — assuming it is instant leads to failed `Outbox` calls.61- Sending the L2 `withdraw` to the wrong bridge address (a lookalike); verify the canonical address62 from the chain's docs, not a token list.6364## Verification6566 cast call $OPTIMISM_PORTAL "provenWithdrawals(bytes32)(bytes32,uint128,uint128)" $WITHDRAWAL_HASH --rpc-url $L1RPC67 cast receipt $FINALIZE_TXHASH --rpc-url $L1RPC --field status # 1 == funds released6869Report the withdrawal hash, the output index and root used, the challenge-period end time, and the70finalise transaction status.