OP Stack canonical bridge

Available on Testnet today. Mainnet contract addresses and final timing parameters are published at Mainnet launch.

Overview

Whitechain settles on Ethereum via the OP Stack canonical bridge. Assets and arbitrary messages move between L1 (Ethereum) and L2 (Whitechain) through Optimism-standard bridge contracts. Deposits arrive on L2 in about 2 minutes. Withdrawals back to L1 complete after a mandatory dispute-resolution period: minimum 7 days on mainnet, about 1 hour on testnet (see Timing parameters).

Ethereum to Whitechain

Deposits (L1 to L2)

A deposit takes about 2 minutes. You initiate the deposit on L1 and the op-node automatically finalizes it on L2. No further action is required on L2 once the deposit is confirmed.

Asset	L1 method	Notes
ETH (native)	Not supported	Whitechain runs in Custom Gas Token (CGT) mode. `depositETH` reverts with `OptimismPortal_NotAllowedOnCGTMode()`.
WBT (native gas token)	Not supported	There is no L1-to-L2 gas-token deposit path for native WBT, on testnet or mainnet. Use the Portal bridge to move WBT between Ethereum and Whitechain, or claim testnet WBT from the faucet.
ERC20 tokens	`approve`, then `L1StandardBridge.depositERC20`	The L2 token must already be deployed. See For token issuers.
NFTs (ERC721)	`approve`, then `L1Erc721BridgeProxy.bridgeERC721`	Only L1-origin NFTs are supported.
Arbitrary messages	`L1CrossDomainMessenger.sendMessage`	Has replay support if the L2 call runs out of gas. `OptimismPortal.depositTransaction` has no replay; do not call it directly.

Example depositERC20 parameters:

Field	Example value	Note
`_l1Token`	address of the L1 token	must have a paired L2 token
`_l2Token`	address of the L2 `OptimismMintableERC20`	deployed via the factory
`_amount`	`10000000`	10 tokens at 6 decimals
`_minGasLimit`	`200000`	minimum gas for L2 execution
`_extraData`	`0x`	optional, empty by default

After ~2 minutes, verify the balance with balanceOf on the L2 token contract.

Withdrawals (L2 to L1)

A withdrawal takes about an hour on testnet. On mainnet it takes minimum 7 days. The wait for a qualifying output proposal adds to that minimum, and so does re-proving against a new game if the initial dispute game is successfully challenged (see Timing parameters for exact figures). The flow has six steps:

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 (see When NOT to use the canonical bridge). The canonical bridge does not handle native WBT withdrawals; use the Portal bridge for that.
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.
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 (see Programmatic bridging).
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.
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. See Timing parameters for current values on each network.
Finalize on L1 call OptimismPortal.finalizeWithdrawalTransaction to release the funds to L1.

The dispute-resolution delay on mainnet (minimum 7 days) is enforced by the protocol and cannot be skipped. Plan treasury operations and time-sensitive flows accordingly. Testnet delays are intentionally shortened and do not reflect mainnet behavior. For urgent exits, see When NOT to use the canonical bridge.

Timing parameters

Parameter	Testnet	Mainnet (planned)
Deposit (L1 to L2)	~2 minutes	~2 minutes
Proposer interval (new dispute game)	30 minutes	TBD, confirmed once mainnet parameters are set
`proofMaturityDelaySeconds`	15 minutes	7 days
`disputeGameFinalityDelaySeconds`	5 minutes	TBD, confirmed once mainnet parameters are set
Full withdrawal cycle	~1 hour typical, up to ~3 hours (observed; see note below)	minimum 7 days

The full testnet cycle is longer than the two delays combined (15 + 5 minutes) because of discrete service intervals. A withdrawal can only be proven once a dispute game covers its L2 block. If the latest game predates your transaction, you wait for the next one: an observed wait of up to ~45 minutes within a measured 64-minute cycle. In the worst case, when batcher and proposer intervals align unfavorably across stages, the full cycle reaches about 3 hours. Testnet delays are intentionally shortened to allow end-to-end testing. Do not assume testnet timings apply to mainnet. Mainnet values follow the OP Stack default consensus parameters (see specs.optimism.io, section Configurability, Consensus parameters).

Programmatic bridging

Common paths for interacting with the bridge contracts directly:

Tool	What it does
viem OP Stack actions	Recommended. The `viem/op-stack` module extends a client with L1 and L2 actions (`depositTransaction`, `proveWithdrawal`, `finalizeWithdrawal`, and the `buildProveWithdrawal` and `getWithdrawals` helpers) that build the proofs for you. See Use viem with Whitechain.
op-withdrawer	CLI that runs the prove and finalize steps for L2 to L1 withdrawals. It is a release-candidate build (`v0.0.1-rc6`) from `base/op-enclave`; treat it as pre-release and pin the version.
Direct contract calls	Any Ethereum-compatible library (viem, ethers, web3.js) can call the bridge contracts. See Contract addresses.

The @eth-optimism/sdk package is deprecated and is no longer maintained. Use viem OP Stack actions instead. Withdrawals still require the prove and finalize steps described above, regardless of which tool you use. No tool triggers them automatically. Proof generation additionally requires an archive-capable L2 RPC endpoint, since eth_getProof needs historical state access beyond the default pruning window. Without this step, funds remain locked in the L1 bridge escrow.

Contract addresses

Contract addresses below are for testnet. Mainnet addresses will be added once mainnet is live.

Testnet

L2 addresses below fall in the 0x4200... predeploy range. They are identical across every OP Stack environment: devnet, testnet, and mainnet. L1 addresses are specific to this testnet deployment and will change if the deployment is ever redone. When verifying addresses, focus on the L1 side; the 0x4200... L2 predeploys are fixed by the protocol and never change.

Contract	L1	L2
`L1StandardBridge`	`0x0c50be539ab5d72d226038928f2eb25100899ded`	n/a
`OptimismPortal`	`0xff9b597b0781457ae6aa7256ca5ed5839bf7d0c3`	n/a
`DisputeGameFactoryProxy`	`0xfaa2faa8912c069c01abc169c33713c79027c833`	n/a
`L1CrossDomainMessengerProxy`	`0x547967f45d19dc4ca0a056ba525afe99bda18a88`	n/a
`L1Erc721BridgeProxy`	`0x1e419fc5575bbd6d352582e9d8073918d79f0c5b`	n/a
`SystemConfigProxy`	`0x9328ea869949f33c57b7b680b6edb58769e2181c`	n/a
`OptimismMintableERC20FactoryProxy`	`0x5898f6c319842a379799d634c6ed2da960a42b9b`	n/a
`L2StandardBridge`	n/a	`0x4200000000000000000000000000000000000010`
`L2CrossDomainMessenger`	n/a	`0x4200000000000000000000000000000000000007`
`OptimismMintableERC20Factory`	n/a	`0x4200000000000000000000000000000000000012`
`L2ERC721Bridge`	n/a	`0x4200000000000000000000000000000000000014`
`OptimismMintableERC721Factory`	n/a	`0x4200000000000000000000000000000000000017`

OptimismPortal2 is the current implementation contract behind the OptimismPortal address above; use the name OptimismPortal when referring to it.

When NOT to use the canonical bridge

The canonical bridge is the safest and most trust-minimized path between L1 and L2, but it does not fit every use case.

Scenario	Why the canonical bridge does not work	Alternative
Need to exit to L1 quickly (mainnet)	The dispute-resolution period (minimum 7 days on mainnet) is mandatory and cannot be skipped	The Portal bridge for a faster, centralized transfer. On mainnet there is no fast canonical exit yet; plan for the full dispute period
Bridging USDC	Whitechain already has a canonical USDC.e representation; a second wrapped pairing created via the factory would fragment liquidity	Use the Portal bridge for USDC.e
Token has transfer fees or rebasing logic	The standard bridge does not account for balance changes during transfer	A custom bridge contract designed for the token
Token has a blocklist or pausable transfer	Finalization may revert permanently, leaving funds stuck	A custom bridge contract
L2-native NFTs going to L1	The standard `L2ERC721Bridge` only supports L1-origin NFTs	A custom NFT bridge
Very large amounts with time-sensitivity	Funds are locked for the entire dispute-resolution period	Stage the transfer in advance, or use a third-party bridge

For token issuers

To make an L1 ERC20 bridgeable to Whitechain, deploy an OptimismMintableERC20 on L2 that mirrors the L1 token. Use the OptimismMintableERC20Factory.createOptimismMintableERC20WithDecimals function with the L1 token address, the name and symbol you want on L2, and the decimals. Before creating a new pairing, confirm the token doesn’t already have an official Whitechain representation (see When NOT to use the canonical bridge). A second wrapped version of an already-represented token fragments liquidity. Example createOptimismMintableERC20WithDecimals parameters:

Field	Example value
`_remoteToken`	address of the original L1 token
`_name`	Example Token
`_symbol`	EXT
`_decimals`	18

The resulting L2 token grants mint and burn rights exclusively to the L2StandardBridge. Verify the pairing before sending real value: L1StandardBridge.deposits(l1Token, l2Token) must return a non-zero value, or query the factory to confirm the L2 contract was created. Tokens with transfer fees, rebasing logic, blocklists, or pausable transfers are not compatible with the standard bridge. Use a custom bridge solution for those cases.

Disclaimer

Always test with a small amount before bridging large balances.
Verify every contract address against this page or the official Whitechain Explorer before submitting a transaction.
Withdrawals are non-reversible once finalized on L1.

Wallet

Dapps

Deploy

Bridge

Block Explorer

Ecosystem

OP Stack canonical bridge

Overview

Ethereum to Whitechain

Deposits (L1 to L2)

Withdrawals (L2 to L1)

Timing parameters

Programmatic bridging

Contract addresses

Testnet

When NOT to use the canonical bridge

For token issuers

Disclaimer

​Overview

​Ethereum to Whitechain

​Deposits (L1 to L2)

​Withdrawals (L2 to L1)

​Timing parameters

​Programmatic bridging

​Contract addresses

​Testnet

​When NOT to use the canonical bridge

​For token issuers

​Disclaimer

​Related

Overview

Ethereum to Whitechain

Deposits (L1 to L2)

Withdrawals (L2 to L1)

Timing parameters

Programmatic bridging

Contract addresses

Testnet

When NOT to use the canonical bridge

For token issuers

Disclaimer

Related