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

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. It is usable only for L1-origin ERC-20 and ERC-721 tokens (NFTs). Whitechain runs in OP Stack custom gas token mode, where the native token is WBT instead of ETH, and the canonical bridge has no deposit or withdrawal path for the native token in that mode, on Testnet or Mainnet. That means you cannot transfer WBT or ETH using the canonical bridge. 

Please note that there is no UI for the OP Stack canonical bridge. You can make a transfer using the contracts that are mentioned in this article. 

The L1 addresses below are for the testnet (Ethereum Sepolia). The L2 addresses in the 0x4200 range are the same on every OP Stack network, including Whitechain Mainnet.

ContractL1L2
L1StandardBridge0x0c50be539ab5d72d226038928f2eb25100899dedn/a
OptimismPortal0xff9b597b0781457ae6aa7256ca5ed5839bf7d0c3n/a
DisputeGameFactoryProxy0xfaa2faa8912c069c01abc169c33713c79027c833n/a
L1CrossDomainMessengerProxy0x547967f45d19dc4ca0a056ba525afe99bda18a88n/a
L1Erc721BridgeProxy0x1e419fc5575bbd6d352582e9d8073918d79f0c5bn/a
SystemConfigProxy0x9328ea869949f33c57b7b680b6edb58769e2181cn/a
OptimismMintableERC20FactoryProxy0x5898f6c319842a379799d634c6ed2da960a42b9bn/a
AnchorStateRegistryProxy0x4da165963420deeb0788f338b7a1df41e535a32cn/a
EthLockboxProxy0x7becd75f3e1ce952cb63fd7ef5220f205a6e1469n/a
SuperchainConfigProxy0x11854d3146a460d095943c3231f2755ba342426en/a
L2StandardBridgen/a0x4200000000000000000000000000000000000010
L2CrossDomainMessengern/a0x4200000000000000000000000000000000000007
OptimismMintableERC20Factoryn/a0x4200000000000000000000000000000000000012
L2ERC721Bridgen/a0x4200000000000000000000000000000000000014
OptimismMintableERC721Factoryn/a0x4200000000000000000000000000000000000017

The L1 addresses for the Mainnet on Ethereum

ContractEthereum mainnet address
L1StandardBridge (proxy)0x7e954f20f24b7988ea966c4e7880fe6d21dcc2d9
OptimismPortal0x0665f74e013b7fccfda6daf8951baf3c982a3864
DisputeGameFactoryProxy0x1de4f415dc5bf6e458cf32d13452c24a35ec90e3
L1CrossDomainMessengerProxy0x589cd6ded71cf4867351e86507a1ce81bde0bc9c
L1Erc721BridgeProxy0x7b854cba91d3b788bc311e2326e203c0f46db3fe
SystemConfigProxy0x1d761826ad3098d10f6ddfbd143957aaf2b6e50c
OptimismMintableERC20FactoryProxy0x149a093e8fe94610586e068739e929723ac0cd1a
AnchorStateRegistryProxy0x860801a7766859b82b0b572f75a56d4d3903b23a
EthLockboxProxy0xbedfe5233e7a57ef396ba7b4292be32a7782097d
SuperchainConfigProxy0x35ab61ee5d1c2319d1822a7be1b6b3fae98ad886

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. ERC-20 tokens use the L1StandardBridge.depositERC20 function. Please make sure that the token is already deployed on L2. To transfer NFTs, you should use L1Erc721BridgeProxy.bridgeERC721 function. 

When you should NOT 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.

  • 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 offers a faster, centralized transfer;
  • Bridging USDC. Whitechain already has a canonical USDC.e representation; a second wrapped pairing created via the factory would fragment liquidity; 
  • Bridging ETH. Whitechain runs in custom gas token mode, so ETH is not a supported deposit asset;
  • Token has transfer fees or rebasing logic. The standard bridge does not account for balance changes during transfer. In this case, we recommend using a custom bridge designed for your token;
  • Token has a blocklist or pausable transfer. Finalization may revert permanently, leaving funds stuck. You should also use the custom bridge;
  • L2-native NFTs going to L1. The standard L2ERC721Bridge only supports L1-origin NFTs;
  • Very large amounts with time sensitivity. Funds are locked for the entire dispute-resolution period. You can use a third-party bridge.

Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request