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 within minutes, and withdrawals back to L1 complete after a 7-day challenge window.
An official Whitechain bridge UI is in active development. Today, bridging is performed programmatically against the canonical contracts. This page describes the contracts and flows you need to use them directly.
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.
- ETH call the
depositETH function on the L1StandardBridge with the amount as msg.value.
- ERC20 tokens first
approve the L1StandardBridge to spend your tokens, then call depositERC20 with the L1 token, the matching L2 representation, and the amount. The L2 token must already be deployed (see For token issuers).
- NFTs (ERC721) approve the
L1ERC721Bridge, then call bridgeERC721. Only L1-origin NFTs are supported by the standard bridge.
- Arbitrary messages use
L1CrossDomainMessenger.sendMessage. This has replay support if the L2 transaction runs out of gas. Do not use OptimismPortal2.depositTransaction directly for contract calls, it has no replay.
Withdrawals (L2 to L1)
A withdrawal takes 7 to 14 days because of the mandatory dispute window. The flow has five steps:
- Initiate on L2 call
L2StandardBridge.bridgeETH or bridgeERC20. Tokens are burned (for L1-origin tokens) or escrowed (for L2-native tokens).
- Wait for an output proposal (about 1 hour) the op-proposer publishes an output root on L1 via the
DisputeGameFactory.
- Prove the withdrawal on L1 call
OptimismPortal2.proveWithdrawalTransaction with the dispute game index and a Merkle proof from L2 storage. Tools such as the OP SDK or op-withdrawer compute the proof for you.
- Wait for the challenge window (7 days) the dispute game must resolve in favor of the proposer. If it is successfully challenged, you must re-prove against a different game.
- Finalize on L1 call
OptimismPortal2.finalizeWithdrawalTransaction to release the funds to L1.
Programmatic bridging
Because there is no UI today, applications interact with the bridge contracts directly. Common paths:
- OP SDK the
@eth-optimism/sdk package abstracts deposits, prove, and finalize calls into high-level helpers.
- op-withdrawer the
op-withdrawer CLI handles the prove and finalize steps for L2 to L1 withdrawals.
- Direct contract calls any Ethereum-compatible library (viem, ethers, web3.js) can call the bridge contracts shown in Contract addresses.
Contract addresses
Contract addresses are organized by network. Testnet and mainnet addresses will be added as those networks become available.
Testnet
| Contract | L1 | L2 |
|---|
L1StandardBridge | TBD | n/a |
OptimismPortal | TBD | n/a |
DisputeGameFactoryProxy | TBD | n/a |
L2StandardBridge | n/a | TBD |
OptimismMintableERC20Factory | n/a | TBD |
Mainnet
| Contract | L1 | L2 |
|---|
L1StandardBridge | TBD | n/a |
OptimismPortal | TBD | n/a |
DisputeGameFactoryProxy | TBD | n/a |
L2StandardBridge | n/a | TBD |
OptimismMintableERC20Factory | n/a | TBD |
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 in under 7 days | The 7-day challenge window is mandatory and cannot be skipped | A third-party liquidity bridge (for example Across) once integrated |
| 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 challenge window | 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.
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.
