How to withdraw tokens from Whitechain to Ethereum using the canonical bridge

A withdrawal takes about an hour on testnet. On mainnet, it takes at least 7 days. This delay is enforced by the protocol on Ethereum and cannot be skipped, so plan treasury and time-sensitive flows around it. A withdrawal cannot be cancelled once proven. If the dispute game your withdrawal was proven against resolves against the proposer, your proof is invalidated, but your funds are not lost: you re-prove against a different, honest game, and the delay countdown restarts.

To make a withdrawal, please follow these next steps:

  1. Initiate on L2. Call L2StandardBridge.bridgeERC20 for ERC20 tokens, L2ERC721Bridge.bridgeERC721 for L1-origin NFTs, or L2CrossDomainMessenger.sendMessage for arbitrary messages. Tokens are burned for L1-origin tokens and escrowed for L2-native tokens. L2-native NFTs cannot be withdrawn. The canonical bridge does not handle native WBT withdrawals; use the Portal bridge for that.
  2. Wait for an output proposal. The op-proposer publishes an output root on L1 via the DisputeGameFactory at a fixed interval (every 30 minutes on testnet). Your withdrawal can only be proven against a dispute game whose l2BlockNumber is greater than or equal to the L2 block of your withdrawal transaction. To find a suitable game and its gameIndex, monitor the create transactions on the DisputeGameFactory contract in the explorer.
  3. Prove the withdrawal on L1. Call OptimismPortal.proveWithdrawalTransaction with the gameIndex and a Merkle proof from L2 storage. Tools such as viem OP Stack actions or op-withdrawer compute the proof for you.
  4. Resolve the dispute game. The game must resolve as DEFENDER_WINS before you can finalize. If it still has IN_PROGRESS status after its challenge clock expires, anyone can call resolveClaim on the game contract to resolve it. This step is permissionless and is typically handled by an off-chain service. If the game instead resolves as CHALLENGER_WINS, your proof is invalidated but your funds are not lost. Re-prove against a different, honest game; the delay countdown restarts from the new prove transaction.
  5. Wait for the dispute-resolution delays. Two independent delays must elapse before finalization is allowed. proofMaturityDelaySeconds is the minimum time since your prove transaction. disputeGameFinalityDelaySeconds is the minimum time since the game resolved in favor of the defender. 
  6. Finalize on L1. Call OptimismPortal.finalizeWithdrawalTransaction to release the funds to L1.

More detailed information about the canonical bridge and when you should use it or not is described in the following article. 

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request