Add a Custom Bridge to OP Mainnet

This guide explains how to add a custom bridge to OP Mainnet. It points you to useful guides and tutorials for bridge customization and details how to add a custom bridge to the Superchain token list repository (opens in a new tab).

About the Standard Bridge

In the standard bridge when ERC20 is deposited on L1 and transferred to the bridge contract, it remains "locked" there while the equivalent amount is minted in the L2 token. For withdrawals the opposite happens, the L2 token amount is burned then the same amount of L1 tokens is transferred to the recipient. This implementation satisfies a wide range of requirements.

Standard Bridge Considerations

Some of the reasons why the standard bridge might not work for you:

• When you cannot limit the L2 token mint and burn functions to the bridge alone (something we require for security).
• Also certain custom bridges implement their own logic for managing the token supply which requires custom logic.
• Another case might be when you are bridging non-ERC20 tokens for example NFTs.
• Yet another case is when you are pooling deposits for cheaper transfers to L2.

Build a Custom Bridge

This is the option to consider when the OP Mainnet Standard bridge does not satisfy your requirements for bridging assets or data you can deploy your custom bridge solution utilizing the same cross-domain infrastructure as the Standard bridge. Note that when you are building a custom bridge for ERC20 tokens and planning to add these to the Superchain token list, we have specific requirements for the bridge contracts. These have to implement the IL1ERC20Bridge interface in the L1 bridge contract and IL2ERC20Bridge interface in the L2 bridge contract. This ensures the OP Mainnet Bridge UI (opens in a new tab) can support token deposits and withdrawals via this custom bridge.

For details on how cross-domain messaging works, see the Bridging basics guide and also the tutorial on depositing and withdrawing between L1 and L2.

Add Your Custom Bridge to OP Mainnet

To add your bridge and token to the token list, you must make a pull request against the Superchain token list repository (opens in a new tab). Due to the complexity of reviewing a custom bridge, you will need to deploy to OP Goerli first, before going to production.