standard-bridge Documentation

1. Project Overview & Quickstart (ethereum-optimism/standard-bridge) Copy Chapter

standard-bridge

Open-source repository ethereum-optimism/standard-bridge

Repository Details Copy Section

• Repository: ethereum-optimism/standard-bridge
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (ethereum-optimism/docs) Copy Chapter

File: README.md Copy Chapter

Optimism Docs (Deprecated)

This repository is deprecated. The documentation has moved to the main Optimism monorepo.

New location: github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs

Please open all new issues and pull requests there. This repo is no longer maintained.

This repo previously housed the Optimism Docs located at docs.optimism.io.

License Copy Chapter

This project is licensed under the MIT License.

File: app-developers/guides/bridging/basics.mdx Copy Chapter

title: Bridging basics Copy Chapter

OP Mainnet is a "Layer 2" system and is fundamentally connected to Ethereum.
However, OP Mainnet is also a distinct blockchain with its own blocks and transactions.
App developers commonly need to move data and tokens between OP Mainnet and Ethereum.
This process of moving data and tokens between the two networks is called "bridging".

Sending tokens Copy Chapter

One of the most common use cases for bridging is the need to send ETH or ERC-20 tokens between OP Mainnet and Ethereum.
OP Mainnet has a system called the Standard Bridge that makes it easy to move tokens in both directions.
If you mostly need to bridge tokens, make sure to check out the Standard Bridge guide.

Sending data Copy Chapter

Under the hood, the Standard Bridge is just an application that uses the OP Mainnet message passing system to send arbitrary data between Ethereum and OP Mainnet.
Applications can use this system to have a contract on Ethereum interact with a contract on OP Mainnet, and vice versa.
All of this is easily accessible with a simple, clean API.

Next steps Copy Chapter

Ready to start bridging?
Check out these tutorials to get up to speed fast.

• Learn how to bridge ERC-20 tokens with viem
• Learn how to create a standard bridged token
• Learn how to create a custom bridged token
• Learn how to submit transactions from L1

File: app-developers/guides/bridging/custom-bridge.mdx Copy Chapter

title: Custom bridges Copy Chapter

Custom token bridges are any bridges other than the Standard Bridge.
You may find yourself in a position where you need to build a custom token bridge because the Standard Bridge doesn't completely support your use case.
This guide provides important information you should be aware of when building a custom bridge.

Custom bridges can bring a significant amount of complexity and risk to any project.
Before you commit to a custom bridge, be sure that the Standard Bridge definitely does not support your use case.
Building a custom bridged token is often sufficient for projects that need more flexibility.

Guidelines Copy Chapter

Custom bridges can use any design pattern you can think of.
However, with increased complexity comes increased risk.
Consider directly extending or modifying the StandardBridge contract before building your own bridge contracts from scratch.
Doing so will provide you with an audited foundation upon which you can add extra logic.

If you choose not to extend the StandardBridge contract, you may still want to follow the interface that the StandardBridge provides.
Bridges that extend this interface will be compatible with the Superchain Bridges UI.
You can read more about the design of the Standard Bridge in the guide on Using the Standard Bridge.

The Superchain Token List Copy Chapter

The Superchain Token List exists to help users and developers find the right bridged representations of tokens native to another blockchain.
Once you've built and tested your custom bridge, make sure to register any tokens meant to flow through this bridge by making a pull request against the Superchain Token List repository.
You must deploy your bridge to OP Sepolia before it can be added to the Superchain Token List.

Next steps Copy Chapter

You can explore several examples of custom bridges for OP Mainnet:

• NFT Bridge
• L2 DAI Token Bridge and deployed addresses
• SNX Bridge

File: app-developers/guides/bridging/messaging.mdx Copy Chapter

title: Sending data between L1 and L2 Copy Chapter

Smart contracts on L1 (Ethereum) can interact with smart contracts on L2 (OP Mainnet) through a process called "bridging".
This page explains how bridging works, how to use it, and what to watch out for.

This is a high-level overview of the bridging process.
For a step-by-step tutorial on how to send data between L1 and L2, check out the Solidity tutorial.

Understanding contract calls Copy Chapter

It can be easier to understand bridging if you first have a basic understanding of how contracts on EVM-based blockchains like OP Mainnet and Ethereum communicate within the same network.
The interface for sending messages between Ethereum and OP Mainnet is designed to mimic the standard contract communication interface as much as possible.

Here's how a contract on Ethereum might trigger a function within another contract on Ethereum:

contract MyContract {
    function doTheThing(address myContractAddress, uint256 myFunctionParam) public {
        MyOtherContract(myContractAddress).doSomething(myFunctionParam);
    }
}

Here, MyContract.doTheThing triggers a call to MyOtherContract.doSomething.
Under the hood, Solidity is triggering the code for MyOtherContract by sending an ABI encoded call for the doSomething function.
A lot of this complexity is abstracted away to simplify the developer experience.
Solidity also has manual encoding tools that allow us to demonstrate the same process in a more verbose way.

Here's how you might manually encode the same call:

contract MyContract {
    function doTheThing(address myContractAddress, uint256 myFunctionParam) public {
        myContractAddress.call(
            abi.encodeCall(
                MyOtherContract.doSomething,
                (
                    myFunctionParam
                )
            )
        );
    }
}

Here you're using the low-level "call" function and one of the ABI encoding functions built into Solidity.
Although these two code snippets look a bit different, they're doing the exact same thing.
Because of limitations of Solidity, the OP Stack's bridging interface is designed to look like the second code snippet.

Basics of communication between layers Copy Chapter

At a high level, the process for sending data between L1 and L2 is pretty similar to the process for sending data between two contracts on Ethereum (with a few caveats).
Communication between L1 and L2 is made possible by a pair of special smart contracts called the "messenger" contracts.
Each layer has its own messenger contract, which serves to abstract away some lower-level communication details, a lot like how HTTP libraries abstract away physical network connections.

We won't get into too much detail about these contracts here.
The most important thing that you need to know is that each messenger contract has a sendMessage function that allows you to send a message to a contract on the other layer.

function sendMessage(
    address _target,
    bytes memory _message,
    uint32 _minGasLimit
) public;

The sendMessage function has three parameters:

1. The address _target of the contract to call on the other layer.
2. The bytes memory _message calldata to send to the contract on the other layer.
3. The uint32 _minGasLimit minimum gas limit that can be used when executing the message on the other layer.

This is basically equivalent to:

address(_target).call{gas: _minGasLimit}(_message);

Except, of course, that you're calling a contract on a completely different network.

This is glossing over a lot of the technical details that make this whole thing work under the hood, but this should be enough to get you started.
Want to call a contract on OP Mainnet from a contract on Ethereum?
It's dead simple:

// Pretend this is on L2
contract MyOptimisticContract {
    function doSomething(uint256 myFunctionParam) public {
        // ... some sort of code goes here
    }
}

// And pretend this is on L1
contract MyContract {
    function doTheThing(address myOptimisticContractAddress, uint256 myFunctionParam) public {
        messenger.sendMessage(
            myOptimisticContractAddress,
            abi.encodeCall(
                MyOptimisticContract.doSomething,
                (
                    myFunctionParam
                )
            ),
            1000000 // or use whatever gas limit you want
        )
    }
}

You can find the addresses of the L1CrossDomainMessenger and the L2CrossDomainMessenger contracts on OP Mainnet and OP Sepolia on the Contract Addresses page.

Communication speed Copy Chapter

Unlike calls between contracts on the same blockchain, calls between Ethereum and OP Mainnet are not instantaneous.
The speed of a cross-chain transaction depends on the direction in which the transaction is sent.

For L1 to L2 transactions Copy Section

Transactions sent from L1 to L2 take approximately 1-3 minutes to get from Ethereum to OP Mainnet, or from Sepolia to OP Sepolia.
This is because the Sequencer waits for a certain number of L1 blocks to be created before including L1 to L2 transactions to avoid potentially annoying reorgs.

For L2 to L1 transactions Copy Section

Transactions sent from L2 to L1 take approximately 7 days to get from OP Mainnet to Ethereum, or from OP Sepolia to Sepolia.
This is because the bridge contract on L1 must wait for the L2 state to be proven to the L1 chain before it can relay the message.

The process of sending transactions from L2 to L1 involves four distinct steps:

1. The L2 transaction that sends a message to L1 is sent to the Sequencer.
   This is just like any other L2 transaction and takes just a few seconds to be confirmed by the Sequencer.

2. The block containing the L2 transaction is proposed to the L1.
   This typically takes approximately 20 minutes.

3. A proof of the transaction is submitted to the OptimismPortal contract on L1.
   This can be done any time after step 2 is complete.

4. The transaction is finalized on L1.
   This can only be done after the fault challenge period has elapsed.
   This period is 7 days on Ethereum and a few seconds on Sepolia.
   This waiting period is a core part of the security model of the OP Stack and cannot be circumvented.

Accessing `msg.sender` Copy Chapter

Contracts frequently make use of msg.sender to make decisions based on the calling address.
For example, many contracts will use the Ownable pattern to selectively restrict access to certain functions.
Because messages are essentially shuttled between L1 and L2 by the messenger contracts, the msg.sender you'll see when receiving one of these messages will be the messenger contract corresponding to the layer you're on.

In order to get around this, you can find a xDomainMessageSender function to each messenger:

function xDomainMessageSender() public returns (address);

If your contract has been called by one of the messenger contracts, you can use this function to see who's actually sending this message.
Here's how you might implement an onlyOwner modifier on L2:

modifier onlyOwner() {
    require(
        msg.sender == address(messenger)
        && messenger.xDomainMessageSender() == owner
    );
    _;
}

Fees for sending data between L1 and L2 Copy Chapter

For L1 to L2 transactions Copy Section

The majority of the cost of an L1 to L2 transaction comes from the smart contract execution on L1.
When sending an L1 to L2 transaction, you send to the L1CrossDomainMessenger contract, which then sends a call to the OptimismPortal contract.
This involves some execution on L1, which costs gas.
The total cost is ultimately determined by gas prices on Ethereum when you're sending the cross-chain transaction.

L1 to L2 execution also triggers contract execution on L2.
The OptimismPortal contract charges you for this L2 execution by burning a dynamic amount of L1 gas during your L1 to L2 transaction, depending on the gas limit you requested on L2.
The amount of L1 gas charged increases when more people are sending L1 to L2 transactions (and decreases when fewer people are sending L1 to L2 transactions).

Since the gas amount charged is dynamic, the gas burn can change from block to block.
You should always add a buffer of at least 20% to the gas limit for your L1 to L2 transaction to avoid running out of gas.

For L2 to L1 transactions Copy Section

Each message from L2 to L1 requires three transactions:

1. An L2 transaction that initiates the transaction, which is priced the same as any other transaction made on OP Mainnet.

2. An L1 transaction that proves the transaction.
   This transaction can only be submitted after the L2 block, including your L2 transaction, is proposed on L1.
   This transaction is expensive because it includes verifying a Merkle trie inclusion proof on L1.

3. An L1 transaction that finalizes the transaction.
   This transaction can only be submitted after the transaction challenge period (7 days on mainnet) has passed.

The total cost of an L2 to L1 transaction is therefore the combined cost of the L2 initialization transaction and the two L1 transactions.
The L1 proof and finalization transactions are typically significantly more expensive than the L2 initialization transaction.

Understanding the challenge period Copy Chapter

One of the most important things to understand about L1 ⇔ L2 interaction is that mainnet messages sent from Layer 2 to Layer 1 cannot be relayed for at least 7 days.
This means that any messages you send from Layer 2 will only be received on Layer 1 after this one-week period has elapsed.
We call this period of time the "challenge period" because it is the time during which a transaction can be challenged with a fault proof.

Optimistic Rollups are "optimistic" because they're based around the idea of publishing the result of a transaction to Ethereum without actually executing the transaction on Ethereum.
In the "optimistic" case, this transaction result is correct and one can completely avoid the need to perform complicated (and expensive) logic on Ethereum.

However, one still needs to find a way to prevent incorrect transaction results from being published in place of correct ones.
Here's where the "fault proof" comes into play.
Whenever a transaction result is published, it's considered "pending" for a period of time known as the challenge period.
During this period of time, anyone may re-execute the transaction on Ethereum in an attempt to demonstrate that the published result was incorrect.

If someone can prove that a transaction result is faulty, then the result is scrubbed from existence and anyone can publish another result in its place (hopefully the correct one this time, financial punishments make faulty results very costly for their publishers).
Once the window for a given transaction result has fully passed without a challenge, the result can be considered fully valid (or else someone would've challenged it).

Anyway, the point here is that you don't want to be making decisions about Layer 2 transaction results from inside a smart contract on Layer 1 until this challenge period has elapsed.
Otherwise you might be making decisions based on an invalid transaction result.
As a result, L2 ⇒ L1 messages sent using the standard messenger contracts cannot be relayed until they've waited out the full challenge period.

File: app-developers/guides/bridging/standard-bridge.mdx Copy Chapter

title: Using the Standard Bridge Copy Chapter

The Standard Bridge is a basic token bridging system available on OP Mainnet and all other standard OP Stack chains.
The Standard Bridge allows you to easily move ETH and most ERC-20 tokens between Ethereum and OP Mainnet.
Transfers from Ethereum to OP Mainnet via the Standard Bridge are usually completed within 1-3 minutes.
Transfers from OP Mainnet to Ethereum are completed in 7 days as a result of the withdrawal challenge period.

The Standard Bridge is fully permissionless and supports standard ERC-20 tokens.
Other bridging systems also exist that provide different features and security properties.
You may wish to explore some of these options to find the bridge that works best for you and your application.

The Standard Bridge does not support fee on transfer tokens or rebasing tokens because these types of tokens may cause bridge accounting errors.

Design Copy Chapter

The Standard Bridge allows users to convert tokens that are native to one chain (like Ethereum) into a representation of those tokens on the other chain (like OP Mainnet).
Users can then convert these bridged representations back into their original native tokens at any time.

This bridging mechanism functions identically in both directions — tokens native to OP Mainnet can be bridged to Ethereum, just like tokens native to Ethereum can be bridged to OP Mainnet.
Here you'll get to understand how the Standard Bridge works when moving tokens from Ethereum to OP Mainnet.
Since the bridging mechanism is mirrored on both sides, this will also explain how the bridge works in the opposite direction.

Architecture Copy Section

The Standard Bridge is composed of two contracts, the L1StandardBridge (on Ethereum) and the L2StandardBridge (on OP Mainnet).
These two contracts interact with one another via the CrossDomainMessenger system for sending messages between Ethereum and OP Mainnet.
You can read more about the CrossDomainMessenger in the guide on Sending Data Between L1 and L2.

Bridged tokens Copy Section

The Standard Bridge utilizes bridged representations of tokens that are native to another blockchain.
Before a token native to one chain can be bridged to the other chain, a bridged representation of that token must be created on the receiving side.

A bridged representation of a token is an ERC-20 token that implements the IOptimismMintableERC20 interface.
This interface includes a few functions that the StandardBridge contracts use to manage the bridging process.
All bridged versions of tokens must implement this interface to be used with the StandardBridge.
Native tokens do not need to implement this interface.

A native token may have more than one bridged representation at the same time.
Users must always specify which bridged token they wish to use when using the bridge.
Different bridged representations of the same native token are considered entirely independent tokens.

Bridging native tokens Copy Section

The Standard Bridge uses a "lock-and-mint" mechanism to convert native tokens into their bridged representations.
This means that native tokens are locked into the Standard Bridge on one side, after which bridged tokens are minted on the other side.
The process for bridging a native token involves a few steps.

<Step title="User calls the bridging function">

The user must provide the following parameters to this function call:

*   `address _localToken`: Address of the native token on the sending side.
*   `address _remoteToken`: Address of the bridged representation on the receiving side.
*   `address _to`: Address of the recipient of these tokens, usually the sender's address.
*   `uint256 _amount`: Number of tokens to transfer.
*   `uint32 _minGasLimit`: Gas to use to complete the transfer on the receiving side.
*   `bytes calldata _extraData`: Optional identity extra data.


  Users can also trigger the [`bridgeERC20`](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L168-L191) function instead of `bridgeERC20To` to avoid needing to specify the `address _to` parameter.
  Doing so will automatically set the `address _to` parameter to the `msg.sender`.

  **The `bridgeERC20` function can be potentially dangerous for users with [smart contract wallets](https://web.archive.org/web/20231012141406/https://blockworks.co/news/what-are-smart-contract-wallets) as some smart contract wallets cannot be deployed at the same address on every blockchain.**
  To help users avoid potentially losing access to tokens by accident, the `bridgeERC20` function will always revert when triggered from a smart contract.
  Smart contract wallet users and other smart contracts should therefore use the `bridgeERC20To` function instead.



</Step>

<Step title="The Standard Bridge locks the transferred tokens">

Since a native token may have more than one bridged representation, the `deposits` token must keep track of the deposit pools for each `_localToken`/`_remoteToken` pair independently.

To illustrate, suppose that two users deposit 100 units of the same native token, `Token A`, but wish to receive two different bridged tokens, `Token B` and `Token C`.
Although the Standard Bridge would now have a total balance of 200 units of `Token A`, the mapping would show that the `Token A`/`Token B` pool and the `Token A`/`Token C` pool both have only 100 units.


</Step>

<Step title="The Standard Bridge sends a minting message">

</Step>

<Step title="The minting message is executed">

When the message is relayed, the `finalizeBridgeERC20` function will be triggered on the receiving Standard Bridge contract.
This function will receive the `_minGasLimit` gas defined by the user to execute to completion.


</Step>

<Step title="The minting message is authenticated">

*   [The request must have originated from the Standard Bridge contract on the other blockchain](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L269).
*   [The Standard Bridge must not be in an emergency paused state](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L271).
*   [The bridged token must properly implement the `IOptimismMintableERC20` interface](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L272).
*   [The bridged token must recognize the original native token as its `remoteToken()`](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L273-L276).


</Step>

<Step title="The bridged token is minted">

This completes the process of bridging native tokens.
This process is identical in both the Ethereum to OP Mainnet and OP Mainnet to Ethereum directions.


</Step></Steps>

The user must provide the following parameters to this function call:

*   `address _localToken`: Address of the bridged token on the sending side.
*   `address _remoteToken`: Address of the native token on the receiving side.
*   `address _to`: Address of the recipient of these tokens, usually the sender's address.
*   `uint256 _amount`: Number of tokens to transfer.
*   `uint32 _minGasLimit`: Gas to use to complete the transfer on the receiving side.
*   `bytes calldata _extraData`: Optional identity extra data.

<Step title="The Standard Bridge burns the transferred tokens">

</Step>

<Step title="The Standard Bridge sends an unlock message">

</Step>

<Step title="The unlock message is executed">

When the message is relayed, the `finalizeBridgeERC20` function will be triggered on the receiving Standard Bridge contract.
This function will receive the `_minGasLimit` gas defined by the user to execute to completion.


</Step>

<Step title="The unlock message is authenticated">

*   [The request must have originated from the Standard Bridge contract on the other blockchain](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L269).
*   [The Standard Bridge must not be in an emergency paused state](https://github.com/ethereum-optimism/optimism/blob/2e647210882d961f04055e656590d90ad98c9934/packages/contracts-bedrock/src/universal/StandardBridge.sol#L271).


</Step>

<Step title="The native token is unlocked">

This completes the process of bridging native tokens.
This process is identical in both the Ethereum to OP Mainnet and OP Mainnet to Ethereum directions.


</Step></Steps>

<Step title="Find the bridged representation of the token">

</Step>
    <Step title="Find the bridge contract address used by the token pair">

</Step>
</Steps>

sequenceDiagram
    participant app as Application
    box rgba(0,0,0,0.1) Source Chain
      participant srcContract as Source Contract
      participant srcXdom as L2ToL2CrossDomainMessenger
      participant log as Event Log
    end
    app->>srcContract: 1. Send a message
    srcContract->>srcXdom: 2. Call contract Ain chainId Bwith calldata C
    note over srcXdom: 3. Sanity checks
    srcXdom->>log: 4. Log event SentMessage

sequenceDiagram
    participant app as Autorelayer
    box rgba(0,0,0,0.1) Source Chain
      participant log as Event Log
    end    
    participant super as OP-Supervisor(destination chainnode)
    box rgba(0,0,0,0.1) Destination Chain
      participant dstXdom as L2ToL2CrossDomainMessenger
      participant Xinbox as CrossL2Inbox
      participant dstContract as Destination Contract
    end
    log->>super: 1. Initiating message log event
    app->>dstXdom: 2. Send an executing message
    dstXdom->>Xinbox: 3. Verify the initiating message is real 
    note over dstXdom: 4. Sanity checks
    dstXdom->>dstContract: 5. Call with provided calldata

sequenceDiagram
    participant User
    participant App as Application
    participant EAS as EAS Contract
    participant Log as Event Log
    
    User->>App: Request attestation
    App->>EAS: createAttestation()
    EAS->>Log: Emit AttestationCreated event
    Note over Log: Event contains attestation data

sequenceDiagram
    participant User
    participant DeFi as DeFi Application
    participant Verifier as AttestationVerifier
    participant CrossL2 as CrossL2Inbox
    participant OP as OP-Supervisor Service
    
    User->>DeFi: Request access using attestation
    DeFi->>Verifier: verifyAttestation(id, attestationEvent)
    Verifier->>CrossL2: validateMessage(id, keccak256(attestationEvent))
    CrossL2->>OP: Check if log exists
    OP-->>CrossL2: Confirm log validity
    CrossL2-->>Verifier: Return validation result
    Verifier-->>DeFi: Return verification status
    DeFi-->>User: Grant access based on attestation

flowchart TD
    A[1. Identify log to consume] --> B[2. Create Identifier struct]
    B --> C[3. Call validateMessage]
    C --> D[4. Process validated log data]
    
    subgraph "Conceptual Approach"
    E["Define an Identifier struct with:
       - chainId: The source chain ID
       - origin: The source contract address
       - Other required identifier parameters"]
    
    F["Call validateMessage on CrossL2Inbox
       Pass the identifier and hash of log data"]
    end
    
    B --> E
    C --> F

flowchart LR
    subgraph "L2ToL2CrossDomainMessenger (Push Model)"
        A[Source Contract] -->|sendMessage| B[Source L2ToL2CrossDomainMessenger]
        B -->|emit event| C[Event Log]
        C -.->|relayed by| D[Autorelayer]
        D -->|relayMessage| E[Destination L2ToL2CrossDomainMessenger]
        E -->|execute| F[Destination Contract]
    end
    
    subgraph "CrossL2Inbox (Pull Model)"
        G[Source Contract] -->|emit event| H[Event Log]
        H -.->|monitored by| I[OP-Supervisor]
        J[Destination Contract] -->|validateMessage| K[CrossL2Inbox]
        K <--->|verify log| I
    end