# Use the Docs with AI
Source: https://docs.optimism.io/ai-docs

Read the Optimism docs as an agent with llms.txt and per-page markdown, connect the hosted MCP server, and start from curated prompts.

These docs are built to be read by AI assistants and agents, not just browsers.
Every page is available as plain markdown, the whole site publishes a machine-readable index, and a hosted MCP server exposes search over the content.
This page covers the three ways to put them to work: [reading the docs as an agent](#read-the-docs-as-an-agent), [connecting the hosted MCP server](#connect-the-hosted-mcp-server), and [starting from curated prompts](#prompt-starters).

## Read the Docs as an Agent

### The Documentation Index: llms.txt

The site publishes an [llms.txt](https://llmstxt.org/) index at:

```text theme={null}
https://docs.optimism.io/llms.txt
```

It is a plain-markdown listing of the site's pages with their URLs.
Point an assistant at it to discover what exists before fetching individual pages.
This is the recommended entry point for any agent working with these docs.

### Per-Page Markdown

Every page is served as raw markdown at its own URL with `.md` appended.
For example, the [Node Operator Overview](/node-operators/overview) page is available as:

```text theme={null}
https://docs.optimism.io/node-operators/overview.md
```

Fetching the `.md` form skips the HTML shell, navigation, and scripts, so an assistant gets exactly the content of the page in a fraction of the tokens.
Prefer it over the HTML URL whenever your tooling fetches pages programmatically.

### The Contextual Menu

Every page in these docs has a contextual menu (next to the page title) with assistant-ready actions:

* **Copy page**: copies the page as markdown, ready to paste into any chat.
* **Open in ChatGPT**: opens a ChatGPT conversation preloaded with the page.
* **Open in Claude**: opens a Claude conversation preloaded with the page.
* **Copy MCP server URL**: copies the [hosted MCP server](#connect-the-hosted-mcp-server) address for your client configuration.

Use it when you are reading a page and want to hand it to an assistant without constructing URLs by hand.

### Tips for Agents Reading These Docs

* Start from `llms.txt` to map the site, then fetch only the `.md` pages you need.
* These docs describe how to *use* the OP Stack. The normative protocol definition lives in the [OP Stack specifications](https://specs.optimism.io) - when a docs page and the specs disagree, the specs win.
* Configuration flags and versions change between releases. Confirm load-bearing values against the linked source or release notes before acting on them.

## Connect the Hosted MCP Server

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) is an open standard for connecting AI assistants to external tools and data sources.
These docs are hosted on Mintlify, which [automatically generates and hosts an MCP server](https://www.mintlify.com/docs/ai/model-context-protocol) for the site.
The server exposes a search tool over the documentation, so a connected assistant (Claude Code, Claude Desktop, Cursor, and others) can look up current OP Stack content instead of relying on stale training data.

### Option 1: The Hosted MCP Server (Recommended)

The docs MCP server is available over HTTP at:

```text theme={null}
https://docs.optimism.io/mcp
```

<Steps>
  <Step title="Add the server to your client">
    For Claude Code, run:

    ```bash theme={null}
    claude mcp add --transport http optimism-docs https://docs.optimism.io/mcp
    ```

    For Cursor, Claude Desktop, and other clients that use a JSON configuration, add the server URL:

    ```json theme={null}
    {
      "mcpServers": {
        "optimism-docs": {
          "url": "https://docs.optimism.io/mcp"
        }
      }
    }
    ```

    You can also connect from any page of these docs: the contextual menu (next to the page title) includes an option to copy the MCP server details for your client.
  </Step>

  <Step title="Verify it works">
    Ask your assistant:

    ```text theme={null}
    Using the optimism-docs MCP server, find the page about running a node
    from source and summarize its hardware requirements.
    ```

    A correctly wired assistant calls the server's search tool, locates [Building and Running an OP Stack Node From Source](/node-operators/tutorials/run-node-from-source), and answers from the live page.
  </Step>
</Steps>

### Option 2: Direct Fetching (No MCP Server Required)

If your assistant can fetch web pages but does not support MCP, no setup is needed.
The site's [machine-readable surfaces](#read-the-docs-as-an-agent) - the `llms.txt` index and per-page markdown - work with any assistant that can fetch URLs.
Give it the index and the URL convention:

```text theme={null}
The Optimism docs publish a machine-readable index at
https://docs.optimism.io/llms.txt. Any page is available as raw
markdown by appending .md to its URL. Use the index to find relevant
pages, then fetch their .md versions.
```

Add that to your assistant's project instructions (for example `CLAUDE.md`, `.cursorrules`, or a system prompt) and it will resolve OP Stack questions against the live docs.

If your tooling only reaches the network through MCP and cannot use the hosted server, the reference [fetch server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) (`uvx mcp-server-fetch`) plus the instruction block above achieves the same result.

If the hosted MCP endpoint is not responding, [open an issue](https://github.com/ethereum-optimism/optimism/issues) so we can investigate.

## Prompt Starters

Copy-paste prompts for common OP Stack tasks, ready for any AI assistant that can fetch URLs.
Each prompt names its intended persona, grounds the assistant in specific docs pages (fetched as [per-page markdown](#per-page-markdown)), and tells it what to produce.
Replace the bracketed placeholders with your own details before sending.

If your assistant cannot fetch URLs, open the linked pages and use the contextual menu's **Copy page** action to paste them in instead.

### Audit My Batcher Configuration for Cost

**Persona:** chain operator

Data availability is usually a chain's largest onchain operating cost, and the batcher configuration controls it.
Grounding pages: [Configure the Batcher](/chain-operators/guides/configuration/batcher) and [Transaction Fees 101](/chain-operators/guides/management/transaction-fees-101).

```text theme={null}
Read https://docs.optimism.io/chain-operators/guides/configuration/batcher.md
and https://docs.optimism.io/chain-operators/guides/management/transaction-fees-101.md

Here is my current op-batcher configuration: [paste your flags or env vars].
My chain posts roughly [N] transactions per day and targets [blobs / calldata].

Audit the configuration for data-availability cost: identify settings that
increase posting cost, explain the trade-off each one controls (cost vs.
latency vs. safety), and propose a revised configuration with reasoning.
Flag any flag you are not sure still exists so I can check it against
op-batcher --help for my release.
```

### Walk Me Through the Deposit Flow

**Persona:** app developer

Understand what actually happens between an L1 deposit call and the transaction appearing on L2 before you build on it.
Grounding pages: [Deposit Flow](/op-stack/bridging/deposit-flow) and [Deposit Transactions](/app-developers/tutorials/bridging/deposit-transactions).

```text theme={null}
Read https://docs.optimism.io/op-stack/bridging/deposit-flow.md and
https://docs.optimism.io/app-developers/tutorials/bridging/deposit-transactions.md

Walk me through the full lifecycle of a deposit from L1 to L2: which
contract I call, what events are emitted, how the L2 transaction is
derived, and what latency and failure modes to expect. Then show me the
minimal code to trigger a deposit from my app. I am building
[describe your app].
```

### Plan a Fault-Proof Challenger Deployment

**Persona:** chain operator

Every permissionless fault-proof chain needs an honest challenger watching its dispute games.
Grounding pages: [OP-Challenger Explainer](/op-stack/fault-proofs/challenger) and [How to Configure Challenger for Your Chain](/chain-operators/guides/configuration/op-challenger-config-guide).

```text theme={null}
Read https://docs.optimism.io/op-stack/fault-proofs/challenger.md and
https://docs.optimism.io/chain-operators/guides/configuration/op-challenger-config-guide.md

I operate an OP Stack chain with fault proofs enabled on [network].
Produce a deployment plan for op-challenger: the role it plays, the
resources and keys it needs, the bond funding it requires, the
configuration I must set, and the monitoring I should attach. List open
questions I need to answer about my own chain before deploying.
```

### Bridge ETH From L1 in My App

**Persona:** app developer

Move ETH between Ethereum and an OP Stack chain programmatically.
Grounding page: [Submitting Transactions From L1](/app-developers/tutorials/bridging/cross-dom-bridge-eth).

```text theme={null}
Read https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-bridge-eth.md

Using the approach in this tutorial, write the code for my app to bridge
ETH from [L1 network] to [L2 network] and report deposit status to the
user. My stack is [TypeScript framework / environment]. Point out where
testnet and mainnet configuration differ, and what the user experience
should show while the deposit is in flight.
```

### Explain My Transaction's Fee Breakdown

**Persona:** app developer

OP Stack transactions pay an execution fee and a data-availability fee; estimating only one of them causes bugs.
Grounding page: [Transaction Fees on OP Mainnet](/op-stack/transactions/fees).

```text theme={null}
Read https://docs.optimism.io/op-stack/transactions/fees.md

Explain every component of the fee my transaction pays on an OP Stack
chain, how each is calculated, and which ones fluctuate with L1 gas
prices. Then show me how to estimate the total fee for a transaction
correctly in my app, and the common estimation mistakes to avoid.
Here is my current estimation code: [paste code, optional].
```

### Debug a Stuck Withdrawal

**Persona:** app developer

Withdrawals are multi-step and time-delayed by design; most "stuck" withdrawals are actually mid-flight.
Grounding pages: [Withdrawal Flow](/op-stack/bridging/withdrawal-flow) and [Transaction Finality](/op-stack/transactions/transaction-finality).

```text theme={null}
Read https://docs.optimism.io/op-stack/bridging/withdrawal-flow.md and
https://docs.optimism.io/op-stack/transactions/transaction-finality.md

A withdrawal from [L2 network] appears stuck: [describe what you did,
when, and the transaction hash or current status]. Using the withdrawal
lifecycle in these docs, determine which stage the withdrawal is in,
whether the delay is expected protocol behavior or an actual problem,
and exactly what action (if any) unblocks the next step.
```

## Contributing

The prompts above are curated: each one maps to a task readers actually arrive with, and each grounds the assistant in maintained docs pages.
To propose a new prompt or fix a stale one, [open an issue](https://github.com/ethereum-optimism/optimism/issues) or edit this page.


# Bridging basics
Source: https://docs.optimism.io/app-developers/guides/bridging/basics

Learn about the fundamentals of sending data and tokens between Ethereum and OP Mainnet.

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

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](./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](./standard-bridge) guide.

## Sending data

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](./messaging).
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

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

* [Learn how to bridge ERC-20 tokens with viem](/app-developers/tutorials/bridging/cross-dom-bridge-erc20)
* [Learn how to create a standard or custom bridged token](/app-developers/tutorials/bridging/standard-bridge-standard-token)
* [Learn how to submit transactions from L1](/app-developers/tutorials/bridging/cross-dom-bridge-eth)


# Custom bridges
Source: https://docs.optimism.io/app-developers/guides/bridging/custom-bridge

Important considerations when building custom bridges for OP Mainnet.

Custom token bridges are any bridges other than the [Standard Bridge](./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.

<Info>
  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](./standard-bridge) definitely does not support your use case.
  [Building a custom bridged token](/app-developers/tutorials/bridging/standard-bridge-standard-token) is often sufficient for projects that need more flexibility.
</Info>

## Guidelines

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`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol) 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](https://app.optimism.io/bridge?utm_source=op-docs\&utm_medium=docs).
You can read more about the design of the Standard Bridge in the guide on [Using the Standard Bridge](./standard-bridge).

## The Superchain Token List

The [Superchain Token List](/app-developers/reference/tokens/tokenlist) 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](https://github.com/ethereum-optimism/ethereum-optimism.github.io#adding-a-token-to-the-list).
You **must** deploy your bridge to OP Sepolia before it can be added to the Superchain Token List.

## Next steps

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

* [NFT Bridge](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1ERC721Bridge.sol)
* [L2 DAI Token Bridge](https://optimistic.etherscan.io/address/0x467194771dae2967aef3ecbedd3bf9a310c76c65#code) and [deployed addresses](https://github.com/ethereum-optimism/ethereum-optimism.github.io/blob/master/data/DAI/data.json)
* [SNX Bridge](https://github.com/ethereum-optimism/ethereum-optimism.github.io/blob/master/data/SNX/data.json)


# Sending data between L1 and L2
Source: https://docs.optimism.io/app-developers/guides/bridging/messaging

Understand how bridging between L1 and L2 works, the messenger contracts that carry messages, what messages cost, and why the challenge period exists.

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: the messenger contracts that carry messages between layers, how long delivery takes in each direction, what messages cost, and why messages from L2 to L1 must wait out a challenge period.

<Info>
  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](/app-developers/tutorials/bridging/cross-dom-solidity).
</Info>

## Understanding contract calls

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:

```solidity theme={null}
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](https://docs.soliditylang.org/en/v0.8.23/abi-spec.html) 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:

```solidity theme={null}
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](https://docs.soliditylang.org/en/v0.8.23/units-and-global-variables.html#members-of-address-types) and one of the [ABI encoding functions built into Solidity](https://docs.soliditylang.org/en/v0.8.23/units-and-global-variables.html#abi-encoding-and-decoding-functions).
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

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.

```solidity theme={null}
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:

```solidity theme={null}
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:

```solidity theme={null}
// 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
        )
    }
}
```

<Info>
  You can find the addresses of the `L1CrossDomainMessenger` and the `L2CrossDomainMessenger` contracts on OP Mainnet and OP Sepolia on the [Contract Addresses](/op-mainnet/network-information/op-addresses) page.
</Info>

## Communication speed

Unlike calls between contracts on the same blockchain, calls between Ethereum and OP Mainnet are *not* instantaneous.
Transactions sent from L1 to L2 take **approximately 1-3 minutes**, 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](https://www.alchemy.com/overviews/what-is-a-reorg).
Transactions sent from L2 to L1 take **approximately 7 days**: the message must be initiated on L2, proven on L1 against an output root, and finalized on L1 only after the [challenge period](#understanding-the-challenge-period) (7 days on mainnet, shorter on test networks) has elapsed.
This waiting period is a core part of the security model of the OP Stack and cannot be circumvented.
For the step-by-step mechanics in each direction, see [Deposit flow](/op-stack/bridging/deposit-flow) and [Withdrawal flow](/op-stack/bridging/withdrawal-flow).

## Accessing `msg.sender`

Contracts frequently make use of `msg.sender` to make decisions based on the calling address.
For example, many contracts will use the [Ownable](https://github.com/OpenZeppelin/openzeppelin-contracts/blob/master/contracts/access/Ownable.sol) 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:

```solidity theme={null}
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:

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

## Fees for sending data between L1 and L2

### For L1 to L2 transactions

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`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol) contract, which then sends a call to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol) 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).

<Info>
  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.
</Info>

### For L2 to L1 transactions

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](/connect/resources/glossary#merkle-patricia-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

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 period of time is called the "challenge period" because it is the window during which a published transaction result can be challenged with a [fault proof](/op-stack/protocol/overview#fault-proofs): Optimistic Rollups publish transaction *results* to Ethereum without executing the transactions there, so L1 contracts must give challengers time to prove a published result faulty before acting on it.
The practical consequence for app developers 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**, and L2 ⇒ L1 messages sent using the standard messenger contracts cannot be relayed until they've waited out the full challenge period.
For how the challenge period fits into the withdrawal process, see [Withdrawal flow](/op-stack/bridging/withdrawal-flow); for why it exists, see the [fault proofs overview](/op-stack/protocol/overview#fault-proofs).


# Using the Standard Bridge
Source: https://docs.optimism.io/app-developers/guides/bridging/standard-bridge

Learn how the Standard Bridge moves ETH and ERC-20 tokens between Layer 1 and Layer 2.

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](./messaging#understanding-the-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.

<Info>
  The Standard Bridge **does not** support [**fee on transfer tokens**](https://github.com/d-xo/weird-erc20#fee-on-transfer) or [**rebasing tokens**](https://github.com/d-xo/weird-erc20#balance-modifications-outside-of-transfers-rebasingairdrops) because they can cause bridge accounting errors.
</Info>

## Design

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

The Standard Bridge is composed of two contracts, the [`L1StandardBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1StandardBridge.sol) (on `Ethereum`) and the [`L2StandardBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2StandardBridge.sol) (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](./messaging).

### Bridged tokens

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`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/universal/IOptimismMintableERC20.sol#L10-L18) 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

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.

<Steps>
  <Step title="User gives the Standard Bridge an allowance">
    The Standard Bridge must be able to pull tokens from the user to lock them into the bridge contract.
    To do this, the user must first give the bridge an [allowance](https://eips.ethereum.org/EIPS/eip-20#approve) to transfer the number of tokens that the user wishes to convert into a bridged representation.
  </Step>

  <Step title="User calls the bridging function">
    After providing a sufficient allowance, the user calls the [`bridgeERC20To`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L217-L229) function on the `StandardBridge` contract on the chain where the native token lives (e.g., the `L1StandardBridge` contract if the token is native to Ethereum).

    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.

    <Info>
      Users can also trigger the [`bridgeERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L194-L206) 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.
    </Info>
  </Step>

  <Step title="The Standard Bridge locks the transferred tokens">
    When the user triggers the `bridgeERC20To` function while transferring a native token, the Standard Bridge will pull the `_amount` of `_localToken` tokens from the user's address and lock them inside of the bridge contract.
    A record of all locked tokens is stored within a [`deposits` mapping](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L41) that keeps track of the total number of tokens deposited for a given `_localToken` and `_remoteToken` pair.

    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">
    After locking the native tokens, the Standard Bridge contract on the sending side will trigger a cross-chain message to the Standard Bridge contract on the receiving side via the [`CrossDomainMessenger`](./messaging) system.
    This message tells the receiving side to **mint** tokens according to the parameters specified by the user.
    Specifically, this message is an encoded call to the [`finalizeBridgeERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L272-L299) function on the other Standard Bridge contract.
    At this point, execution ends on the sending side.
  </Step>

  <Step title="The minting message is executed">
    Once the minting message is sent, it must be relayed to the receiving side.
    Message relaying is automatic when sending from Ethereum to OP Mainnet but requires additional user transactions when sending from OP Mainnet to Ethereum.
    Read more about the message relaying process in the guide to [Sending Data Between L1 and L2](./messaging#communication-speed).

    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">
    Upon execution, `finalizeBridgeERC20` verifies a number of things about the incoming request:

    * [The request must have originated from the Standard Bridge contract on the other blockchain](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L281).
    * [The Standard Bridge must not be in an emergency paused state](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L283).
    * [The bridged token must properly implement the `IOptimismMintableERC20` interface](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L284).
    * [The bridged token must recognize the original native token as its `remoteToken()`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L285-L288).
  </Step>

  <Step title="The bridged token is minted">
    If the minting message is fully verified, `finalizeBridgeERC20` will [mint tokens to the recipient](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L290) equal to the number of tokens originally deposited on the other blockchain.
    For this to work properly, the bridged representation of the native token must correctly implement a `mint` function that allows the Standard Bridge to mint tokens arbitrarily.
    This is part of the [`IOptimismMintableERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/universal/IOptimismMintableERC20.sol) interface.

    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>

### Bridging non-native tokens

The Standard Bridge uses a "burn-and-unlock" mechanism to convert bridged representations of tokens back into their native tokens.
This means that **bridged tokens are burned** on the Standard Bridge on one side, after which **native tokens are unlocked** on the other side.
The process for bridging a non-native, bridged representation of a token involves a few steps.

<Steps>
  <Step title="User calls the bridging function">
    Unlike when bridging native tokens, users do not need to provide an approval to trigger a transfer of a bridged token because the Standard Bridge should already have the ability to `burn` these tokens.
    Here, the user calls the [`bridgeERC20To`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L217-L229) function on the `StandardBridge` contract on the chain where the bridged token lives (e.g., the `L2StandardBridge` contract if the token is bridged to OP Mainnet).

    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>

  <Step title="The Standard Bridge burns the transferred tokens">
    When the user triggers the `bridgeERC20To` function while transferring a bridge token, [the Standard Bridge will burn the corresponding `_amount` of tokens from the sender's address](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L359).
  </Step>

  <Step title="The Standard Bridge sends an unlock message">
    After burning the bridged tokens, the Standard Bridge contract on the sending side will trigger a cross-chain message to the Standard Bridge contract on the receiving side via the [`CrossDomainMessenger`](./messaging) system.
    This message tells the receiving side to **unlock** tokens according to the parameters specified by the user.
    Specifically, this message is an encoded call to the [`finalizeBridgeERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L272-L299) function on the other Standard Bridge contract.
    At this point, execution ends on the sending side.
  </Step>

  <Step title="The unlock message is executed">
    Once the unlock message is sent, it must be relayed to the receiving side.
    Message relaying is automatic when sending from Ethereum to OP Mainnet but requires additional user transactions when sending from OP Mainnet to Ethereum.
    Read more about the message relaying process in the guide to [Sending Data Between L1 and L2](./messaging#communication-speed).

    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">
    Upon execution, `finalizeBridgeERC20` verifies a number of things about the incoming request:

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

  <Step title="The native token is unlocked">
    If the unlock message is fully verified, `finalizeBridgeERC20` will [unlock and transfer tokens to the recipient](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L292-L293) equal to the number of tokens originally burned on the other blockchain.

    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>

### Bridging ETH

The Standard Bridge contracts can also be used to bridge ETH from Ethereum to OP Mainnet and vice versa.
The ETH bridging process is generally less complex than the ERC-20 bridging process.
Users simply need to trigger and send ETH to the [`bridgeETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L166-L168) or [`bridgeETHTo`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol#L182-L184) functions on either blockchain.

<Info>
  Users can also deposit ETH from Ethereum to OP Mainnet by sending a basic ETH transfer from an EOA to the `L1StandardBridgeProxy`.
  This works because the `L1StandardBridgeProxy` contains a [`receive`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1StandardBridge.sol#L134-L136) function.
  You can find the mainnet and testnet addresses on the [Contract Addresses](/op-mainnet/network-information/op-addresses) page.
</Info>

## Tutorials

* [Learn how to bridge ERC-20 tokens with viem](/app-developers/tutorials/bridging/cross-dom-bridge-erc20)
* [Learn how to create a standard or custom bridged token](/app-developers/tutorials/bridging/standard-bridge-standard-token)
* [Learn how to submit transactions from L1](/app-developers/tutorials/bridging/cross-dom-bridge-eth)

## Superchain Token List

The [Superchain Token List](/app-developers/reference/tokens/tokenlist) exists to help users discover the right bridged token addresses for any given native token.
Because a native token may have more than one bridged representation, and different bridged representations are entirely independent tokens, using the wrong one can lock up your native tokens permanently.
Follow the guide on [verifying bridged token addresses](/app-developers/guides/bridging/verify-bridged-tokens) to confirm that you're using the correct bridged representation of a token before bridging.

Developers who are creating their own bridged tokens should consider [adding their token](https://github.com/ethereum-optimism/ethereum-optimism.github.io#adding-a-token-to-the-list) to the Superchain Token List.
Tokens on the Superchain Token List will automatically appear on certain tools like the [Superchain Bridges UI](https://app.optimism.io/bridge?utm_source=op-docs\&utm_medium=docs).


# Verifying bridged token addresses
Source: https://docs.optimism.io/app-developers/guides/bridging/verify-bridged-tokens

Use the Superchain Token List to find and verify the correct bridged representation of a token before using the Standard Bridge.

A native token may have more than one bridged representation on the other chain, and different bridged representations of the same native token are entirely independent tokens.
Bridging to the wrong representation can lock up your native tokens permanently.
This guide shows you how to use the [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io) to find and verify the correct bridged token address before you bridge a token with the [Standard Bridge](/app-developers/guides/bridging/standard-bridge).

## Find the bridged representation of a token for OP Mainnet

You can easily find the bridged representation of a token for OP Mainnet on the [Bridged token addresses](/app-developers/reference/tokens/tokenlist) page.
That page is generated automatically from the Superchain Token List.

## Find the bridged representation of a token for another chain

If you want to find the bridged representation of a token for another chain, use the following steps.

<Steps>
  <Step title="Find the token you want to bridge">
    The Superchain Token List is organized by the token's address and native blockchain.
    [Search the token list](https://github.com/ethereum-optimism/ethereum-optimism.github.io/blob/master/optimism.tokenlist.json) for the token you want to bridge to confirm that it's included in the list.
    Make sure that the chain ID in the entry matches the chain ID of the blockchain you're bridging from.
    Retrieve the token's name and symbol from the list.
  </Step>

  <Step title="Find the bridged representation of the token">
    Once you've found the token you want to bridge, look for the token's name and symbol in the list.
    Find the entry that matches the name and symbol of the token you want to bridge and where the chain ID matches the chain ID of the blockchain you're bridging to.
    The address of this entry is the address of the bridged representation of the token you want to bridge.
  </Step>

  <Step title="Find the bridge contract address used by the token pair">
    Identify the cross-chain bridge contract address used by the token pair.
    You can observe that some token pairs in the list utilize **custom bridge contracts** instead of the default Standard Bridge.
    Verify the bridge contract specified in the token list entry to ensure you are interacting with the correct bridge implementation for that token.
  </Step>
</Steps>

## Add a token to the Superchain Token List

Developers who are creating their own bridged tokens should consider [adding their token](https://github.com/ethereum-optimism/ethereum-optimism.github.io#adding-a-token-to-the-list) to the Superchain Token List.
Tokens on the Superchain Token List will automatically appear on certain tools like the [Superchain Bridges UI](https://app.optimism.io/bridge?utm_source=op-docs\&utm_medium=docs).

## Next steps

* Learn how the [Standard Bridge](/app-developers/guides/bridging/standard-bridge) moves tokens between Ethereum and OP Mainnet.
* Follow the tutorial to [bridge ERC-20 tokens with viem](/app-developers/tutorials/bridging/cross-dom-bridge-erc20).


# Building apps on OP Stack chains
Source: https://docs.optimism.io/app-developers/guides/building-apps

Learn the basics of building apps on OP Stack chains.

This guide explains the basics of OP Stack development.
OP Stack chains are [EVM equivalent](https://web.archive.org/web/20231127160757/https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306), meaning they run a slightly modified version of the same `geth` you run on mainnet.
Therefore, the differences between OP Stack development and Ethereum development are minor.
But a few differences [do exist](/op-stack/protocol/differences).

## OP Stack chains endpoint URLs

To access any Ethereum type network you need an endpoint. [These providers](/app-developers/reference/rpc-providers) support our networks.

### Network choice

For development purposes we recommend you use either a local development network or [OP Sepolia](https://sepolia-optimism.etherscan.io).
That way you don't need to spend real money.
If you need ETH on OP Sepolia for testing purposes, [you can use this faucet](https://console.optimism.io/faucet?utm_source=op-docs\&utm_medium=docs).

## Interacting with contracts on OP Stack chains

We have Hardhat's Greeter contract on OP Sepolia at address [0x9d334aFBa83865E67a9219830ADA57aaA9406681](https://testnet-explorer.optimism.io/address/0x9d334aFBa83865E67a9219830ADA57aaA9406681#code).
You can verify your development stack configuration by interacting with it.

## Development stacks

As you can see in the different development stacks below, the way you deploy contracts and interact with them on OP Stack chains is almost identical to the way you do it with L1 Ethereum.
The most visible difference is that you have to specify a different endpoint (of course).
For more detail, see the guide on [Differences between Ethereum and OP Stack Chains](/op-stack/protocol/differences).

* [Foundry](https://getfoundry.sh/)
* [Hardhat](https://hardhat.org/)
* [Apeworx](https://www.apeworx.io/)
* [Brownie](https://eth-brownie.readthedocs.io/en/stable/install.html)
* [Remix](https://remix.ethereum.org)
* [Waffle](https://getwaffle.io/)

## Best practices

### Use provided EVM

It is best to start development with the EVM provided by the development stack.
Not only is it faster, but such EVMs often have extra features, such as the [ability to log messages from Solidity](https://hardhat.org/tutorial/debugging-with-hardhat-network.html) or a [graphical user interface](https://trufflesuite.com/ganache/).

### Debug before deploying

After you are done with that development, debug your decentralized application locally and then on a [Sepolia test network](/op-mainnet/network-information/connecting-to-op).
This lets you debug parts that are OP Stack chains specific such as calls to bridges to transfer ETH or tokens between layers.

Only when you have a version that works well on a test network should you deploy to the production network, where every transaction has a cost.

<Info>
  **Running your app in production**

  A production application depends on infrastructure your team does not run: RPC endpoints that hold up under real traffic (the public endpoints are rate-limited and not built for production), bridges your users rely on, and a chain whose operator keeps sequencing, upgrades, and incident response going around the clock. These docs cover building and testing. If your application is growing toward dedicated blockspace of its own, [OP Enterprise](https://optimism.io/op-enterprise?utm_source=docs\&utm_medium=docs\&utm_campaign=op-enterprise) offers managed and supported paths to running a chain. These docs stay the reference for what you build either way. OP Enterprise is Optimism's managed offering.
</Info>

### Contract source verification

You don't have to upload your source code to [block explorers](/app-developers/tools/infrastructure/block-explorers), but it is a good idea.
On the test network, it lets you issue queries and transactions from the explorer's user interface.
On the production network, it lets users know exactly what your contract does, which is conducive to trust.

Just remember, if you use [the Etherscan API](https://explorer.optimism.io/apis?utm_source=op-docs\&utm_medium=docs), you need one API key for OP Stack chains and a separate one for OP Sepolia.


# Configuring Actions SDK
Source: https://docs.optimism.io/app-developers/guides/configuring-actions

Learn how to configure Actions SDK for your application.

Actions SDK lets you choose which assets, markets, chains, protocols, and providers you want to support in your application via configuration file.

<Steps>
  <Step title="Install Actions SDK">
    Follow the
    [quickstart](/app-developers/quickstarts/actions) guide to
    add Actions SDK as a dependency in your app.
  </Step>

  <Step title="Integrate an embedded wallet">
    Follow the [connecting a wallet to Actions
    SDK](/app-developers/guides/connect-wallet-to-actions) guide, choose and
    install a Wallet Provider.
  </Step>

  <Step title="Create a config file">
    `actions.ts` - An accessible file that holds all of your configuration preference.
  </Step>

  <Step title="Configure a Wallet Provider">
    Let Actions SDK know which Wallet Provider you've chosen:

    <Tabs>
      <Tab title="Frontend">
        Select a wallet provider:

        <Tabs>
          <Tab title="Privy">
            ```typescript title="actions.ts" theme={null}
            const walletConfig = {
              hostedWalletConfig: {
                provider: {
                  type: "privy" as const,
                },
              },
              smartWalletConfig: {
                provider: {
                  type: "default" as const,
                  attributionSuffix: "actions",
                },
              },
            };
            ```
          </Tab>

          <Tab title="Turnkey">
            ```typescript title="actions.ts" theme={null}
            const walletConfig = {
              hostedWalletConfig: {
                provider: {
                  type: "turnkey" as const,
                },
              },
              smartWalletConfig: {
                provider: {
                  type: "default" as const,
                  attributionSuffix: "actions",
                },
              },
            };
            ```
          </Tab>

          <Tab title="Dynamic">
            ```typescript title="actions.ts" theme={null}
            const walletConfig = {
              hostedWalletConfig: {
                provider: {
                  type: "dynamic" as const,
                },
              },
              smartWalletConfig: {
                provider: {
                  type: "default" as const,
                  attributionSuffix: "actions",
                },
              },
            };
            ```
          </Tab>
        </Tabs>
      </Tab>

      <Tab title="Backend">
        Select a wallet provider:

        <Tabs>
          <Tab title="Privy">
            ```typescript title="actions.ts" theme={null}
            import { PrivyClient } from '@privy-io/node'

            const privyClient = new PrivyClient(
              process.env.PRIVY_APP_ID,
              process.env.PRIVY_APP_SECRET,
            )

            const walletConfig = {
              hostedWalletConfig: {
                provider: {
                  type: "privy" as const,
                  config: {
                    privyClient,
                  },
                },
              },
              smartWalletConfig: {
                provider: {
                  type: "default" as const,
                  attributionSuffix: "actions",
                },
              },
            };
            ```
          </Tab>

          <Tab title="Turnkey">
            ```typescript title="actions.ts" theme={null}
            import { Turnkey } from '@turnkey/sdk-server'

            const turnkeyClient = new Turnkey({
              apiBaseUrl: 'https://api.turnkey.com',
              apiPublicKey: process.env.TURNKEY_API_KEY,
              apiPrivateKey: process.env.TURNKEY_API_SECRET,
              defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
            })

            const walletConfig = {
              hostedWalletConfig: {
                provider: {
                  type: "turnkey" as const,
                  config: {
                    client: turnkeyClient.apiClient(),
                  },
                },
              },
              smartWalletConfig: {
                provider: {
                  type: "default" as const,
                  attributionSuffix: "actions",
                },
              },
            };
            ```
          </Tab>
        </Tabs>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure supported assets">
    Configure which assets you want to support across all lend providers:

    ```typescript title="actions.ts" theme={null}
    // Additional config from previous steps...

    // Import popular assets
    import { USDC } from '@eth-optimism/actions-sdk/assets'
    import type { Asset, AssetsConfig } from "@eth-optimism/actions-sdk";

    // Or define custom assets
    export const CustomToken: Asset = {
      address: {
        [mainnet.id]: '0x123...',
        [unichain.id]: '0x456...',
        [baseSepolia.id]: '0x789...',
      },
      metadata: {
        decimals: 6,
        name: 'Custom Token',
        symbol: 'CUSTOM',
      },
      type: 'erc20',
    }

    // Configure allowed/blocked assets
    const assetsConfig: AssetsConfig = {
      allow: [USDC, CustomToken],
      block: [],  // Optional
    }
    ```
  </Step>

  <Step title="Configure Markets">
    Define which markets you want to support or block within your app:

    ```typescript title="actions.ts" theme={null}
    // Additional config from previous steps...

    export const GauntletUSDC: LendMarketConfig = {
      address: '0xabc...',
      chainId: unichain.id,
      name: 'Gauntlet USDC',
      asset: USDC,
      lendProvider: 'morpho',
    }
    ```
  </Step>

  <Step title="Configure Lend Providers">
    Configure which lend protocols you want to support. You can enable one or multiple providers:

    ```typescript title="actions.ts" theme={null}
    // Additional config from previous steps...

    import type { LendConfig } from "@eth-optimism/actions-sdk";

    const lendConfig: LendConfig = {
      morpho: {
        marketAllowlist: [GauntletUSDC],
        marketBlocklist: [],  // Optional
      },
      aave: {
        marketAllowlist: [AaveWETH],
        marketBlocklist: [],  // Optional
      },
    };
    ```
  </Step>

  <Step title="Configure supported chains">
    Configure supported chains:

    ```typescript title="actions.ts" theme={null}
    // Additional config from previous steps...

    import { optimism, base } from "viem/chains";

    // Define any EVM chain
    const OPTIMISM = {
      chainId: optimism.id,
      rpcUrls: env.OPTIMISM_RPC_URL,
      bundler: {
        // Bundle and sponsor txs with a gas paymaster
        type: "simple" as const,
        url: env.OPTIMISM_BUNDLER_URL,
      },
    };

    const BASE = {
      chainId: base.id,
      rpcUrls: env.BASE_RPC_URL,
      bundler: {
        // Bundle and sponsor txs with a gas paymaster
        type: "simple" as const,
        url: env.BASE_BUNDLER_URL,
      },
    };

    const chains = [OPTIMISM, BASE];
    ```
  </Step>

  <Step title="Initialize Actions">
    Finally bring it all together and initialize Actions:

    ```typescript title="actions.ts" theme={null}
    // Additional config from previous steps...

    export const actions = createActions({
      wallet: walletConfig,
      assets: assetsConfig,
      lend: lendConfig,
      chains,
    });
    ```
  </Step>

  <Step title="Take Action">
    Once you've initialized your actions instance, import it anywhere you need to take action:

    ```typescript theme={null}
    import { actions } from './actions';

    // Use actions anywhere in your app
    const market = await actions.lend.getMarket({ ... });
    const wallet = await actions.wallet.createSmartWallet({ ... });
    const receipt = await wallet.lend.openPosition({ ... });
    ```
  </Step>
</Steps>

## Next Steps

For detailed API documentation and type definitions, see the [Actions SDK Reference](/app-developers/reference/actions/integrating-wallets).


# Connecting a wallet to Actions SDK
Source: https://docs.optimism.io/app-developers/guides/connect-wallet-to-actions

Connect an embedded provider wallet to Actions SDK so it can perform DeFi actions like Lend, Borrow, Swap, and Pay.

Actions SDK works with wallets from popular embedded wallet providers, regardless of where and how transactions are signed.
This guide shows you how to connect a provider wallet to Actions so it can call Actions functions.

For help deciding which wallet schema fits your use case, see [Integrating wallets](/app-developers/reference/actions/integrating-wallets).

## Connect your wallet

<Steps>
  <Step title="Choose a wallet provider">
    Follow embedded wallet provider documentation and installation steps.
    Actions works with Typescript clients, both frontend React and backend Node.
  </Step>

  <Step title="Import Actions SDK">
    Import [Actions SDK](https://actions.money/) alongside your chosen wallet
    provider SDK.
    The [quickstart](/app-developers/quickstarts/actions#installation) covers
    installing Actions SDK in your project.
  </Step>

  <Step title="Create and fetch embedded user wallets">
    Follow embedded wallet provider documentation for wallet creation and
    access.
  </Step>

  <Step title="Pass the wallet to Actions">
    Call `actions.wallet.toActionsWallet(...)`, and [pass
    in](/app-developers/quickstarts/actions#choose-a-wallet-provider) the
    provider wallet.
    The quickstart includes provider-specific code examples for both frontend
    and backend clients.
  </Step>

  <Step title="Take Action">
    The returned
    [Wallet](/app-developers/reference/actions/wallet-definitions) is now
    capable of calling Actions
    [functions](/app-developers/quickstarts/actions#take-action) like Lend,
    Borrow, Swap and Pay!
  </Step>
</Steps>

## Next steps

* Follow the [Configuring Actions](/app-developers/guides/configuring-actions) guide to define which protocols, chains, and assets to support.
* Learn about [smart wallets & signers](/app-developers/reference/actions/integrating-wallets#smart-wallets--signers) if you want Actions to deploy smart contract wallets controlled by your users' embedded wallets.
* See the [Wallet Documentation](/app-developers/reference/actions/wallet-definitions) for API details on wallet classes, functions, and parameters.


# Build interoperable apps on OP Stack devnet
Source: https://docs.optimism.io/app-developers/guides/interoperability/get-started

Learn about deploying contracts, cross-chain messaging, and tutorials to help you build applications on OP Stack chains.

Reimagine your app with OP Stack interop to deliver the unified UX your users expect. Hack on net-new, bold use cases on Interop devnet.

<Info>
  Explore the [Superchain Dev Console](https://console.optimism.io/?utm_source=op-docs\&utm_medium=docs) to build, launch, and grow your app on OP Stack chains.
</Info>

## Connect to OP Stack Interop

Choose your development environment to build, test, and quickly iterate on your apps.

| Environment           | Purpose                                   | Getting Started                                                                     |
| --------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------- |
| **Local development** | Rapid iteration and testing with Supersim | [Setup Supersim guide](/app-developers/tutorials/development/supersim/installation) |
| **Interop devnet**    | Large-scale testing on testnets           | [Network specs](/app-developers/guides/building-apps)                               |

## Tools & resources for building interoperable apps

| Tool                                                                                        | Description                                                                |
| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [Superchain Faucet](https://console.optimism.io/faucet?utm_source=op-docs\&utm_medium=docs) | One-stop shop to grab testnet ETH for any OP Stack network.                |
| [Supersim](/app-developers/tools-sdks/supersim)                                             | Local multi-chain testing environment for smart contracts.                 |
| [Super CLI](https://github.com/ethereum-optimism/super-cli)                                 | Command-line tool for seamless multichain app deployment and testing.      |
| [Superchain Relayer](https://github.com/ethereum-optimism/superchain-relayer)               | UI for monitoring and managing cross-chain transactions.                   |
| [Interop Docs](/op-stack/interop/explainer)                                                 | Comprehensive Interop information in the Optimism Docs.                    |
| [Developer Console](https://console.optimism.io/?utm_source=op-docs\&utm_medium=docs)       | Comprehensive tool to build, launch, and grow your app on OP Stack chains. |
| [Developer Support GitHub](https://github.com/ethereum-optimism/developers/discussions)     | Quick and easy developer support.                                          |

## Handy step-by-step guides

<CardGroup>
  <Card title="Supersim tutorials" icon="flask" href="/app-developers/tutorials/supersim" />

  <Card title="Interop tutorials" icon="network-wired" href="/app-developers/tutorials/interop" />

  <Card title="Transaction tutorials" icon="arrow-right-arrow-left" href="/app-developers/tutorials/transactions/sdk-estimate-costs" />

  <Card title="Bridging tutorials" icon="bridge-water" href="/app-developers/tutorials/bridging/standard-bridge-standard-token" />
</CardGroup>

## Discover and build net-new use cases with OP Stack Interop

There is so much more than just bridge abstraction. Hack on the various cutting-edge applications that are uniquely enabled by OP Stack Interop. Here are some ideas to get you started:

| Superloans                                                                         | Superlend                                                                                                           | SuperCDP                                                                                                          |
| :--------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------- |
| Use collateral on ChainA and ChainB to execute an arbitrage opportunity on ChainA. | Deposit ETH into lending protocols across chains for optimal yield, with automatic rebalancing based on best rates. | Collateralized crosschain debt protocol that holds assets and issues cross-chain tokens on user preferred chains. |


# Message expiration
Source: https://docs.optimism.io/app-developers/guides/interoperability/message-expiration

What message expiration is, why it exists, and how to reemit a previously sent message if it has expired and was never relayed.

# Message expiration

[Messages](/app-developers/guides/interoperability/message-passing) referenced between OP Stack chains have a limited validity period called the expiry window. Once this window elapses, the referenced message becomes invalid and can no longer be referenced.

For messages using [`L2ToL2CrossDomainMessenger`](/app-developers/guides/interoperability/message-passing), if a message expires before being referenced, developers can reemit the message on the source chain. This triggers a fresh `SentMessage` event, enabling the message to be relayed.

## The expiry window

The expiry window is an offchain constant that defines how long a cross-chain message or event emitted remains valid. For any chain in the [Superchain interop cluster](/interop/explainer#superchain-interop-cluster), messages must be referenced within 7 days (604,800 seconds) of the log being created.

After this period, a message can no longer be referenced unless the event is remitted.

## Reemitting an expired message

The `resendMessage` function on the [`L2ToL2CrossDomainMessenger`](/app-developers/guides/interoperability/message-passing) contract allows developers to reemit a message that was sent but not yet relayed.

This emits a new `SentMessage` log with the same content as the original message, enabling offchain relayers to pick it up again.

The process to reemit an expired message:

1. Call [`resendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L2/IL2ToL2CrossDomainMessenger.sol#L114-L122) on the origin chain to reemit the message event. The contract verifies the message hash was originally sent. The call requires   [every parameter](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L2/IL2ToL2CrossDomainMessenger.sol#L114-L122) to rebuild the original message.

2. [Relay the new message](/interop/message-passing#executing-message) as normal.

Note: Re-emitting an already relayed message will have no effect on the destination chain, since the destination chain only honors the original initiating message.

## Next steps

* Learn how to [pass messages between blockchains](/app-developers/tutorials/interoperability/message-passing)


# Interop message passing overview
Source: https://docs.optimism.io/app-developers/guides/interoperability/message-passing

Understand how interop message passing works, from the initiating message on the source chain to the executing message on the destination chain.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

<Info>
  This is an explanation of how interop works.
  You can find a step by step tutorial [here](/app-developers/tutorials/interoperability/message-passing).
</Info>

The low-level [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol) contract handles basic message execution. It verifies whether an initiating message exists but does not check the message's destination, processing status, or other attributes.

The [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract extends `CrossL2Inbox` by providing complete cross-domain messaging functionality.

For high-level interoperability, both messages use the `L2ToL2CrossDomainMessenger` contract on their respective chains.

## Initiating message

```mermaid theme={null}

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 A<br/>in chainId B<br/>with calldata C
    note over srcXdom: 3. Sanity checks
    srcXdom->>log: 4. Log event SentMessage
    
```

1. The application sends a transaction to a contract on the source chain.

2. The contract calls [`L2ToL2CrossDomainMessenger.SendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L125-L142).
   The call requires these parameters:

   * `_destination`: The chain ID of the destination blockchain.
   * `_target`: The address of the contract on that blockchain.
   * `_message`: The actual message.

   This message is provided to `_target` as calldata, which means it includes a function selector and the parameters for that function call.

3. `L2ToL2CrossDomainMessenger` on the source chain verifies the message is legitimate:
   * The destination chain is one to which this chain can send messages.
   * The destination chain is *not* the source chain.
   * The target is neither `CrossL2Inbox` nor `L2ToL2CrossDomainMessenger`.

4. `L2ToL2CrossDomainMessenger` emits a log entry.
   In addition to the parameters, the log entry also includes:

   * `_nonce`: A [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) value to ensure the message is only executed once.

   * `_sender`: The contract that sent the cross domain message.

## Executing message

```mermaid theme={null}

sequenceDiagram
    participant app as Autorelayer
    box rgba(0,0,0,0.1) Source Chain
      participant log as Event Log
    end
    box rgba(0,0,0,0.1) Destination Chain
      participant dstNode as Destination Chain Node
      participant dstXdom as L2ToL2CrossDomainMessenger
      participant Xinbox as CrossL2Inbox
      participant dstContract as Destination Contract
    end
    log->>dstNode: 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
```

1. Before the executing message is processed, the log event of the initiating message has to reach the destination chain's node before the [expiry window](/app-developers/guides/interoperability/message-expiration) of 7 days.

2. The autorelayer, the application, or a contract calling on the application's behalf calls [`L2ToL2CrossDomainMessenger.relayMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L150-L203).
   This call includes the message that was sent (`_sentMessage`), as well as the [fields required to find that message (`_id`)](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L2/ICrossL2Inbox.sol#L4-L10).

3. The `L2ToL2CrossDomainMessenger` uses `CrossL2Inbox` to verify the message was sent from the source.

4. `L2ToL2CrossDomainMessenger` on the destination chain verifies the message is legitimate:

   * `_destination`: Chain ID of the destination chain.
   * `_nonce`: Nonce of the message sent
   * `_sender`: Address that sent the message
   * `_target`: Target contract or wallet address.
   * `message`: Message payload to call target with.

5. If everything checks out, `L2ToL2CrossDomainMessenger` calls the destination contract with the calldata provided in the message.

## Next steps

* Learn how to [pass messages between blockchains](/app-developers/tutorials/interoperability/message-passing).


# Reading Logs with OP Stack Interop
Source: https://docs.optimism.io/app-developers/guides/interoperability/reading-logs

Understand how contracts use CrossL2Inbox to validate logs from other interop chains, and how this pull model differs from sending messages.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>
OP Stack interop enables developers to leverage current and historical logs from other blockchains within the [OP Stack interop cluster](/interop/explainer#superchain-interop-cluster) directly on their local chain.
This allows smart contracts to consume local and cross-chain logs with low latency in a trust-minimized way.

## Overview

Instead of relying solely on [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol), developers can use [`CrossL2Inbox#validateMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L76) and treat `CrossL2Inbox` as an oracle for logs that occurred on different chains or even their local chain.

This enables developers to:

* Build cross-chain applications that react to events happening across OP Stack chains.
* Create novel applications that leverage data from multiple chains.

<Info>
  When reading logs, you must reference logs created within the [expiry window of 7 days](/app-developers/guides/interoperability/message-expiration).
</Info>

## Why use `CrossL2Inbox`?

* **Reference existing logs**: Allows contracts to verify and use logs that were already emitted, without requiring those logs to have been sent as cross-chain messages.
* **Trust-minimized security**: Leverages the existing OP Stack security model with no additional trust assumptions.
* **Flexibility**: Can be used to validate events from another chain or even the local chain.

## How it works

### Architecture

The process works through the [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L31) contract, which serves as an oracle for logs from other chains in the OP Stack interop cluster:

1. A smart contract on `Chain A` emits a log (event)
2. Your contract on `Chain B` calls `CrossL2Inbox#validateMessage` with the log's identifier
3. The `CrossL2Inbox` contract verifies the log's authenticity
4. Your contract can then use the validated log data

### Key components

* **Identifier**: A struct containing information about the log, including `chainId`, `origin` (contract address), and other log metadata
* **[validateMessage](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L79)**: Function that verifies a log's authenticity before allowing its use

## Example: cross-chain attestation verification

Let's walk through a conceptual example of verifying an Ethereum Attestation Service (EAS) attestation across chains.
EAS is a [predeploy](/app-developers/reference/contracts/interop/predeploy) in the OP Stack for making attestations on or off-chain about anything.

### Source chain: creating an attestation

On the source chain (e.g., OP Mainnet), a user creates an attestation using EAS:

```mermaid theme={null}
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
```

1. The user initiates a request for an attestation through an application.

2. The application calls the `createAttestation()` function on the EAS (Ethereum Attestation Service) contract on the source chain.

3. The EAS contract processes the attestation request and emits an `AttestationCreated` event.

4. The event is recorded in the chain's log, containing all necessary attestation data.

### Destination chain: verifying the attestation

On the destination chain (e.g., Unichain), a DeFi application wants to verify this attestation:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant DeFi as DeFi Application
    participant Verifier as AttestationVerifier
    participant CrossL2 as CrossL2Inbox

    User->>DeFi: Request access using attestation
    DeFi->>Verifier: verifyAttestation(id, attestationEvent)
    Verifier->>CrossL2: validateMessage(id, keccak256(attestationEvent))
    Note over CrossL2: Check the log exists on the source chain.
    CrossL2-->>Verifier: Return validation result
    Verifier-->>DeFi: Return verification status
    DeFi-->>User: Grant access based on attestation
```

1. The user requests access to a DeFi application on the destination chain, referencing an attestation created on the source chain.

2. The DeFi application calls a verification function on an attestation verifier contract, passing the attestation's identifier and event data.

3. The attestation verifier calls `validateMessage()` on the `CrossL2Inbox` contract, passing the attestation identifier and a hash of the event data.

4. The [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol) contract checks whether the specified log exists on the source chain.

5. The `CrossL2Inbox` returns the validation result to the attestation verifier.

6. The attestation verifier returns the verification status to the DeFi application.

7. If validation is successful, the DeFi application grants the user access based on the verified attestation.

The primary benefit of this approach is that it allows your contract to verify attestations that already exist on another chain without requiring those attestations to have been explicitly sent as cross-chain messages.

## Overview of the process

To implement cross-chain log reading:

```mermaid theme={null}
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
```

1. First, identify which log from another chain you want to consume in your application.

2. Create an Identifier struct that contains all necessary information about the log, including the chain ID and the contract address that emitted the log.

3. Call the `validateMessage()` function on the `CrossL2Inbox` contract, passing the identifier and a hash of the log data.

4. After validation, process the log data according to your application's requirements.

## Important considerations

* This feature works between chains within the [OP Stack interop cluster](/interop/explainer#superchain-interop-cluster).
* The same functionality can be used on a single chain (for example, to maintain a consistent architecture).

### Handling validation failures

* The `validateMessage` call will revert the entire transaction if validation fails.
* Consider implementing a try-catch pattern in your application's frontend to handle these failures.
* Design your contract to allow for retry mechanisms where appropriate.

## Comparison with `L2ToL2CrossDomainMessenger`

| Feature    | L2ToL2CrossDomainMessenger                     | CrossL2Inbox#validateMessage                      |
| ---------- | ---------------------------------------------- | ------------------------------------------------- |
| Purpose    | Send messages between chains                   | Verify logs from other chains or local chain      |
| Initiation | Source explicitly sends message to destination | Destination queries for existing logs from source |
| Use Case   | Transfer tokens, trigger actions               | Verify attestations, reference events             |
| Flow       | Push model                                     | Pull model                                        |

## End-to-End flow comparison

```mermaid theme={null}
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]
        J[Destination Contract] -->|validateMessage| K[CrossL2Inbox]
        K -.->|verify log exists on source chain| H
    end
```

This diagram compares the two approaches for cross-chain communication:

### L2ToL2CrossDomainMessenger (Push Model):

1. A source contract calls `sendMessage()` on the `L2ToL2CrossDomainMessenger`.

2. The messenger emits an event to the event log.

3. An autorelayer detects the event and relays it to the destination chain.

4. The destination `L2ToL2CrossDomainMessenger` receives the relayed message.

5. The destination messenger executes the message on the target contract.

### CrossL2Inbox (Pull Model):

1. A source contract emits an event to the event log.

2. A destination contract calls `validateMessage()` on the `CrossL2Inbox`.

3. The `CrossL2Inbox` verifies that the log exists on the source chain.

4. The destination contract receives verification and proceeds with its logic.

## Next steps

* Learn how to [pass messages between blockchains](/app-developers/tutorials/interoperability/message-passing)


# Testing apps for OP Stack chains
Source: https://docs.optimism.io/app-developers/guides/testing-apps

Learn best practices for testing apps on OP Stack chains.

For the most part, running applications on OP Stack chains is identical to running them on Ethereum, so the testing is identical too.
In this guide, you learn the best practices for OP Stack testing where there are differences.

## Unit tests and single layer integration tests

The vast majority of tests do not involve any OP Stack-specific features.
In those cases, while you *could* test everything on an OP Stack chain or a test network, that would normally be inefficient.
Most Ethereum development stacks include features that make testing easier, which normal Ethereum clients, such as geth (and our modified version, `op-geth`) don't support.
Therefore, it is a good idea to run the majority of tests, which do not rely on OP Stack-specific features, in the development stack.
It is a lot faster.

It is a best practice to design and run thorough tests across an OP test network, either in your [local multichain development environment](/app-developers/tools/development/supersim), our [devnets](/op-stack/introduction/op-stack), or on [the test network](/op-mainnet/network-information/connecting-to-op#op-sepolia), depending on your use case. Alternatively, with [Tenderly Virtual TestNets](https://docs.tenderly.co/virtual-testnets?mtm_campaign=ext-docs\&mtm_kwd=optimism)you can run tests with complete integration with existing protocols, access to unlimited faucets, continuous state sync, and access to development tools such as Debugger and Simulator UI.
Running proper testing is key to identifying fringe cases where the equivalence between OP Stack chains and Ethereum breaks down (or where Ethereum mainnet itself and the development stack may be non-equivalent in a production environment).

## Multilayer integration tests

Some apps need OP Stack-specific features that aren't available as part of the development stack.
For example, if your decentralized application relies on [inter-domain communication](/app-developers/guides/bridging/messaging), the effort of developing a stub to let you debug it in a development stack is probably greater than the hassle of having the automated test go to [a local multichain development environment](/app-developers/tools/development/supersim) each time.

## Testing and Staging with Tenderly

Tenderly [Virtual TestNets](https://docs.tenderly.co/virtual-testnets?mtm_campaign=ext-docs\&mtm_kwd=optimism) provide a powerful environment for testing OP Stack applications with mainnet-like conditions. They offer several advantages for testing OP Stack applications:

* **Mainnet State Replication**: Virtual TestNets can sync with the latest OP Stack mainnet state, allowing you to test against real network conditions and interact with up-to-date protocols without spending real assets.
* **Unlimited Faucet**: Access [unlimited test tokens](https://docs.tenderly.co/virtual-testnets/unlimited-faucet?mtm_campaign=ext-docs\&mtm_kwd=optimism) for both native currency and ERC-20 tokens, enabling comprehensive testing of complex DeFi interactions.
* **Collaborative Testing**: Your entire team can access the same testing environment, making it easier to debug issues and validate fixes.
* **CI/CD Integration**: Incorporate automated testing in your deployment pipeline using [Virtual TestNets' API](https://docs.tenderly.co/reference/api?mtm_campaign=ext-docs\&mtm_kwd=optimism#/operations/createAlert) and [GitHub Actions integration](https://docs.tenderly.co/virtual-testnets/ci-cd/github-actions-foundry?mtm_campaign=ext-docs\&mtm_kwd=optimism).
* **Development tools**: Rely on the built-in [developer explorer](https://docs.tenderly.co/developer-explorer?mtm_campaign=ext-docs\&mtm_kwd=optimism) and debugging tools to analyze test transactions and contract interactions.

## Integration with other products

In many cases a decentralized application requires the services of other contracts.
For example, [Perpetual v. 2](https://docs.perp.com/docs/guides/integration-guide) cannot function without [Uniswap v. 3](https://uniswap.org/blog/uniswap-v3).

* If that is the case, you can use [mainnet forking](/app-developers/reference/tools/supersim/fork). It works with OP Stack chains.
* Create a Virtual TestNet to get access to third party contracts (e.g. Uniswap) and it's latest or historical state.
* Alternatively, you can connect to our [test network](/op-mainnet/network-information/connecting-to-op#op-sepolia) if those contracts are also deployed there (in many cases they are).


# Estimating transaction fees on OP Mainnet
Source: https://docs.optimism.io/app-developers/guides/transactions/estimates

Learn how to properly estimate the total cost of a transaction on OP Mainnet.

<Info>
  Check out the guide on understanding [Transaction Fees on OP Mainnet](/op-stack/transactions/fees) for an in-depth explanation of how OP Mainnet transaction fees work.
</Info>

It's important to properly estimate the cost of a transaction on OP Mainnet before submitting it to the network.
Here you'll learn how to estimate both of the components that make up the total cost of an OP Mainnet transaction, the [execution gas fee](/op-stack/transactions/fees#execution-gas-fee) and the [L1 data fee](/op-stack/transactions/fees#l1-data-fee).
Make sure to read the guide on [Transaction Fees on OP Mainnet](/op-stack/transactions/fees) for a detailed look at how these fees work under the hood.

## Execution gas fee

<Info>
  Estimating the execution gas fee on OP Mainnet is just like estimating the execution gas fee on Ethereum.
  Steps are provided here for reference and convenience, but you can use the same tooling that you'd use to estimate the execution gas fee for a transaction on Ethereum.
</Info>

A transaction's execution gas fee is exactly the same fee that you would pay for the same transaction on Ethereum.
This fee is equal to the amount of gas used by the transaction multiplied by the gas price attached to the transaction.
Refer to the guide on [Transaction Fees on OP Mainnet](/op-stack/transactions/fees#execution-gas-fee) for more information about the execution gas fee.

When estimating the execution gas fee for a transaction, you'll need to know the gas limit and the [max fee per gas](https://ethereum.org/en/developers/docs/gas/#maxfee) for the transaction.
Your transaction fee will then be the product of these two values.
Refer to the guide on [Setting Transaction Gas Parameters on OP Mainnet](./parameters) to learn how to select an appropriate gas limit and max fee per gas for your transaction.

<Steps>
  <Step title="Estimate the gas limit">
    Using the same tooling that you'd use to estimate the gas limit for a transaction on Ethereum, estimate the gas limit for your transaction on OP Mainnet.
    OP Mainnet is designed to be [EVM equivalent](https://web.archive.org/web/20231127160757/https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306) so transactions will use the same amount of gas on OP Mainnet as they would on Ethereum.
    This means you can feed your transaction to the [`eth_estimateGas`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_estimategas) JSON-RPC method just like you would on Ethereum. Alternatively, use Tenderly's [`tenderly_estimateGas`](https://docs.tenderly.co/node/rpc-reference/optimism-mainnet/tenderly_estimateGas) for 100% accurate gas estimations.
  </Step>

  <Step title="Estimate the max fee per gas">
    Like Ethereum, OP Mainnet uses an `EIP-1559` style fee market to determine the current base fee per gas.
    You can then additionally specify a priority fee (also known as a tip) to incentivize the Sequencer to include your transaction more quickly.
    Make sure to check out the guide on [Setting Transaction Gas Parameters on OP Mainnet](./parameters) to learn more about how to select an appropriate max fee per gas for your transaction.
  </Step>
</Steps>

## L1 data fee

<Info>
  The Viem library provides a convenient method for estimating the L1 data fee for a transaction.
  Check out the tutorial on [Estimating Transaction Costs on OP Mainnet](/app-developers/tutorials/transactions/sdk-estimate-costs) to learn how to use the Viem library to estimate the L1 data fee for your transaction.
  Keep reading if you'd like to learn how to estimate the L1 data fee without the Viem library.
</Info>

The L1 data fee is a fee paid to the Sequencer for the cost of publishing your transaction to Ethereum.
This fee is paid in ETH and is calculated based on the size of your transaction in bytes and the current gas price on Ethereum.
Refer to the guide on [Transaction Fees on OP Mainnet](/op-stack/transactions/fees#l1-data-fee) for more information about the L1 data fee.

Unlike the execution gas fee, the L1 data fee is an **intrinsic** fee for every transaction.
This fee is automatically charged based on the size of your transaction and the current Ethereum gas price.
You currently cannot specify a custom L1 data fee for your transaction.

<Info>
  The L1 data fee is paid based on the current Ethereum gas price as tracked within the [`GasPriceOracle`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/GasPriceOracle.sol) smart contract.
  This gas price is updated automatically by the OP Mainnet protocol.
  Your transaction will be charged the Ethereum gas price seen by the protocol at the time that your transaction is included in an OP Mainnet block.
  This means that the L1 data fee for your transaction may differ from your estimated L1 data fee.
</Info>

<Steps>
  <Step title="Serialize your transaction">
    The L1 data fee is calculated based on the size of your serialized transaction in bytes.
    Most Ethereum tooling will provide a method for serializing a transaction.
    For instance, Ethers.js provides the [`ethers.utils.serializeTransaction`](https://docs.ethers.org/v5/api/utils/transactions/#utils-serializeTransaction) method.
  </Step>

  <Step title="Estimate the L1 data fee">
    Once you have serialized your transaction, you can estimate the L1 data fee by calling the [`getL1Fee`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/GasPriceOracle.sol#L64-L71) method on the [`GasPriceOracle`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/GasPriceOracle.sol) smart contract available on OP Mainnet and all OP Stack chains.
    This method takes the serialized transaction as input and returns the L1 data fee in wei using the formula described in the [Transaction Fees on OP Mainnet](/op-stack/transactions/fees#l1-data-fee) guide.

    <Info>
      Fee estimation is typically performed before the transaction is signed.
      As a result, the `getL1Fee` method assumes that your input is an **unsigned** Ethereum transaction.
    </Info>
  </Step>
</Steps>

### Tooling

Several tools are available to help you estimate the L1 Data Fee for your transaction.
Selecting the right tool for your use case will depend on your specific needs.

* [Viem](https://viem.sh/op-stack#getting-started-with-op-stack) provides first-class support for OP Stack chains, including OP Mainnet. You can use Viem to estimate gas costs and send cross-chain transactions (like transactions through the Standard Bridge system). It's strongly recommended to use Viem if you are able to do so as it will provide the best native support at the moment.

### Future proofing

The L1 Data Fee formula is subject to change in the future, especially as the data availability landscape evolves.
As a result, it's important to future-proof your transaction fee estimation code to ensure that it will continue to function properly as the L1 Data Fee formula changes.

* Use existing [tooling](#tooling) to estimate the L1 Data Fee for your transaction if possible. This tooling will be updated to reflect any changes to the L1 Data Fee formula. This way you won't need to modify your code to account for any changes to the formula.
* Use the `getL1Fee` method on the `GasPriceOracle` if you are unable to use existing tooling. The `getL1Fee` method will be updated to reflect any changes to the L1 Data Fee formula. It's strongly recommended that you do **not** implement the L1 Data Fee formula yourself.


# Integrate Subblocks in your app
Source: https://docs.optimism.io/app-developers/guides/transactions/integrating-subblocks

Query pre-confirmed Subblocks state from your app using standard JSON-RPC methods with the pending tag, or through viem and ethers.

A chain that streams [Subblocks](/op-stack/features/subblocks) publishes a partial block every 200 ms, so your app can show a transaction's result well before the block containing it is sealed.
This guide shows how to read that pre-confirmed state over standard Ethereum JSON-RPC and from the viem and ethers libraries.

Most apps need only a change of endpoint and the `pending` block tag.

* In production, point your app to a subblocks-aware RPC endpoint from your provider of choice. If your provider doesn't support subblocks yet, let us know on [Discord](https://discord.gg/jPQhHTdemH)
  and we'll work with them to get it added.
* To run your own subblocks-aware node, start `op-reth` with `--flashblocks-url=<websocket-url>` pointing at the chain's stream. The node then serves `pending` from the subblock state.
  OP Mainnet and OP Sepolia stream URLs are listed on the [network information page](/op-mainnet/network-information/connecting-to-op).

<Info>
  This guide covers reading pre-confirmed state through an RPC endpoint, which is what most apps want.
  If you consume the WebSocket stream directly instead, four payload fields are zeroed and need handling — see the [Subblocks notice](/notices/subblocks).
</Info>

## Supported RPC methods

You read subblock state with the same Ethereum JSON-RPC calls you already use.
The difference is using the "pending" tag in some of them to explicitly query the pre-confirmed state instead of the last finalized block.

* **`eth_getBlockByNumber`**: Use the `pending` tag to retrieve the latest subblock snapshot.

  <Expandable title="Sample response">
    ```json theme={null}
        {
          "jsonrpc": "2.0",
          "id": 1,
          "result": {
            "number": "0x1234",
            "hash": "0x...",
            "transactions": [...]
          }
        }
    ```
  </Expandable>

* **`eth_call`**: Use the `pending` tag to execute calls against the most recent pre-confirmed state.

  <Expandable title="Sample request">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "method": "eth_call",
      "params": [{"to": "0x...", "data": "0x..."}, "pending"],
      "id": 1
    }
    ```
  </Expandable>

* `eth_getBalance` / `eth_getTransactionCount`: Use the `pending` tag to fetch balances or transaction counts respectively as they evolve within the block window.

  <Expandable title="Sample response for `eth_getBalance`">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": "0x0234"
    }
    ```
  </Expandable>

  <Expandable title="Sample response for `eth_getTransactionCount`">
    ```json theme={null}
    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": "0x1b" // 27 transactions
    }
    ```
  </Expandable>

  Other methods, like `eth_getTransactionReceipt`, `eth_getTransactionByHash` or `eth_simulateV1`, return data from pre-confirmed transactions without requiring the `pending` tag.
  Consult the [Flashblocks specification](https://specs.optimism.io/protocol/flashblocks.html#flashblock-json-rpc-apis) for more details on each of these methods.

## Libraries

You need a subblocks‑aware RPC endpoint to use the following libraries:

### Viem

```ts theme={null}
import { createPublicClient, createWalletClient, http, parseEther } from 'viem';
import { privateKeyToAccount } from 'viem/accounts';
import { opSepolia } from 'viem/chains';
import { publicActionsL2, walletActionsL2 } from 'viem/op-stack';

const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);

const walletClient = createWalletClient({
  account,
  chain: opSepolia,
  transport: http("https://sepolia.optimism.io"),
}).extend(walletActionsL2());

const publicClient = createPublicClient({
  chain: opSepolia,
  transport: http("https://sepolia.optimism.io"),
}).extend(publicActionsL2());

const submissionTime = new Date();
const hash = await walletClient.sendTransaction({
  to: '0x...',
  value: parseEther('0.0001'),
});

// Wait for pre-confirmation
const receipt = await publicClient.waitForTransactionReceipt({ hash });
const confirmTime = new Date();
console.log('pre-confirmed in ms:', confirmTime.getTime() - submissionTime.getTime());
```

### Ethers

```ts theme={null}
import { ethers } from 'ethers';

// Here, provider is a subblocks-enabled RPC provider
const provider = new ethers.JsonRpcProvider("https://sepolia.optimism.io");
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY as string, provider);

const tx = { to: '0x...', value: ethers.parseEther('0.0001') };
const submission = new Date();

const sent = await wallet.sendTransaction(tx);

await sent.wait(0);
const confirmed = new Date();

// should represent the transaction (pre)confirmation faster than standard RPC
console.log('Pre-confirmed in ms:', confirmed.getTime() - submission.getTime());

// validates the transaction hash returned by the pre-confirmed transaction above
const receipt = await provider.getTransactionReceipt(sent.hash);
const validated = new Date();
console.log('Receipt validated in ms:', validated.getTime() - submission.getTime());
console.log('Transaction receipt:', receipt);
```

## Next steps

* Understand how subblocks affect [gas usage and large transactions](/app-developers/guides/transactions/subblocks-and-gas-usage).
* Learn how subblocks work in the [Subblocks explainer](/op-stack/features/subblocks).
* Review the [technical specs](https://specs.optimism.io/protocol/flashblocks.html) for architecture details.
* Join our [community](https://discord.gg/jPQhHTdemH) to share best practices and get support!


# Setting transaction gas parameters on OP Mainnet
Source: https://docs.optimism.io/app-developers/guides/transactions/parameters

Learn how to set gas parameters for transactions on OP Mainnet.

OP Mainnet is designed to be [EVM equivalent](https://web.archive.org/web/20231127160757/https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306) which means that it is as compatible with Ethereum as possible, down to the client software used to run OP Mainnet nodes.
Like Ethereum, OP Mainnet has an EIP-1559 style fee mechanism that dynamically adjusts a [base fee](https://ethereum.org/en/developers/docs/gas/#base-fee) that acts as the minimum fee that a transaction must pay to be included in a block.
OP Mainnet also allows transactions to pay a [priority fee](https://ethereum.org/en/developers/docs/gas/#priority-fee) (also known as a tip) to incentivize the Sequencer to include transactions more quickly.

Setting the base fee and the priority fee appropriately is important to ensure that your transactions are included in a timely manner.
This guide will walk you through some best practices for determining the base fee and priority fee for your transactions.

## Selecting the base fee

The base fee is the minimum fee that a transaction must pay to be included in a block.
Transactions that specify a maximum fee per gas that is less than the current base fee cannot be included in the blockchain.

The simplest way to select a base fee is to look at the latest available OP Mainnet block.
Each OP Mainnet block includes the current base fee and the amount of gas used within that block.
You can use this information to predict a reasonable maximum fee for your transaction.

Note that, like Ethereum, the base fee is not explicitly defined within a transaction.
Instead, the maximum base fee is determined as the difference between the `maxFeePerGas` and the `maxPriorityFeePerGas` fields of any given transaction.

<Steps>
  <Step title="Retrieve the latest block">
    Using the JSON-RPC API or your favorite Ethereum library, retrieve the latest block on OP Mainnet.
  </Step>

  <Step title="Retrieve the base fee and gas used">
    From the block, retrieve the `baseFeePerGas` and `gasUsed` fields.
  </Step>

  <Step title="Predict the next base fee">
    OP Mainnet adjusts the base fee based on the amount of gas used in the previous block.
    If the previous block used more than 5m gas (of the 30m gas limit), then the base fee will increase by up to 10%.
    If the previous block used less than 5m gas, then the base fee will decrease by up to 10%.
    Refer to the [OP Mainnet EIP-1559 Parameters](/op-stack/protocol/differences#eip-1559-parameters) section for more details.
  </Step>

  <Step title="Select a base fee per gas">
    Using the current base fee per gas and the amount of gas used in the previous block, you can predict the next base fee per gas.
    If you are highly sensitive to the base fee, you may want to select a base fee per gas that is either 10% higher or 10% lower than the previous base fee.
    However, you may run the risk that your transaction will not be included in a block quickly.
    If you are less sensitive to the base fee, you may wish to simply use a large multiple of the previous base fee (e.g. 2x).
  </Step>
</Steps>

## Selecting the priority fee

The priority fee is an optional tip that can be paid to the Sequencer to incentivize them to include your transaction more quickly.
The priority fee is paid in addition to the base fee.

The simplest way to select a priority fee is to use the [`eth_maxPriorityFeePerGas`](https://docs.alchemy.com/reference/eth-maxpriorityfeepergas) JSON-RPC method to retrieve an estimate for an acceptable priority fee.
Many Ethereum libraries will provide a function to call this JSON-RPC method.
You can also use the [`eth_feeHistory`](https://docs.alchemy.com/reference/eth-feehistory) JSON-RPC method to retrieve historical priority fee data.
You can then use this data to predict a reasonable priority fee for your transaction.

Alternatively, you can rely on Tenderly's [`tenderly_gasPrice`](https://docs.tenderly.co/node/rpc-reference/optimism-mainnet/tenderly_gasPrice?mtm_campaign=ext-docs\&mtm_kwd=optimism) to get real-time gas predictions with 3 levels of likelihood for transaction inclusion.


# Transaction statuses on OP Mainnet
Source: https://docs.optimism.io/app-developers/guides/transactions/statuses

Reference for the statuses a transaction can have on OP Mainnet.

This page is a reference for the statuses a transaction can have on OP Mainnet, listed in the order a transaction moves through them.
Each entry gives the status, how long it typically takes to reach, what the status guarantees, and the JSON-RPC call used to observe it.

Consult it when you need to troubleshoot a transaction, decide how many confirmations your application should wait for, or display accurate status information to your users.
For an explanation of *why* a transaction moves through these states, see [Transaction flow](/op-stack/transactions/transaction-flow).

## Pending

**Instant after sending to the Sequencer**

A transaction is considered "pending" when it has been sent to the Sequencer but has not yet been included in a block.
This is the first status a transaction will have after being sent to the Sequencer.
At this point the transaction is not part of the blockchain and there is no guarantee that the transaction will be included in the blockchain.

The list of all pending transactions can be retrieved by calling the standard JSON-RPC method [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) with the parameter `pending` as the block number.

## Sequencer confirmed or unsafe

**Typically within 2-4 seconds**

A transaction is considered "sequencer confirmed" or "unsafe" when it has been included in a block by the Sequencer but that block has **not** yet been published to Ethereum.
Although the transaction is included in a block, it is still possible for the transaction to be excluded from the final blockchain if the Sequencer fails to publish the block to Ethereum within the [Sequencing Window](/connect/resources/glossary#sequencing-window) (approximately 12 hours).
Applications should make sure to consider this possibility when displaying information about transactions that are in this state.

The latest "sequencer confirmed" block can be retrieved by calling the standard JSON-RPC method [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) with the parameter `safe` as the block number and comparing this to the result returned for the `latest` block.
If the `safe` block is behind the `latest` block, then the earliest "sequencer confirmed" block is the `safe` block plus one.

## Published to Ethereum or safe

**Typically within 5-10 minutes, up to 12 hours**

A transaction is considered "safe" when it has been included in a block by the Sequencer and that block has been published to Ethereum but that block is not yet finalized.
Once a block has been published to Ethereum there is a high likelihood that the block will be included in the final blockchain.
However, it is still possible for the block to be excluded from the final blockchain if the Ethereum blockchain experiences a reorganization.

The latest "safe" block can be retrieved by calling the standard JSON-RPC method [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) with the parameter `safe` as the block number.

Transactions typically become "safe" within a few minutes of becoming "sequencer confirmed".

## Finalized

**Typically within 15-30 minutes, up to 12 hours**

A transaction is considered "finalized" when it has been included in a block by the Sequencer, that block has been published to Ethereum, and that block has been finalized.
Once a block has been finalized it is guaranteed to be included in the OP Mainnet blockchain.
Applications that require the highest level of certainty that a transaction will be included in the blockchain should wait until the transaction is "finalized" before considering the transaction to be successful.

The latest "finalized" block can be retrieved by calling the standard JSON-RPC method [`eth_getBlockByNumber`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getblockbynumber) with the parameter `finalized` as the block number.


# Subblocks and gas usage on OP Stack
Source: https://docs.optimism.io/app-developers/guides/transactions/subblocks-and-gas-usage

Explains how Subblocks affect block gas usage, transaction inclusion, and why large transactions can be rejected or stay pending.

This document explains how **subblocks** affect block gas usage, transaction inclusion, large-transaction handling, and how to avoid unexpected transaction rejections.

If you are unfamiliar with subblocks you can read more in the [Subblocks explainer](/op-stack/features/subblocks).

***

## Background: Block Gas Limit vs. Transaction Gas Limit

On OP Mainnet, the **theoretical block gas limit** is currently **40M gas**. In a traditional EVM mental model, a single transaction can use up to the full block gas limit, as long as it does not exceed it.

With **subblocks**, block construction is incremental and *effective transaction inclusion depends on the gas already consumed within the block*, not just the theoretical maximum.

***

## What Are Subblocks?

Subblocks are an incremental block-building mechanism: instead of constructing the full block at once, the sequencer's execution client assembles it as a series of subblocks, each of which adds to the *cumulative gas budget* available for inclusion.
For what subblocks are and how a block's subblock count is determined, see the [Subblocks explainer](/op-stack/features/subblocks).
The consequence for gas usage is that earlier subblocks can only include smaller transactions, and larger transactions fit only later in the block, *if enough gas remains*.

### Example

Assume:

* Block gas limit **B = 40M**
* Number of subblocks **N = 10**, the count a 2-second block time and a 200 ms interval imply

Then the cumulative gas limit increases as follows:

| Subblock | Max cumulative gas available |
| -------- | ---------------------------- |
| 1        | 4M                           |
| 2        | 8M                           |
| 3        | 12M                          |
| 4        | 16M                          |
| 5        | 20M                          |
| 6        | 24M                          |
| 7        | 28M                          |
| 8        | 32M                          |
| 9        | 36M                          |
| 10       | 40M                          |

A transaction with a **20M gas limit** can only be included starting from subblock 5, *and only if prior subblocks have not already consumed that gas*.

The subblock count is not fixed. Heavy execution in one interval leaves less time for the ones after it, so a real block may contain fewer subblocks than the interval implies.

***

## Why a Transaction Can Get Stuck

A transaction may be submitted with a gas limit lower than the total block gas limit (e.g. **38M \< 40M**) and still remain pending or, depending on the EL implementation, be rejected with the error: `exceeds block gas limit`.

This happens because transaction acceptance and transaction inclusion are decided by different components.

Generally:

* Incoming transactions first enter the Execution Layer txpool.
* The EL checks whether `tx.gasLimit` exceeds the **full block gas limit**.
  * If it does, it rejects with `exceeds block gas limit`.
  * Otherwise, it keeps the transaction in the **pending/queued mempool** and **P2P-gossips** it, eventually reaching the **sequencer**.
* The **sequencer's execution client** applies the incremental **remaining block gas** check to decide whether to include the tx in a subblock or leave it pending.

### Real-World Example

* Block gas limit: **40M**
* Gas already used in earlier subblocks: **13M**
* Remaining gas: **27M**
* Incoming transaction gas limit: **38M**

The **EL** checks if the transaction exceeds **40M**. Since **38M \< 40M**, the transaction is accepted into the pending/queued mempool and gossiped to the **sequencer**.
The sequencer's execution client applies the incremental remaining-gas constraint. With only **27M** gas remaining and the tx requiring **38M**, the transaction cannot be included yet and stays pending.

**Result:** the transaction is not rejected, but remains pending in the mempool until there is enough remaining gas to include it in a subblock.

***

## Client Behavior and Error Messages

There are two distinct outcomes depending on the transaction size:

* **Rejected immediately (txpool admission failure):**\
  The EL (e.g. **op-reth**) rejects transactions only when the transaction gas limit exceeds the **full block gas limit**:
  * Condition: `tx.gasLimit > blockGasLimit`
  * Error returned to the user: `exceeds block gas limit`

* **Accepted but pending inclusion:**\
  If the transaction gas limit is **within** the block gas limit, but still too large to fit into the **remaining block gas** at that point in the block, it will not be included yet.
  * The transaction remains in the **pending/queued mempool**, waiting for enough remaining gas to become available in a later subblock.
  * From the user’s perspective, the transaction may appear **pending** until it gets enough gas available for inclusion.

In practice, transactions are sent to Execution Layer RPC nodes (e.g. via proxyd), checked, and only if accepted into the EL txpool are eventually propagated to the sequencer for potential inclusion.

Implementing mechanisms such as txpool rebroadcasting can mitigate this divergence automatically, so users do not notice retries. However, when an error is surfaced, it may originate from the ingress client’s gas checks.

***

## Practical Guidance for Application Developers and End Users

### Leave Headroom for Large Transactions

If you submit large transactions, avoid targeting the full block gas limit.

**Recommended approach:**

* Leave **20–30% headroom** relative to the block gas limit
* For a 40M block, aim for ≤ **28–32M gas**

Or:

* Proactively cap single-transaction gas usage to \~16.7M gas to align with the upcoming L2 Fusaka transaction limit

This increases the chance that the transaction fits within Execution Layer gas checks under partial block utilization.

More generally, designing applications to avoid extremely large single transactions is good long-term practice since, with upcoming protocol changes (Fusaka on L2), transactions will be capped at 16.7M gas anyway.

***

### Expect Variable Gas Availability During Congestion

Under high demand:

* Early subblocks are often full
* Remaining gas later in the block may be limited
* Very large transactions may be rejected or require retries

This is expected behavior with subblocks and not necessarily an issue with the transaction itself.

***

### Transaction Resubmission

Because block state evolves quickly:

* Retrying submission in a later block may succeed
* Large transactions are more likely to be included when earlier subblocks are less congested

***

## Key Takeaways

* Subblocks build blocks incrementally, unlocking gas capacity over time rather than all at once\
  *(e.g. in a 40M gas block with 10 subblocks, only 4M is available at the first subblock, then 8M, and so on)*

* A transaction must be **within the full block gas limit** to be accepted into the EL txpool, but it must fit within the **remaining block gas** to be included by the sequencer in the next subblock
  *(e.g. if 13M gas out of 40M has already been used, a 38M gas transaction can be accepted by EL but cannot be included until enough remaining gas is available once it reaches the sequencer)*

* As a result, large transactions may be **accepted but remain pending** even when their gas limit is below the nominal block limit\
  *(e.g. a 38M gas transaction can be accepted in a 40M gas block but delayed during periods of high activity)*

* Leaving meaningful headroom is the most reliable way to improve inclusion success for large transactions\
  *(e.g. targeting 28–32M gas instead of the full 40M or proactively implementing the Fusaka limit of 16.7M gas)*


# Troubleshooting transactions
Source: https://docs.optimism.io/app-developers/guides/transactions/troubleshooting

Learn how to troubleshoot common problems with transactions.

## Transactions stuck in the transaction pool

OP Chain uses EIP-1559, but with different parameters than L1 Ethereum.
As a result, while the base fee on L1 can grow by up to 12.5% in a twelve-second period (in the case of a single 30M gas block), the L2 base fee can grow by up to 77% (in the case of six 30M gas blocks).
However, it still shrinks by only up to 12.5% in the same twelve-second period (if all the blocks are empty).

If the maximum fee per gas specified by the transaction is less than the block base fee, it does not get included until the base fee drops to below the value in the transaction.
When this happens, some users may see their transaction become stuck.
No ETH is lost, but the transaction does not clear on its own.

We have a workaround that users and wallet operators can implement immediately, and we expect a protocol-level fix to be live by the end of Q4.

### Recommendation

Set the maximum fee per gas for transactions to a relatively high value, such as 0.1 gwei.
This will *not* increase the transaction cost because the same base fee, determined by a formula, is charged to all the transactions in the block.
To save on the cost of L2 gas you want to minimize the max priority fee.

Also, if the [current base fee](https://optimistic.grafana.net/public-dashboards/c84a5a9924fe4e14b270a42a8651ceb8?orgId=1\&refresh=5m) is comparable to 0.1 gwei or higher, you might want to suggest to users a higher multiple of the base fee than you would on L1 Ethereum because it can grow faster in the time interval between transaction creation and transaction signing and submission.

#### Recommendations for wallet developers

Wallets are usually in charge of determining the default priority fee and max fee that a transaction would include, so the above recommendations can be applied directly.

#### Recommendations for app developers

As an app developer, you can usually override the default recommendation of the wallet
(see, for example, [ethers](https://github.com/ethers-io/ethers.js/blob/v5.7/packages/contracts/lib/index.d.ts#L10-L11)).
As long as not all wallets are upgraded according to our recommendations, it makes sense for apps to get the current base fee and recommend a value based on that.

#### Recommendations for users

As a user, you are the final authority on transaction fields. Sometimes when submitting a transaction, the gas fee is set too low, and it gets stuck in the transaction pool (a.k.a. mempool). If you want to push that transaction through, [you can cancel it by submitting another transaction with the same nonce](https://info.etherscan.com/how-to-cancel-ethereum-pending-transactions/). This method increases the fee and the sequencer will process it from the mempool quicker.

## Deposit transactions don't have a chainId on L2

[Deposit transactions](https://specs.optimism.io/protocol/deposits.html?utm_source=op-docs\&utm_medium=docs#the-deposited-transaction-type) are transactions added to the L2 blockchain as part of the block derivation process.
These transactions come from a dummy address and don't have a signature.
Because in Ethereum the chainID is encoded as part of the signature, this means there is no recoverable chainID for these transactions.

This is not a problem because the only source of deposit transactions is the block derivation process.
There shouldn't be a need to recover the chainID.


# App developers
Source: https://docs.optimism.io/app-developers/index

Routes app developers to the quickstarts, guides, tutorials, tools, and reference for building on OP Mainnet and other OP Stack chains.

You are building an app on OP Mainnet or another OP Stack chain. Pick the
path that matches where you are: start from zero, solve a specific task, or
look something up.

<CardGroup>
  <Card title="Deploy your first app" href="/app-developers/quickstarts/get-started">
    Go from zero to a working app on an OP Stack chain with the quickstart.
  </Card>

  <Card title="Solve a specific task" href="/app-developers/guides/building-apps">
    Follow a guide for building and testing apps, bridging, interoperability,
    or transactions.
  </Card>

  <Card title="Learn by doing" href="/app-developers/tutorials/deploy-a-contract">
    Work through step-by-step tutorials, from deploying a contract to
    cross-chain messaging with Supersim.
  </Card>

  <Card title="Pick your tools" href="/app-developers/tools-sdks/support-matrix">
    Choose supported SDKs, faucets, block explorers, and data tools for your
    stack.
  </Card>

  <Card title="Look up the details" href="/app-developers/reference/rpc-providers">
    Find RPC providers, Actions SDK definitions, token lists, and Supersim
    reference material.
  </Card>

  <Card title="Running a chain or a node instead?" href="/">
    Route by role from the documentation home: chain operators, node
    operators, and protocol learners each have their own section.
  </Card>
</CardGroup>


# Integrating DeFi with Actions SDK
Source: https://docs.optimism.io/app-developers/quickstarts/actions

Perform DeFi actions with lightweight, composable, and type-safe modules.

<Warning>
  Actions SDK is still under construction and not ready for production use! This
  guide is meant for early testing purposes only.
</Warning>

The [Actions SDK](https://actions.money/) is an open source Typescript development toolkit that simplifies the act of integrating DeFi into your application.

## How it works

Here's a breakdown of what's under the hood:

* **Modular Providers**: Actions is built with a set of core adapters called "Providers". Providers let you to pick an choose the right services and protocols for your use-case.

* **Embedded Wallets**: Actions supports popular embedded [wallet providers](https://actions.money/#wallet), allowing your users to access DeFi with email authentication flows alone.

* **Configure Actions**: Extend your embedded wallet with DeFi actions like Lend, Borrow, Swap, and Pay. Set multiple providers for each Action to choose the best markets across DeFi.

* **Customize assets & chains**: Allow and block assets, markets, chains, and protocols from your application from a single config.

## Installation

Install the Actions SDK in your project:

<CodeGroup>
  ```bash npm theme={null}
  npm install @eth-optimism/actions-sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @eth-optimism/actions-sdk
  ```

  ```bash yarn theme={null}
  yarn add @eth-optimism/actions-sdk
  ```

  ```bash bun theme={null}
  bun add @eth-optimism/actions-sdk
  ```

  ```bash deno theme={null}
  deno add @eth-optimism/actions-sdk
  ```
</CodeGroup>

## Choose a Wallet Provider

Actions works with both frontend and backend wallets depending on your needs:

<Tabs>
  <Tab title="Frontend">
    Select a wallet provider:

    <Tabs>
      <Tab title="Privy">
        **Set Up Privy**

        Sign up for Privy and follow the full Privy installation [guide](https://docs.privy.io/basics/react/installation).

        **Configure Wallet Provider**

        Once you have set up Privy embedded wallets, pass them to Actions SDK:

        ```typescript theme={null}
        import { actions } from './config'
        import { useWallets } from '@privy-io/react-auth'

        // PRIVY: Fetch wallet
        const { wallets } = useWallets()
        const embeddedWallet = wallets.find(
          (wallet) => wallet.walletClientType === 'privy',
        )

        // ACTIONS: Let wallet make onchain Actions
        const wallet = await actions.wallet.toActionsWallet({
          connectedWallet: embeddedWallet,
        })
        ```

        **Configure Smart Wallets**

        Optionally, create signers for smart wallets you control:

        ```typescript theme={null}
        import { actions } from './config'
        import { useWallets } from '@privy-io/react-auth'

        // PRIVY: Fetch wallet
        const { wallets } = useWallets()
        const embeddedWallet = wallets.find(
          (wallet) => wallet.walletClientType === 'privy',
        )

        // ACTIONS: Create signer from hosted wallet
        const signer = await actions.wallet.createSigner({
          connectedWallet: embeddedWallet,
        })

        // ACTIONS: Create smart wallet
        const { wallet } = await actions.wallet.createSmartWallet({
          signer: signer
        })
        ```
      </Tab>

      <Tab title="Turnkey">
        **Set Up Turnkey**

        Sign up for Turnkey and follow the full Turnkey installation [guide](https://docs.turnkey.com/sdks/react/getting-started).

        **Configure Wallet Provider**

        Once you have set up Turnkey embedded wallets, pass them to Actions SDK:

        ```typescript theme={null}
        import { useTurnkey, WalletSource } from "@turnkey/react-wallet-kit"
        import { actions, USDC, ExampleMarket } from './config'

        // Fetch Turnkey wallet
        const { wallets, httpClient, session } = useTurnkey()
        const embeddedWallet = wallets.find(
          (wallet) =>
            wallet.accounts.some(
              (account) => account.addressFormat === 'ADDRESS_FORMAT_ETHEREUM',
            ) && wallet.source === WalletSource.Embedded,
        )

        const walletAddress = embeddedWallet.accounts[0].address

        // Convert to Actions wallet
        const wallet = await actions.wallet.toActionsWallet({
          client: httpClient,
          organizationId: session.organizationId,
          signWith: walletAddress,
        })

        // Wallet can now take action
        const receipt = await wallet.lend.openPosition({
          amount: 100,
          asset: USDC,
          ...ExampleMarket
        })
        ```

        **Configure Smart Wallets**

        Optionally, create signers for smart wallets you control:

        ```typescript theme={null}
        import { useTurnkey, WalletSource } from "@turnkey/react-wallet-kit"
        import { actions } from './config'

        // Fetch Turnkey wallet
        const { wallets, httpClient, session } = useTurnkey()
        const embeddedWallet = wallets.find(
          (wallet) =>
            wallet.accounts.some(
              (account) => account.addressFormat === 'ADDRESS_FORMAT_ETHEREUM',
            ) && wallet.source === WalletSource.Embedded,
        )
        const walletAddress = embeddedWallet.accounts[0].address

        // Create signer
        const signer = await actions.wallet.createSigner({
          client: httpClient,
          organizationId: session.organizationId,
          signWith: walletAddress,
        })

        // Create smart wallet
        const { wallet } = await actions.wallet.createSmartWallet({
          signer: signer
        })
        ```
      </Tab>

      <Tab title="Dynamic">
        **Set Up Dynamic**

        Sign up for Dynamic and follow the full Dynamic installation [guide](https://www.dynamic.xyz/docs/wallets/embedded-wallets/mpc/setup).

        **Configure Wallet Provider**

        Once you have set up Dynamic embedded wallets, pass them to Actions SDK:

        ```typescript theme={null}
        import { useDynamicContext } from "@dynamic-labs/sdk-react-core"
        import { actions, USDC, ExampleMarket } from './config'

        // Fetch Dynamic wallet
        const { primaryWallet } = useDynamicContext()

        // Convert to Actions wallet
        const wallet = await actions.wallet.toActionsWallet({
          wallet: primaryWallet,
        })

        // Wallet can now take action
        const receipt = await wallet.lend.openPosition({
          amount: 100,
          asset: USDC,
          ...ExampleMarket
        })
        ```

        **Configure Smart Wallets**

        Optionally, create signers for smart wallets you control:

        ```typescript theme={null}
        import { useDynamicContext } from "@dynamic-labs/sdk-react-core"
        import { actions } from './config'

        // Fetch Dynamic wallet
        const { primaryWallet } = useDynamicContext()

        // Create signer
        const signer = await actions.wallet.createSigner({
          wallet: primaryWallet
        })

        // Create smart wallet
        const { wallet } = await actions.wallet.createSmartWallet({
          signer: signer
        })
        ```
      </Tab>
    </Tabs>
  </Tab>

  <Tab title="Backend">
    Select a wallet provider:

    <Tabs>
      <Tab title="Privy">
        **Set Up Privy**

        Sign up for Privy and follow the full Privy installation [guide](https://docs.privy.io/basics/nodeJS/installation).

        **Configure Wallet Provider**

        Once you have set up Privy embedded wallets, pass them to Actions SDK:

        ```typescript theme={null}
        import { actions } from './config'
        import { PrivyClient } from '@privy-io/node'

        // PRIVY: Create wallet
        const privyClient = new PrivyClient(env.PRIVY_APP_ID, env.PRIVY_APP_SECRET)

        const privyWallet = await privyClient.wallets().create({
          chain_type: 'ethereum',
          owner: { user_id: 'privy:did:xxxxx' },
        })

        // ACTIONS: Let wallet make onchain Actions
        const wallet = await actions.wallet.toActionsWallet({
          walletId: privyWallet.id,
          address: privyWallet.address,
        })
        ```

        **Configure Smart Wallets**

        Optionally, create signers for smart wallets you control:

        ```typescript theme={null}
        import { actions } from './config'
        import { PrivyClient } from '@privy-io/node'
        import { getAddress } from 'viem'

        const privyClient = new PrivyClient(env.PRIVY_APP_ID, env.PRIVY_APP_SECRET)

        // PRIVY: Create wallet
        const privyWallet = await privyClient.wallets().create({
          chain_type: 'ethereum',
          owner: { user_id: 'privy:did:xxxxx' },
        })

        // ACTIONS: Create signer
        const signer = await actions.wallet.createSigner({
          walletId: privyWallet.id,
          address: getAddress(privyWallet.address),
        })

        // ACTIONS: Create smart wallet
        const { wallet } = await actions.wallet.createSmartWallet({
          signer: signer
        })
        ```
      </Tab>

      <Tab title="Turnkey">
        **Set Up Turnkey**

        Sign up for Turnkey and follow the full Turnkey installation [guide](https://docs.turnkey.com/sdks/javascript-server).

        **Configure Wallet Provider**

        Once you have set up Turnkey embedded wallets, pass them to Actions SDK:

        ```typescript theme={null}
        import { Turnkey } from '@turnkey/sdk-server'
        import { actions, USDC, ExampleMarket } from './config'

        const turnkeyClient = new Turnkey({
          apiBaseUrl: 'https://api.turnkey.com',
          apiPublicKey: process.env.TURNKEY_API_KEY,
          apiPrivateKey: process.env.TURNKEY_API_SECRET,
          defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
        })

        // Create Turnkey wallet
        const turnkeyWallet = await turnkeyClient.apiClient().createWallet({
          walletName: 'ETH Wallet',
          accounts: [{
            curve: 'CURVE_SECP256K1',
            pathFormat: 'PATH_FORMAT_BIP32',
            path: "m/44'/60'/0'/0/0",
            addressFormat: 'ADDRESS_FORMAT_ETHEREUM',
          }],
        })

        // Convert to Actions wallet
        const wallet = await actions.wallet.toActionsWallet({
          organizationId: turnkeyWallet.activity.organizationId,
          signWith: turnkeyWallet.addresses[0],
        })

        // Wallet can now take action
        const receipt = await wallet.lend.openPosition({
          amount: 100,
          asset: USDC,
          ...ExampleMarket
        })
        ```

        **Configure Smart Wallets**

        Optionally, create signers for smart wallets you control:

        ```typescript theme={null}
        import { Turnkey } from '@turnkey/sdk-server'
        import { actions } from './config'

        const turnkeyClient = new Turnkey({
          apiBaseUrl: 'https://api.turnkey.com',
          apiPublicKey: process.env.TURNKEY_API_KEY,
          apiPrivateKey: process.env.TURNKEY_API_SECRET,
          defaultOrganizationId: process.env.TURNKEY_ORGANIZATION_ID,
        })

        // Create Turnkey wallet
        const turnkeyWallet = await turnkeyClient.apiClient().createWallet({
          walletName: 'ETH Wallet',
          accounts: [{
            curve: 'CURVE_SECP256K1',
            pathFormat: 'PATH_FORMAT_BIP32',
            path: "m/44'/60'/0'/0/0",
            addressFormat: 'ADDRESS_FORMAT_ETHEREUM',
          }],
        })

        // Create signer
        const signer = await actions.wallet.createSigner({
          organizationId: turnkeyWallet.activity.organizationId,
          signWith: turnkeyWallet.addresses[0],
        })

        // Create smart wallet
        const { wallet } = await actions.wallet.createSmartWallet({
          signer: signer
        })
        ```
      </Tab>
    </Tabs>
  </Tab>
</Tabs>

## Create your ActionsConfig

Follow the [Configuring Actions](/app-developers/guides/configuring-actions) guide to define which protocols, chains, and assets to support.

## Take Action

Once configured, you can use Actions to perform DeFi operations:

```typescript theme={null}
import { USDC, ETH, USDT } from "@eth-optimism/actions-sdk/assets";
import { ExampleMarket } from "@/actions/markets";

// Enable asset lending in DeFi
const lendReceipt = await wallet.lend.openPosition({
  amount: 1,
  asset: USDC,
  ...ExampleMarket,
});

// Manage user market positions
const lendPosition = await wallet.lend.getPosition(market);

// Fetch wallet balance
const balance = await wallet.getBalance();

// ⚠️ COMING SOON
const borrowReceipt = await wallet.borrow.openPosition({
  amount: 1,
  asset: USDT,
  ...market,
});

// ⚠️ COMING SOON
const swapReceipt = await wallet.swap.execute({
  amountIn: 1,
  assetIn: USDC,
  assetOut: ETH,
});

// ⚠️ COMING SOON
const sendReceipt = await wallet.send({
  amount: 1,
  asset: USDC,
  to: "vitalik.eth",
});
```

## Next Steps

* [Configure Actions](/app-developers/guides/configuring-actions) to customize protocols, chains, and assets
* Check out the [Actions demo](https://actions.money/earn) for a complete example application


# App developer quickstart
Source: https://docs.optimism.io/app-developers/quickstarts/get-started

Get testnet ETH, deploy your first contract to OP Sepolia, and bridge assets - your first steps on the Superchain.

OP Stack chains are [EVM equivalent](/op-stack/protocol/differences): everything you know from Ethereum works here, and everything you build here works across the OP Stack ecosystem.
This quickstart takes you from zero to a deployed contract on the OP Sepolia testnet, using only free testnet funds.

<Info>
  No real funds are needed at any point — everything below runs on testnets.
</Info>

## Before you start

You'll need:

* A wallet you control (any EVM wallet works; you'll export or generate a private key for testnet use only).
* A terminal with `curl` available.

<Warning>
  Use a fresh, testnet-only private key for tutorials. Never paste a key that holds real funds into a terminal.
</Warning>

<Steps>
  <Step title="Get testnet ETH">
    Grab free OP Sepolia ETH from the [Superchain Faucet](https://console.optimism.io/faucet).
    Other options are listed on the [testnet faucets page](/app-developers/tools-sdks/faucets).
  </Step>

  <Step title="Connect to OP Sepolia">
    OP Sepolia's public RPC endpoint is `https://sepolia.optimism.io` and its chain ID is `11155420`.
    Verify you can reach it:

    ```bash theme={null}
    curl -s -X POST -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
      https://sepolia.optimism.io
    ```

    Expected result: `{"jsonrpc":"2.0","id":1,"result":"0xaa37dc"}` (`0xaa37dc` = 11155420).
    For other networks and production-grade endpoints, see [network information](/op-mainnet/network-information/connecting-to-op) and [RPC providers](/app-developers/reference/rpc-providers).
  </Step>

  <Step title="Deploy your first contract">
    Follow the [Deploy a contract to OP Sepolia](/app-developers/tutorials/deploy-a-contract) tutorial.
    It walks you through installing Foundry, deploying a small `Greeter` contract, and reading and writing to it from the command line — the same workflow you'd use on Ethereum.
  </Step>

  <Step title="Bridge ETH between L1 and L2 (optional)">
    Apps often need to move assets between Ethereum and an OP Stack chain.
    Start with [Bridging basics](/app-developers/guides/bridging/basics) to understand the model, then follow the [Bridging ETH with Viem](/app-developers/tutorials/bridging/cross-dom-bridge-eth) tutorial to do a Sepolia → OP Sepolia deposit programmatically.
  </Step>
</Steps>

## Where to go next

<CardGroup>
  <Card title="Build apps on OP Stack chains" href="/app-developers/guides/building-apps">
    Development workflow, tooling, and what (little) is different from Ethereum.
  </Card>

  <Card title="Test your apps" href="/app-developers/guides/testing-apps">
    Test against OP Stack chains locally and in CI.
  </Card>

  <Card title="Go cross-chain with interop" href="/app-developers/guides/interoperability/get-started">
    Build apps that span multiple Superchain chains.
  </Card>

  <Card title="Integrate DeFi with the Actions SDK" href="/app-developers/quickstarts/actions">
    Lend, borrow, and swap with lightweight, type-safe modules (early preview — not production-ready).
  </Card>
</CardGroup>

<Info>
  **Running your app in production**

  A production application depends on infrastructure your team does not run: RPC endpoints that hold up under real traffic (the public endpoints are rate-limited and not built for production), bridges your users rely on, and a chain whose operator keeps sequencing, upgrades, and incident response going around the clock. These docs cover building and testing. If your application is growing toward dedicated blockspace of its own, [OP Enterprise](https://optimism.io/op-enterprise?utm_source=docs\&utm_medium=docs\&utm_campaign=op-enterprise) offers managed and supported paths to running a chain. These docs stay the reference for what you build either way. OP Enterprise is Optimism's managed offering.
</Info>

## Need help?

* Ask a question or report documentation issues on the [Optimism monorepo issue tracker](https://github.com/ethereum-optimism/optimism/issues).


# Integrating wallets
Source: https://docs.optimism.io/app-developers/reference/actions/integrating-wallets

Understand the wallet options Actions SDK supports, embedded wallet providers, gas sponsorship, and smart wallets.

## Which wallets are right for my use case?

In order to let your users access DeFi, they will need an <Tooltip href="https://ethereum.org/developers/docs/evm/">EVM</Tooltip>-compatible wallet. There are plenty of considerations when selecting a wallet schema that works for you:

* Who will maintain custody of funds?
* What permissions must exist for my use case?
* Where in my stack should transaction signatures originate?
* How can my users on and off ramp funds?

Actions SDK supports popular [embedded wallet providers](#embedded-wallet-providers) to address all of these questions while remaining flexible to your use case.

## Embedded Wallet Providers

Embedded wallet providers give your users the ability to sign onchain transactions through your app's existing email authentication and authorization flows.

Actions works with:

<CardGroup>
  <Card title="Privy" href="https://www.privy.io/" icon="https://mintcdn.com/optimism-373f39ad/9zyR2ZwcL-ncDc-N/public/img/actions/Privy.png?fit=max&auto=format&n=9zyR2ZwcL-ncDc-N&q=85&s=72e628e7c7e8804636d7edc65092e06c" />

  <Card title="Turnkey" href="https://www.turnkey.com/" icon="https://mintcdn.com/optimism-373f39ad/9zyR2ZwcL-ncDc-N/public/img/actions/turnkey.png?fit=max&auto=format&n=9zyR2ZwcL-ncDc-N&q=85&s=d963f9d75de9fcb9ad69c38acf61f0b1" />

  <Card title="Dynamic" href="https://www.dynamic.xyz/" icon="https://mintcdn.com/optimism-373f39ad/9zyR2ZwcL-ncDc-N/public/img/actions/dynamic.png?fit=max&auto=format&n=9zyR2ZwcL-ncDc-N&q=85&s=a34b37a0f6b1866583200bef641864f1" />
</CardGroup>

## Gas Sponsorship

Signing and sending onchain transactions requires gas, or fee payment, which adds [additional overhead](/app-developers/guides/transactions/estimates) for you and friction for users.

Actions supports gas sponsorship via a combination of smart contract wallets and [paymasters](https://eips.ethereum.org/EIPS/eip-7677). First, configure a paymaster in the chain config by specifying a bundler url. Now, any transactions submitted via an actions SmartWallet on that chain will automatically use your paymaster, therefore eliminating the need for the wallet to pay gas.

## Connect your wallet to Actions

Regardless of where and how transactions are signed, Actions has you covered.
Once you've chosen a wallet provider, follow the guide on [connecting a wallet to Actions SDK](/app-developers/guides/connect-wallet-to-actions) to pass the provider wallet to Actions and start calling Actions functions like Lend, Borrow, Swap, and Pay.

## Smart wallets & signers

In addition to using embedded provider wallets directly, Actions [supports the creation](/app-developers/quickstarts/actions#choose-a-wallet-provider) of custom smart contract wallets. This additional wallet type is separate from, but still controlled by the owner of the embedded wallet.

If you [configure it](/app-developers/guides/configuring-actions), Actions will deploy a [EIP-4337](https://eips.ethereum.org/EIPS/eip-4337) compliant [Coinbase Smart Wallets](https://github.com/coinbase/smart-wallet) on the chains you've chosen to support.

Once created, an embedded wallet can be added as a signer on the smart wallet, capable of signing transactions on behalf of the Smart Wallet.

See [Wallet Documentation](/app-developers/reference/actions/wallet-definitions) for additional details.


# Lend Documentation
Source: https://docs.optimism.io/app-developers/reference/actions/lend-documentation

API reference for Actions SDK lending operations, functions, and parameters.

## WalletLendNamespace

Wallet Lend Namespace

### Methods

| Function                                      | Description                                              |
| --------------------------------------------- | -------------------------------------------------------- |
| **[getMarkets()](#getmarkets)**               | Get all markets across all configured providers          |
| **[getMarket()](#getmarket)**                 | Get a specific market by routing to the correct provider |
| **[supportedChainIds()](#supportedchainids)** | Get supported chain IDs across all providers             |
| **[openPosition()](#openposition)**           | Open a lending position                                  |
| **[getPosition()](#getposition)**             | Get position information for this wallet                 |
| **[closePosition()](#closeposition)**         | Close a lending position (withdraw from market)          |

#### `getMarkets()`

Get all markets across all configured providers

| Parameter | Type                   | Description                   |
| --------- | ---------------------- | ----------------------------- |
| `params`  | `GetLendMarketsParams` | Optional filtering parameters |

**Returns:** Promise resolving to array of markets from all providers

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/lend/namespaces/BaseLendNamespace.ts#L25)</sub>

***

#### `getMarket()`

Get a specific market by routing to the correct provider

| Parameter | Type                  | Description       |
| --------- | --------------------- | ----------------- |
| `params`  | `GetLendMarketParams` | Market identifier |

**Returns:** Promise resolving to market information

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/lend/namespaces/BaseLendNamespace.ts#L37)</sub>

***

#### `supportedChainIds()`

Get supported chain IDs across all providers

**Returns:** Array of unique chain IDs supported by any provider

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/lend/namespaces/BaseLendNamespace.ts#L46)</sub>

***

#### `openPosition()`

Open a lending position

| Parameter         | Type                     | Description                           |
| ----------------- | ------------------------ | ------------------------------------- |
| `params`          | `LendOpenPositionParams` | Lending position parameters           |
| `params.marketId` |                          | Market identifier to open position in |
| `params.amount`   | `number`                 | Amount to lend                        |

**Returns:** Promise resolving to transaction receipt

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/lend/namespaces/WalletLendNamespace.ts#L34)</sub>

***

#### `getPosition()`

Get position information for this wallet

| Parameter         | Type                | Description                      |
| ----------------- | ------------------- | -------------------------------- |
| `params`          | `GetPositionParams` | Position query parameters        |
| `params.marketId` | `LendMarketId`      | Market identifier (required)     |
| `params.asset`    | `Asset`             | Asset filter (not yet supported) |

**Returns:** Promise resolving to position information

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/lend/namespaces/WalletLendNamespace.ts#L54)</sub>

***

#### `closePosition()`

Close a lending position (withdraw from market)

| Parameter         | Type                  | Description                            |
| ----------------- | --------------------- | -------------------------------------- |
| `params`          | `ClosePositionParams` | Position closing parameters            |
| `params.marketId` | `LendMarketId`        | Market identifier to close position in |
| `params.amount`   | `number`              | Amount to withdraw                     |

**Returns:** Promise resolving to transaction receipt

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/lend/namespaces/WalletLendNamespace.ts#L75)</sub>

***


# Swap Documentation
Source: https://docs.optimism.io/app-developers/reference/actions/swap-documentation

API reference for Actions SDK swap operations, functions, and parameters.

## WalletSwapNamespace

Wallet swap namespace with full operations including signing.
Provides getQuote() for pricing and execute() for swapping tokens.

### Methods

| Function                                      | Description                                                                                                                |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **[getQuote()](#getquote)**                   | Get a swap quote with the wallet address as recipient. Ensures calldata is encoded for the real wallet, not a placeholder. |
| **[getQuotes()](#getquotes)**                 | Get quotes from all providers with the wallet address as recipient.                                                        |
| **[getMarket()](#getmarket)**                 | Get a specific swap market by ID.                                                                                          |
| **[getMarkets()](#getmarkets)**               | Get available swap markets across all providers                                                                            |
| **[supportedChainIds()](#supportedchainids)** | Get all supported chain IDs across all providers                                                                           |
| **[execute()](#execute)**                     | Execute a token swap. Accepts either raw params (re-quotes internally) or a pre-built SwapQuote (skips re-quoting).        |

#### `getQuote()`

Get a swap quote with the wallet address as recipient.
Ensures calldata is encoded for the real wallet, not a placeholder.

| Parameter | Type              | Description |
| --------- | ----------------- | ----------- |
| `params`  | `SwapQuoteParams` |             |

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/swap/namespaces/WalletSwapNamespace.ts#L32)</sub>

***

#### `getQuotes()`

Get quotes from all providers with the wallet address as recipient.

| Parameter | Type              | Description |
| --------- | ----------------- | ----------- |
| `params`  | `SwapQuoteParams` |             |

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/swap/namespaces/WalletSwapNamespace.ts#L42)</sub>

***

#### `getMarket()`

Get a specific swap market by ID.

| Parameter  | Type                  | Description                                                       |
| ---------- | --------------------- | ----------------------------------------------------------------- |
| `params`   | `GetSwapMarketParams` | Market identifier (poolId + chainId)                              |
| `provider` | `SwapProviderName`    | Optional provider name to query directly instead of searching all |

**Returns:** Market information

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/swap/namespaces/BaseSwapNamespace.ts#L145)</sub>

***

#### `getMarkets()`

Get available swap markets across all providers

| Parameter | Type                   | Description                            |
| --------- | ---------------------- | -------------------------------------- |
| `params`  | `GetSwapMarketsParams` | Optional filtering by chainId or asset |

**Returns:** Promise resolving to array of markets from all providers

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/swap/namespaces/BaseSwapNamespace.ts#L174)</sub>

***

#### `supportedChainIds()`

Get all supported chain IDs across all providers

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/swap/namespaces/BaseSwapNamespace.ts#L184)</sub>

***

#### `execute()`

Execute a token swap.
Accepts either raw params (re-quotes internally) or a pre-built SwapQuote (skips re-quoting).

| Parameter | Type               | Description |                                                          |
| --------- | ------------------ | ----------- | -------------------------------------------------------- |
| `params`  | \`WalletSwapParams | SwapQuote\` | Swap parameters or a pre-built SwapQuote from getQuote() |

**Returns:** Swap receipt with transaction details

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/swap/namespaces/WalletSwapNamespace.ts#L55)</sub>

***


# Wallet Documentation
Source: https://docs.optimism.io/app-developers/reference/actions/wallet-definitions

API reference for Actions SDK wallet classes, functions, and parameters.

## WalletNamespace

Wallet namespace that provides unified wallet operations

### Methods

| Function                                            | Description                                              |
| --------------------------------------------------- | -------------------------------------------------------- |
| **[hostedWalletProvider()](#hostedwalletprovider)** | Get direct access to the hosted wallet provider          |
| **[smartWalletProvider()](#smartwalletprovider)**   | Get direct access to the smart wallet provider           |
| **[createSmartWallet()](#createsmartwallet)**       | Create a new smart wallet                                |
| **[createSigner()](#createsigner)**                 | Create a viem LocalAccount signer from the hosted wallet |
| **[toActionsWallet()](#toactionswallet)**           | Convert a hosted wallet to an Actions wallet             |
| **[getSmartWallet()](#getsmartwallet)**             | Get an existing smart wallet with a provided signer      |

#### `hostedWalletProvider()`

Get direct access to the hosted wallet provider

**Returns:** Promise resolving to the configured hosted wallet provider instance

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/namespace/WalletNamespace.ts#L86)</sub>

***

#### `smartWalletProvider()`

Get direct access to the smart wallet provider

**Returns:** Promise resolving to the configured smart wallet provider instance

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/namespace/WalletNamespace.ts#L98)</sub>

***

#### `createSmartWallet()`

Create a new smart wallet

| Parameter                                                             | Type                       | Description                                                        |
| --------------------------------------------------------------------- | -------------------------- | ------------------------------------------------------------------ |
| `params`                                                              | `CreateSmartWalletOptions` | Smart wallet creation parameters                                   |
| `params.signer`                                                       | `LocalAccount`             | Primary local account used for signing transactions                |
| `params.signers`                                                      | `Signer[]`                 | Optional array of additional signers for the smart wallet          |
| `params.nonce`                                                        | `bigint`                   | Optional nonce for smart wallet address generation (defaults to 0) |
| `params.deploymentChainIds`                                           | `SupportedChainId[]`       | Optional chain IDs to deploy the wallet to.                        |
| If not provided, the wallet will be deployed to all supported chains. |                            |                                                                    |

**Returns:** Promise resolving to deployment result containing:

* `wallet`: The created SmartWallet instance
* `deployments`: Array of deployment results with chainId, receipt, success flag, and error

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/namespace/WalletNamespace.ts#L120)</sub>

***

#### `createSigner()`

Create a viem LocalAccount signer from the hosted wallet

| Parameter | Type                                 | Description                  |
| --------- | ------------------------------------ | ---------------------------- |
| `params`  | `TToActionsMap[THostedProviderType]` | Configuration for the signer |

**Returns:** Promise resolving to a viem `LocalAccount` with the hosted wallet as the signer backend

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/namespace/WalletNamespace.ts#L136)</sub>

***

#### `toActionsWallet()`

Convert a hosted wallet to an Actions wallet

| Parameter         | Type                                 | Description                                                    |
| ----------------- | ------------------------------------ | -------------------------------------------------------------- |
| `params`          | `TToActionsMap[THostedProviderType]` | Parameters for converting a hosted wallet to an Actions wallet |
| `params.walletId` |                                      | Unique identifier for the hosted wallet                        |
| `params.address`  |                                      | Ethereum address of the hosted wallet                          |

**Returns:** Promise resolving to the Actions wallet instance

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/namespace/WalletNamespace.ts#L151)</sub>

***

#### `getSmartWallet()`

Get an existing smart wallet with a provided signer

| Parameter                  | Type                    | Description                                                        |
| -------------------------- | ----------------------- | ------------------------------------------------------------------ |
| `params`                   | `GetSmartWalletOptions` | Wallet retrieval parameters                                        |
| `params.signer`            | `LocalAccount`          | Local account to use for signing transactions on the smart wallet  |
| `params.signers`           | `Signer[]`              | Optional array of additional signers for the smart wallet          |
| `params.deploymentSigners` | `Signer[]`              | Optional array of signers used during wallet deployment            |
| `params.walletAddress`     | `Address`               | Optional explicit smart wallet address (skips address calculation) |
| `params.nonce`             | `bigint`                | Optional nonce used during smart wallet creation                   |

**Returns:** Promise resolving to the smart wallet instance with the provided signer

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/namespace/WalletNamespace.ts#L173)</sub>

***

## Wallet

Base actions wallet class

### Namespaces

| Namespace | Type                  | Description                                |
| --------- | --------------------- | ------------------------------------------ |
| `lend`    | `WalletLendNamespace` | Lend namespace with all lending operations |
| `swap`    | `WalletSwapNamespace` | Swap namespace with all swap operations    |

### Properties

| Property  | Type           | Description                            |
| --------- | -------------- | -------------------------------------- |
| `address` | `Address`      | Get the address of this actions wallet |
| `signer`  | `LocalAccount` | Get a signer for this actions wallet   |

### Methods

| Function                        | Description                                            |
| ------------------------------- | ------------------------------------------------------ |
| **[getBalance()](#getbalance)** | Get asset balances across all supported chains         |
| **[send()](#send)**             | Send a transaction using this actions wallet           |
| **[sendBatch()](#sendbatch)**   | Send a batch of transactions using this actions wallet |

#### `getBalance()`

Get asset balances across all supported chains

**Returns:** Promise resolving to array of token balances with chain breakdown

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/wallets/abstract/Wallet.ts#L89)</sub>

***

#### `send()`

Send a transaction using this actions wallet

| Parameter         | Type               | Description                     |
| ----------------- | ------------------ | ------------------------------- |
| `transactionData` | `TransactionData`  | The transaction data to execute |
| `chainId`         | `SupportedChainId` | Target blockchain chain ID      |

**Returns:** Promise resolving to the transaction hash

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/wallets/abstract/Wallet.ts#L150)</sub>

***

#### `sendBatch()`

Send a batch of transactions using this actions wallet

| Parameter         | Type                | Description                     |
| ----------------- | ------------------- | ------------------------------- |
| `transactionData` | `TransactionData[]` | The transaction data to execute |
| `chainId`         | `SupportedChainId`  | Target blockchain chain ID      |

**Returns:** Promise resolving to the transaction hash

<sub>[<Icon icon="github" /> Source ↗](https://github.com/ethereum-optimism/actions/blob/@eth-optimism/actions-sdk@0.4.0/packages/sdk/src/wallet/core/wallets/abstract/Wallet.ts#L162)</sub>

***


# Interoperability predeploys
Source: https://docs.optimism.io/app-developers/reference/contracts/interop/predeploy

Learn how interoperability predeploys work.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>
The following predeploys have been added to enable interoperability.
*Predeployed smart contracts* exist at predetermined addresses, coming from the genesis state.
They're similar to [precompiles](https://www.evm.codes/precompiled) but run directly in the EVM instead of running as native code.

## CrossL2Inbox

The `CrossL2Inbox` is the system predeploy for cross chain messaging.
Anyone can trigger the execution or validation of cross chain messages, on behalf of any user.

* **Address:** `0x4200000000000000000000000000000000000022`
* **Specs:** [`CrossL2Inbox`](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#crossl2inbox)
* **Source code:** [`CrossL2Inbox`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol)

## L2ToL2CrossDomainMessenger

The `L2ToL2CrossDomainMessenger` is a higher level abstraction on top of the `CrossL2Inbox` that provides general message passing.
It's utilized for secure ERC20 token transfers between L2 chains.
Messages sent through the `L2ToL2CrossDomainMessenger` on the source chain receive both replay protection and domain binding (the executing transaction can only be valid on a single chain).

* **Address:** `0x4200000000000000000000000000000000000023`
* **Specs:** [`L2ToL2CrossDomainMessenger`](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#l2tol2crossdomainmessenger)
* **Source code:** [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol)

## SuperchainETHBridge

The `SuperchainETHBridge` is a predeploy contract that facilitates cross-chain ETH bridging within the OP Stack interop cluster. It serves as an abstraction layer on top of the `L2ToL2CrossDomainMessenger` specifically designed for native ETH transfers between chains. The contract integrates with the `ETHLiquidity` contract to manage native ETH liquidity across chains, ensuring seamless cross-chain transfers of native ETH.

* **Address:** `0x4200000000000000000000000000000000000024`
* **Specs:** [`SuperchainETHBridge`](https://specs.optimism.io/interop/superchain-eth-bridge.html)
* **Source code:** [`SuperchainETHBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainETHBridge.sol)

## ETHLiquidity

The `ETHLiquidity` contract is a predeploy that manages native ETH liquidity for cross-chain transfers within the OP Stack interop set. It works in conjunction with the `SuperchainETHBridge` to facilitate the movement of ETH between chains without requiring modifications to the EVM to generate new ETH.

The contract is initialized with a very large balance (type(uint248).max wei) to ensure it can handle all legitimate minting operations. This design allows the `SuperchainETHBridge` to have a guaranteed source of ETH liquidity on each chain, which is essential for the cross-chain ETH transfer mechanism.

* **Address:** `0x4200000000000000000000000000000000000025`
* **Specs:** [`ETHLiquidity`](https://specs.optimism.io/interop/eth-liquidity.html)
* **Source code:** [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol)

## SuperchainTokenBridge

The `SuperchainTokenBridge` is an abstraction on top of the `L2ToL2CrossDomainMessenger` that facilitates token bridging using interop, as described in the [token bridging spec](https://specs.optimism.io/interop/token-bridging.html).

* **Address:** `0x4200000000000000000000000000000000000028`
* **Specs:** [`SuperchainTokenBridge`](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#superchaintokenbridge)
* **Source code:** [`SuperchainTokenBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainTokenBridge.sol)

## Next steps

* Learn [how messages get from one chain to another chain](/app-developers/guides/interoperability/message-passing)


# OP Stack RPC directory
Source: https://docs.optimism.io/app-developers/reference/rpc-providers

Find public RPC endpoints and production RPC providers across all OP Stack networks.

This directory provides developers with a comprehensive collection of RPC endpoints across all OP Stack networks, making it easier to build, deploy, and scale applications on the OP Stack ecosystem.

## Public RPC endpoints

The following table lists public RPC endpoints for all OP Stack networks. These endpoints are **rate-limited and not suitable for production use**, but are perfect for development, testing, and proof-of-concept work.
For production use, please see the [Production RPC Providers](#production-rpc-providers) section below.

<Tabs>
  <Tab title="Mainnet">
    | Chain      | Public RPC URL                                                                                     | Documentation                                                                         |
    | ---------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
    | OP Mainnet | [https://mainnet.optimism.io](https://mainnet.optimism.io)                                         | [Docs](https://docs.optimism.io/superchain/networks)                                  |
    | Base       | [https://mainnet.base.org](https://mainnet.base.org)                                               | [Docs](https://docs.base.org/chain/network-information)                               |
    | Ink        | [https://rpc-gel.inkonchain.com](https://rpc-gel.inkonchain.com)                                   | [Docs](https://docs.inkonchain.com/general/network-information)                       |
    | Unichain   | [https://mainnet.unichain.org](https://mainnet.unichain.org)                                       | [Docs](https://docs.unichain.org/docs/technical-information/network-information)      |
    | Soneium    | [https://rpc.soneium.org/](https://rpc.soneium.org/)                                               | [Docs](https://docs.soneium.org/docs/builders/overview)                               |
    | Mode       | [https://mainnet.mode.network/](https://mainnet.mode.network/)                                     | [Docs](https://docs.mode.network/user-guides/network-details)                         |
    | Zora       | [https://rpc.zora.energy](https://rpc.zora.energy)                                                 | [Docs](https://docs.zora.co/zora-network/network)                                     |
    | Swell      | [https://swell-mainnet.alt.technology](https://swell-mainnet.alt.technology)                       | [Docs](https://build.swellnetwork.io/docs/guides/getting-started)                     |
    | Arena-Z    | [https://rpc.arena-z.gg](https://rpc.arena-z.gg)                                                   | [Docs](https://raas.gelato.network/rollups/details/public/arena-z)                    |
    | Metal      | [https://rpc.metall2.com](https://rpc.metall2.com)                                                 | [Docs](https://docs.metall2.com/chain/networks)                                       |
    | World      | [https://worldchain-mainnet.g.alchemy.com/public](https://worldchain-mainnet.g.alchemy.com/public) | [Docs](https://docs.world.org/world-chain/quick-start/info)                           |
    | Lisk       | [https://rpc.api.lisk.com](https://rpc.api.lisk.com)                                               | [Docs](https://docs.lisk.com/network-info/)                                           |
    | Polynomial | [https://rpc.polynomial.fi](https://rpc.polynomial.fi)                                             | [Docs](https://docs.polynomial.fi/links)                                              |
    | Mint       | [https://rpc.mintchain.io](https://rpc.mintchain.io)                                               | [Docs](https://docs.mintchain.io/build/network)                                       |
    | Superseed  | [https://mainnet.superseed.xyz](https://mainnet.superseed.xyz)                                     | [Docs](https://docs.superseed.xyz/build-on-superseed/network-information)             |
    | Shape      | [https://mainnet.shape.network](https://mainnet.shape.network)                                     | [Docs](https://docs.shape.network/technical-details/network-information)              |
    | Epic       | [https://mainnet.ethernitychain.io](https://mainnet.ethernitychain.io)                             | [Docs](https://docs.ethernity.io/introduction/network-information)                    |
    | Race       | [https://racemainnet.io](https://racemainnet.io)                                                   | [Docs](https://raceecosystem.gitbook.io/docs/building-on-race-tm/network-information) |
    | BoB        | [https://rpc.gobob.xyz/](https://rpc.gobob.xyz/)                                                   | [Docs](https://docs.gobob.xyz/learn/user-guides/getting-started/networks)             |
  </Tab>

  <Tab title="Testnet">
    | Chain              | Public RPC URL                                                                                     | Documentation                                                                         |
    | ------------------ | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
    | OP Sepolia         | [https://sepolia.optimism.io](https://sepolia.optimism.io)                                         | [Docs](https://docs.optimism.io/superchain/networks)                                  |
    | Base Sepolia       | [https://sepolia.base.org](https://sepolia.base.org)                                               | [Docs](https://docs.base.org/chain/network-information)                               |
    | Ink Sepolia        | [https://rpc-gel-sepolia.inkonchain.com](https://rpc-gel-sepolia.inkonchain.com)                   | [Docs](https://docs.inkonchain.com/general/network-information)                       |
    | Unichain Sepolia   | [https://sepolia.unichain.org](https://sepolia.unichain.org)                                       | [Docs](https://docs.unichain.org/docs/technical-information/network-information)      |
    | Soneium Sepolia    | [https://rpc.minato.soneium.org/](https://rpc.minato.soneium.org/)                                 | [Docs](https://docs.soneium.org/docs/builders/overview)                               |
    | Mode Sepolia       | [https://sepolia.mode.network](https://sepolia.mode.network)                                       | [Docs](https://docs.mode.network/user-guides/network-details)                         |
    | Zora Sepolia       | [https://sepolia.rpc.zora.energy](https://sepolia.rpc.zora.energy)                                 | [Docs](https://docs.zora.co/zora-network/network)                                     |
    | Swell Sepolia      | [https://swell-testnet.alt.technology](https://swell-testnet.alt.technology)                       | [Docs](https://build.swellnetwork.io/docs/guides/getting-started)                     |
    | Arena-Z Testnet    | [https://rpc.arena-z.t.raas.gelato.cloud](https://rpc.arena-z.t.raas.gelato.cloud)                 | [Docs](https://raas.gelato.network/rollups/details/public/arena-z)                    |
    | Metal Testnet      | [https://testnet.rpc.metall2.com/](https://testnet.rpc.metall2.com/)                               | [Docs](https://docs.metall2.com/chain/networks)                                       |
    | World Sepolia      | [https://worldchain-sepolia.g.alchemy.com/public](https://worldchain-sepolia.g.alchemy.com/public) | [Docs](https://docs.world.org/world-chain/quick-start/info)                           |
    | Lisk Sepolia       | [https://rpc.sepolia-api.lisk.com](https://rpc.sepolia-api.lisk.com)                               | [Docs](https://docs.lisk.com/network-info/)                                           |
    | Polynomial Sepolia | [https://rpc.sepolia.polynomial.fi](https://rpc.sepolia.polynomial.fi)                             | [Docs](https://docs.polynomial.fi/links)                                              |
    | Mint Sepolia       | [https://sepolia-testnet-rpc.mintchain.io](https://sepolia-testnet-rpc.mintchain.io)               | [Docs](https://docs.mintchain.io/build/network)                                       |
    | Superseed Sepolia  | [https://sepolia.superseed.xyz](https://sepolia.superseed.xyz)                                     | [Docs](https://docs.superseed.xyz/build-on-superseed/network-information)             |
    | Shape Sepolia      | [https://sepolia.shape.network](https://sepolia.shape.network)                                     | [Docs](https://docs.shape.network/technical-details/network-information)              |
    | Epic Testnet       | [https://testnet.ethernitychain.io](https://testnet.ethernitychain.io)                             | [Docs](https://docs.ethernity.io/introduction/network-information)                    |
    | Race Testnet       | [https://racetestnet.io](https://racetestnet.io)                                                   | [Docs](https://raceecosystem.gitbook.io/docs/building-on-race-tm/network-information) |
    | BoB Sepolia        | [https://sepolia.rpc.gobob.xyz/](https://sepolia.rpc.gobob.xyz/)                                   | [Docs](https://docs.gobob.xyz/learn/user-guides/getting-started/networks)             |
  </Tab>
</Tabs>

## Production RPC providers

The following providers offer production-grade RPC access to OP Stack networks. Most providers offer both free tiers with higher rate limits than public RPCs and paid plans for production applications.

### 1RPC

**Description**: [1RPC](https://www.1rpc.io/) offers [free and paid plans](https://www.1rpc.io/#pricing) for the following [networks](https://docs.1rpc.io/using-the-web3-api/networks):

**Supported Testnets**: Mode Sepolia, World Sepolia

**Supported Mainnets**: OP Mainnet, Mode, Base

### Ankr

**Description**: [Ankr](https://www.ankr.com/) offers [free and paid plans](https://www.ankr.com/rpc/pricing/) for the following [networks](https://www.ankr.com/rpc/):

**Supported Testnets**: OP Sepolia, Swell Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Swell, Base

### Alchemy

**Description**: [Alchemy](https://www.alchemy.com/) offers [free and paid plans](https://www.alchemy.com/pricing) for the following [networks](https://docs.alchemy.com/reference/api-overview):

**Supported Testnets**: OP Sepolia, Ink Sepolia, Unichain Sepolia, Soneium Sepolia, Base Sepolia, World Sepolia, Shape Sepolia

**Supported Mainnets**: OP Mainnet, Ink, Unichain, Soneium, Base, World, Shape

### All That Node

**Description**: [All That Node](https://www.allthatnode.com/) offers [free and paid plans](https://www.allthatnode.com/pricing.dsrv) for the following [networks](https://docs.allthatnode.com/docs/supported-protocols-1):

**Supported Testnets**: OP Sepolia

**Supported Mainnets**: OP Mainnet, Base

### Blast

**Description**: [Blast](https://blastapi.io/) offers [free and paid plans](https://blastapi.io/pricing) for the following [networks](https://blastapi.io/chains):

**Supported Testnets**: OP Sepolia, Mode Sepolia, Base Sepolia, BoB Sepolia

**Supported Mainnets**: OP Mainnet, Mode, Base, BoB

### Blockdaemon

**Description**: [Blockdaemon](https://www.blockdaemon.com/) offers [free and paid plans](https://www.blockdaemon.com/api/pricing) for the following [networks](https://www.blockdaemon.com/protocols):

**Supported Testnets**: OP Sepolia, Unichain Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Unichain, Base

### BlockPI

**Description**: [BlockPI](https://blockpi.io/) offers [free and paid plans](https://blockpi.io/pricing) for the following [networks](https://blockpi.io/chains):

**Supported Testnets**: OP Sepolia, Unichain Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Unichain, Base

### Chainstack

**Description**: [Chainstack](https://chainstack.com/) offers [free and paid plans](https://chainstack.com/pricing/) for the following [networks](https://chainstack.com/protocols/):

**Supported Testnets**: OP Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Base

### dRPC NodeCloud

**Description**: [dRPC](https://drpc.org/nodecloud-multichain-rpc-management) offers [free and paid plans](https://drpc.org/pricing) for the following [networks](https://drpc.org/chainlist):

**Supported Testnets**: OP Sepolia, Ink Sepolia, Unichain Sepolia, Soneium Sepolia, Mode Sepolia, Zora Sepolia, Swell Sepolia, Metal Sepolia, Base Sepolia, World Sepolia, Lisk Sepolia, Superseed Sepolia, BoB Sepolia

**Supported Mainnets**: OP Mainnet, Ink, Unichain, Soneium, Mode, Zora, Swell, Metal, Base, World, Lisk, Superseed, BoB

### GetBlock

**Description**: [GetBlock](https://getblock.io/) offers [free and paid plans](https://getblock.io/pricing/) for the following [networks](https://docs.getblock.io/api-reference/overview#supported-networks):

**Supported Testnets**: OP Sepolia

**Supported Mainnets**: OP Mainnet

### Grove

**Description**: [Grove](https://grove.city/) offers [free and paid plans](https://www.grove.city/pricing) for the following [networks](https://www.grove.city/services):

**Supported Testnets**: OP Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Base Mainnet, Ink Mainnet

### Infura

**Description**: [Infura](https://infura.io) offers [free and paid plans](https://www.infura.io/pricing) for the following [networks](https://www.infura.io/networks):

**Supported Testnets**: OP Sepolia, Unichain Sepolia, Swell Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Unichain, Swell, Base

### Moralis

**Description**: [Moralis](https://moralis.io) offers [free and paid plans](https://developers.moralis.com/pricing/) for the following [networks](https://developers.moralis.com/chains/):

**Supported Testnets**: OP Sepolia, Base Sepolia, Lisk Sepolia

**Supported Mainnets**: OP Mainnet, Base, Lisk

### Nodies DLB

**Description**: [Nodies DLB](https://www.nodies.app/) offers [free and paid plans](https://www.nodies.app/pricing) for the following [networks](https://docs.nodies.app/overview/supported-blockchains):

**Supported Testnets**: OP Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Ink, Base

### NOWNodes

**Description**: [NOWNodes](https://nownodes.io/) offers [free and paid plans](https://nownodes.io/pricing) for the following [networks](https://nownodes.io/nodes):

**Supported Testnets**: n/a

**Supported Mainnets**: OP Mainnet, Base, Lisk

### OnFinality

**Description**: [OnFinality](https://onfinality.io/) offers [free and paid plans](https://onfinality.io/pricing) for the following [networks](https://onfinality.io/networks):

**Supported Testnets**: OP Sepolia, Unichain Sepolia, Base Sepolia

**Supported Mainnets**: OP Mainnet, Unichain, Base

### QuickNode

**Description**: [QuickNode](https://www.quicknode.com/) offers [free and paid plans](https://www.quicknode.com/pricing) for the following [networks](https://www.quicknode.com/chains):

**Supported Testnets**: OP Sepolia, Ink Sepolia, Unichain Sepolia, Base Sepolia, World Sepolia, Race Sepolia

**Supported Mainnets**: OP Mainnet, Ink, Unichain, Mode, Zora, Base, World, Lisk, Race

### RockX

**Description**: [RockX](https://www.rockx.com/) offers [free and paid plans](https://access.rockx.com/product/optimism-blockchain-api-for-web3-builders) for the following [networks](https://access.rockx.com/):

**Supported Testnets**: n/a

**Supported Mainnets**: OP Mainnet, Base

### Tenderly

**Description**: [Tenderly](https://tenderly.co/) offers [free and paid plans](https://tenderly.co/pricing) for the following [networks](https://docs.tenderly.co/node/rpc-reference):

**Supported Testnets**: OP Sepolia, Ink Sepolia, Unichain Sepolia, Soneium Sepolia, Mode Sepolia, Swell Sepolia, Base Sepolia, World Sepolia, Lisk Sepolia, Polynomial Sepolia, BoB Sepolia

**Supported Mainnets**: OP Mainnet, Ink, Unichain, Soneium, Mode, Swell, Base, World, Lisk, Polynomial, BoB

### Validation Cloud

**Description**: [Validation Cloud](https://www.validationcloud.io/) offers [free and paid plans](https://www.validationcloud.io/node) for the following [networks](https://docs.validationcloud.io/v1/optimism/overview):

**Supported Testnets**: n/a

**Supported Mainnets**: OP Mainnet, Base

## Directory governance

The OP Stack RPC Directory is maintained by OP Labs with the following policies:

* Providers must submit a docs PR to the [docs](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/) to be added
* To be listed, providers must support at least one network in the [OP Stack ecosystem](/op-stack/protocol/superchain-registry)
* Anyone can submit a PR to remove a provider that does not support a listed network

## Next steps

* Want to run your own node? See the [Node operators overview](/node-operators/overview).
* Looking for other developer tools? See [developer tools overview](/app-developers/tools) to explore more options!


# Bridged token addresses
Source: https://docs.optimism.io/app-developers/reference/tokens/tokenlist

This reference guide lists the correct bridged token addresses for each token.

Various ERC-20 tokens originally deployed to Ethereum also have corresponding "bridged" representations on OP Mainnet.
The [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io) exists to help users discover the correct bridged token addresses for each token.
This page is automatically generated from the Superchain Token List.

<Warning>
  **Tokens listed on this page are provided for convenience only** and are automatically derived from the [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io).
  **The presence of a token on this page does not imply any endorsement of the token or its minter.**
</Warning>

### USDC on OP Mainnet

<Info>
  The legacy bridged version of USDC (USDC.e) at address `0x7f5c764cbc14f9669b88837ca1490cca17c31607` is being deprecated on OP Mainnet.
  Users and developers should migrate to using the native USDC token issued directly by [Circle](https://www.circle.com/en/), the issuer of [USDC](https://www.circle.com/en/usdc?gad_source=1).
</Info>

Information about the bridged `USDC.e` token and native USDC token can be found below.

| Symbol   | Description                  | Address                                                                                                                       |
| -------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `USDC.e` | Bridged USDC from Ethereum   | [`0x7f5c764cbc14f9669b88837ca1490cca17c31607`](https://explorer.optimism.io/token/0x7f5c764cbc14f9669b88837ca1490cca17c31607) |
| `USDC`   | Native USDC issued by Circle | [`0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85`](https://explorer.optimism.io/token/0x0b2c639c533813f4aa9d7837caf62653d097ff85) |

## OP Mainnet

<Info>
  For a complete and up-to-date list of bridged token addresses for OP Mainnet (Chain ID: 10), please refer to the [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io) repository.
</Info>

## OP Sepolia

<Info>
  For a complete and up-to-date list of bridged token addresses for OP Sepolia (Chain ID: 11155420), please refer to the [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io) repository.
</Info>


# OPChainA (chainID 901)
Source: https://docs.optimism.io/app-developers/reference/tools/supersim/chain-a

Learn network details and contract addresses for OPChainA (chainID 901).

This guide provides network details and contract addresses for OPChainA (chainID 901) when running `supersim` vanilla mode.

## Network details

| **Parameter** | **Value**                                      |
| ------------- | ---------------------------------------------- |
| **Name**      | OPChainA                                       |
| **Chain ID**  | 901                                            |
| **RPC URL**   | [http://127.0.0.1:9545](http://127.0.0.1:9545) |

## Contract addresses

### L1 contracts

```json theme={null}
{
  "AddressManager": "0x78d21C9820A9135215202A9a8D6521483D4b75cD",
  "AnchorStateRegistry": "0x21799f09394c50220CCD95E7dAc1cdD774FC871a",
  "AnchorStateRegistryProxy": "0xa6F40d5770b3509aB40B2effa5cb544D29743ec7",
  "DelayedWETH": "0x49BBFf1629824A1e7993Ab5c17AFa45D24AB28c9",
  "DelayedWETHProxy": "0x309DA6B9a8fE16afD7D067528d358E55314bEa6b",
  "DisputeGameFactory": "0x20B168142354Cee65a32f6D8cf3033E592299765",
  "DisputeGameFactoryProxy": "0x444689B81D485bc58AB81aC02A95a937fAa152D7",
  "L1CrossDomainMessenger": "0x094e6508ba9d9bf1ce421fff3dE06aE56e67901b",
  "L1CrossDomainMessengerProxy": "0xcd712b03bc6424BF45cE6C29Fc90FFDece228F6E",
  "L1ERC721Bridge": "0x5C4F5e749A61a9503c4AAE8a9393e89609a0e804",
  "L1ERC721BridgeProxy": "0x018dC24a6617c47cAa00C3fA25097214B2D4F447",
  "L1StandardBridge": "0xb7900B27Be8f0E0fF65d1C3A4671e1220437dd2b",
  "L1StandardBridgeProxy": "0x8d515eb0e5F293B16B6bBCA8275c060bAe0056B0",
  "L2OutputOracle": "0x19652082F846171168Daf378C4fD3ee85a0D4A60",
  "L2OutputOracleProxy": "0x6cE0530E823e23be85D8e151FB023605eB4F6d43",
  "Mips": "0xB3A0348310a0ff78E5FbDB7f14BB7d3e02d40773",
  "OptimismMintableERC20Factory": "0x39Aea2Dd53f2d01c15877aCc2791af6BDD7aD567",
  "OptimismMintableERC20FactoryProxy": "0x15c855966C196Be3a8ca747E8A8Bf40928d4741f",
  "OptimismPortal": "0x37a418800d0c812A9dE83Bc80e993A6b76511B57",
  "OptimismPortal2": "0xfcbb237388CaF5b08175C9927a37aB6450acd535",
  "OptimismPortalProxy": "0xF5fe61a258CeBb54CCe428F76cdeD04Cbc12F53d",
  "PreimageOracle": "0x3bd7E801E51d48c5d94Ea68e8B801DFFC275De75",
  "ProtocolVersions": "0xfbfD64a6C0257F613feFCe050Aa30ecC3E3d7C3F",
  "ProtocolVersionsProxy": "0x6dA4f6489039d9f4F3144954DDF5bb2F4986e90b",
  "ProxyAdmin": "0xe32a4D31ffD5596542DAc8239a1DE3Fff9d63475",
  "SafeProxyFactory": "0x4a05c09875DE2DD5B81Bc01dd46eD4699b181bfA",
  "SafeSingleton": "0x99A395CE6d6b37CaaCBad64fB42d556b6CA73a48",
  "SuperchainConfig": "0x068E44eB31e111028c41598E4535be7468674D0A",
  "SuperchainConfigProxy": "0x7E6c6ebCF109fa23277b86bdA39738035C21BB86",
  "SystemConfig": "0x6167B477F8d9138aa509f54b2800443857e28c0f",
  "SystemConfigProxy": "0xf32919Ed2490b56EaD65E72749894aE4C9523320",
  "SystemOwnerSafe": "0xc052b7316C87390E555aF97D42bCd5FB6d5eEFDa"
}
```

### L2 contracts

```json theme={null}
{
  // OP Stack predeploys
  "L2ToL1MessagePasser": "0x4200000000000000000000000000000000000016",
  "L2CrossDomainMessenger": "0x4200000000000000000000000000000000000007",
  "L2StandardBridge": "0x4200000000000000000000000000000000000010",
  "L2ERC721Bridge": "0x4200000000000000000000000000000000000014",
  "SequencerFeeVault": "0x4200000000000000000000000000000000000011",
  "OptimismMintableERC20Factory": "0x4200000000000000000000000000000000000012",
  "OptimismMintableERC721Factory": "0x4200000000000000000000000000000000000017",
  "L1BlockInterop": "0x4200000000000000000000000000000000000015",
  "GasPriceOracle": "0x420000000000000000000000000000000000000F",
  "ProxyAdmin": "0x4200000000000000000000000000000000000018",
  "BaseFeeVault": "0x4200000000000000000000000000000000000019",
  "L1FeeVault": "0x420000000000000000000000000000000000001A",
  "OperatorFeeVault": "0x420000000000000000000000000000000000001B",
  "GovernanceToken": "0x4200000000000000000000000000000000000042",
  "SchemaRegistry": "0x4200000000000000000000000000000000000020",
  "EAS": "0x4200000000000000000000000000000000000021",
  "CrossL2Inbox": "0x4200000000000000000000000000000000000022",
  "L2ToL2CrossDomainMessenger": "0x4200000000000000000000000000000000000023",
  "SuperchainETHBridge": "0x4200000000000000000000000000000000000024",
  "SuperchainTokenBridge": "0x4200000000000000000000000000000000000028",

  // Periphery
  "L2NativeSuperchainERC20": "0x420beeF000000000000000000000000000000001"
}
```

## Next steps

* Learn how to [deposit transactions](/app-developers/tutorials/bridging/deposit-transactions) with Supersim, using a much simpler approach that bypasses the derivation pipeline.

- For more info about how OP Stack interoperability works under the hood, [check out the specs](https://specs.optimism.io/interop/overview.html?utm_source=op-docs\&utm_medium=docs).


# OPChainB (chainID 902)
Source: https://docs.optimism.io/app-developers/reference/tools/supersim/chain-b

Learn network details and contract addresses for OPChainB (chainID 902).

This guide provides network details and contract addresses for OPChainB (chainID 902) when running `supersim` vanilla mode.

## Network details

| **Parameter** | **Value**                                      |
| ------------- | ---------------------------------------------- |
| **Name**      | OPChainB                                       |
| **Chain ID**  | 902                                            |
| **RPC URL**   | [http://127.0.0.1:9546](http://127.0.0.1:9546) |

## Contract addresses

### L1 contracts

```json theme={null}
{
  "AddressManager": "0xafB51A0f73C8409AeA1207DF7f39885c927BeA46",
  "AnchorStateRegistry": "0x05493149c84A71063f7948127bb931f8377F779C",
  "AnchorStateRegistryProxy": "0xfd0269a716A59fF125Bd7eb65Cd3427C8555bab7",
  "DelayedWETH": "0x49BBFf1629824A1e7993Ab5c17AFa45D24AB28c9",
  "DelayedWETHProxy": "0xA63353128502269b4A4A4c2677fE316cd9ad4397",
  "DisputeGameFactory": "0x20B168142354Cee65a32f6D8cf3033E592299765",
  "DisputeGameFactoryProxy": "0x5F416fEb15c8B382d338FDBDb7D44967ca2b59BC",
  "L1CrossDomainMessenger": "0x094e6508ba9d9bf1ce421fff3dE06aE56e67901b",
  "L1CrossDomainMessengerProxy": "0xeCA0f912b4bd255f3851951caE5775CC9400aA3B",
  "L1ERC721Bridge": "0x5C4F5e749A61a9503c4AAE8a9393e89609a0e804",
  "L1ERC721BridgeProxy": "0xDCE41E6C0901586EE27Eac329EBD4b5fe5A7170d",
  "L1StandardBridge": "0xb7900B27Be8f0E0fF65d1C3A4671e1220437dd2b",
  "L1StandardBridgeProxy": "0x67B2aB287a32bB9ACe84F6a5A30A62597b10AdE9",
  "L2OutputOracle": "0x19652082F846171168Daf378C4fD3ee85a0D4A60",
  "L2OutputOracleProxy": "0x006Af3fB62c4BE4fB0393995d364BbFe6b0F3CB2",
  "Mips": "0xB3A0348310a0ff78E5FbDB7f14BB7d3e02d40773",
  "OptimismMintableERC20Factory": "0x39Aea2Dd53f2d01c15877aCc2791af6BDD7aD567",
  "OptimismMintableERC20FactoryProxy": "0x1A2A942d891e525D1Ab192578a378980729fD585",
  "OptimismPortal": "0x35e67BC631C327b60C6A39Cff6b03a8adBB19c2D",
  "OptimismPortal2": "0xfcbb237388CaF5b08175C9927a37aB6450acd535",
  "OptimismPortalProxy": "0xdfC9DEAbEEbDaa7620C71e2E76AEda32919DE5f2",
  "PreimageOracle": "0x3bd7E801E51d48c5d94Ea68e8B801DFFC275De75",
  "ProtocolVersions": "0xfbfD64a6C0257F613feFCe050Aa30ecC3E3d7C3F",
  "ProtocolVersionsProxy": "0xE139cB0CDa5EF722870068ea331d0989776A7aDf",
  "ProxyAdmin": "0xff5E6C2Af859f70B875BA59B958BEde60E36bf69",
  "SafeProxyFactory": "0xb68f3B057fE3c6CdDF9DB35837Ea769FCc81978a",
  "SafeSingleton": "0xeeB44D84d505AbD958d032e90704c56443eB3ED0",
  "SuperchainConfig": "0x068E44eB31e111028c41598E4535be7468674D0A",
  "SuperchainConfigProxy": "0x2ED4AA34573c36bF3856e597501aEf9d9Dc1687C",
  "SystemConfig": "0x6167B477F8d9138aa509f54b2800443857e28c0f",
  "SystemConfigProxy": "0x2Db03FE998D7c20E4B65afD1f50f04Ec4BfAb694",
  "SystemOwnerSafe": "0xBF3830711B7c559042453B7546dB4736eFB4245e"
}
```

### L2 contracts

```json theme={null}
{
  // OP Stack predeploys
  "L2ToL1MessagePasser": "0x4200000000000000000000000000000000000016",
  "L2CrossDomainMessenger": "0x4200000000000000000000000000000000000007",
  "L2StandardBridge": "0x4200000000000000000000000000000000000010",
  "L2ERC721Bridge": "0x4200000000000000000000000000000000000014",
  "SequencerFeeVault": "0x4200000000000000000000000000000000000011",
  "OptimismMintableERC20Factory": "0x4200000000000000000000000000000000000012",
  "OptimismMintableERC721Factory": "0x4200000000000000000000000000000000000017",
  "L1BlockInterop": "0x4200000000000000000000000000000000000015",
  "GasPriceOracle": "0x420000000000000000000000000000000000000F",
  "ProxyAdmin": "0x4200000000000000000000000000000000000018",
  "BaseFeeVault": "0x4200000000000000000000000000000000000019",
  "L1FeeVault": "0x420000000000000000000000000000000000001A",
  "OperatorFeeVault": "0x420000000000000000000000000000000000001B",
  "GovernanceToken": "0x4200000000000000000000000000000000000042",
  "SchemaRegistry": "0x4200000000000000000000000000000000000020",
  "EAS": "0x4200000000000000000000000000000000000021",
  "CrossL2Inbox": "0x4200000000000000000000000000000000000022",
  "L2ToL2CrossDomainMessenger": "0x4200000000000000000000000000000000000023",
  "SuperchainETHBridge": "0x4200000000000000000000000000000000000024",
  "SuperchainTokenBridge": "0x4200000000000000000000000000000000000028",

  // Periphery
  "L2NativeSuperchainERC20": "0x420beeF000000000000000000000000000000001"
}
```

## Next steps

* Learn how to [deposit transactions](/app-developers/tutorials/bridging/deposit-transactions) with Supersim, using a much simpler approach that bypasses the derivation pipeline.

- For more info about how OP Stack interoperability works under the hood, [check out the specs](https://specs.optimism.io/interop/overview.html?utm_source=op-docs\&utm_medium=docs).


# Fork mode
Source: https://docs.optimism.io/app-developers/reference/tools/supersim/fork

Learn how to fork Supersim.

Supersim fork mode to simulate and interact with the state of the chain without needing to re-deploy or modify the contracts. This is possible if you're relying on contracts already deployed on testnet / mainnet chains.

```sh theme={null}
supersim fork
```

## How it works

The `supersim` fork command simplifies the process of forking multiple chains in the OP Stack ecosystem simultaneously. It determines the appropriate block heights for each chain and launches both the L1 and L2 chains based on these values.

This allows you to locally fork any chain in a superchain network of the [superchain registry](https://github.com/ethereum-optimism/superchain-registry), default `mainnet` versions.

### Example startup logs

```
Available Accounts
-----------------------
(0): 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
--- truncated for brevity ---

Private Keys
-----------------------
(0): 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
--- truncated for brevity ---

Orchestrator Config:
L1:
  Name: mainnet    Chain ID: 1    RPC: http://127.0.0.1:8545    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-1-1521250718
L2:
  Name: op    Chain ID: 10    RPC: http://127.0.0.1:9545    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-10
  Name: base    Chain ID: 8453    RPC: http://127.0.0.1:9546    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-8453
  Name: zora    Chain ID: 7777777    RPC: http://127.0.0.1:9547    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-7777777
```

## Configuration

```
NAME:
   supersim fork - Locally fork a network in the superchain registry

USAGE:
   supersim fork [command options]

OPTIONS:

          --l1.fork.height value              (default: 0)                       ($SUPERSIM_L1_FORK_HEIGHT)
                L1 height to fork the superchain (bounds L2 time). `0` for latest

          --chains value                                                         ($SUPERSIM_CHAINS)
                chains to fork in the superchain, mainnet options: [arena-z, automata, base,
                bob, cyber, ethernity, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode,
                op, orderly, polynomial, race, redstone, shape, soneium, sseed, swan, swell, tbn,
                unichain, worldchain, xterio-eth, zora]. In order to replace the public rpc endpoint
                for a chain, specify the ($SUPERSIM_RPC_URL_<CHAIN>) env variable. i.e
                SUPERSIM_RPC_URL_OP=http://optimism-mainnet.infura.io/v3/<API-KEY>

          --network value                     (default: "mainnet")               ($SUPERSIM_NETWORK)
                superchain network. options: mainnet, sepolia, sepolia-dev-0. In order to
                replace the public rpc endpoint for the network, specify the
                ($SUPERSIM_RPC_URL_<NETWORK>) env variable. i.e
                SUPERSIM_RPC_URL_MAINNET=http://mainnet.infura.io/v3/<API-KEY>

          --interop.enabled                   (default: true)                    ($SUPERSIM_INTEROP_ENABLED)
                enable interop predeploy and functionality

          --admin.port value                  (default: 8420)                    ($SUPERSIM_ADMIN_PORT)
                Listening port for the admin server

          --interop.l2tol2cdm.override value                                     ($SUPERSIM_INTEROP_L2TO2CDM_OVERRIDE)
                Path to the L2ToL2CrossDomainMessenger build artifact that overrides
                the default implementation

          --l1.port value                     (default: 8545)                    ($SUPERSIM_L1_PORT)
                Listening port for the L1 instance. `0` binds to any available port

          --l2.count value                    (default: 2)                       ($SUPERSIM_L2_COUNT)
                Number of L2s. Max of 5

          --l2.starting.port value            (default: 9545)                    ($SUPERSIM_L2_STARTING_PORT)
                Starting port to increment from for L2 chains. `0` binds each chain to any
                available port

          --interop.autorelay                 (default: false)                   ($SUPERSIM_INTEROP_AUTORELAY)
                Automatically relay messages sent to the L2ToL2CrossDomainMessenger using
                account 0xa0Ee7A142d267C1f36714E4a8F75612F20a79720

          --interop.delay value               (default: 0)                       ($SUPERSIM_INTEROP_DELAY)
                Delay before relaying messages sent to the L2ToL2CrossDomainMessenger

          --logs.directory value                                                 ($SUPERSIM_LOGS_DIRECTORY)
                Directory to store logs

          --l1.host value                     (default: "127.0.0.1")             ($SUPERSIM_L1_HOST)
                Host address for the L1 instance

          --l2.host value                     (default: "127.0.0.1")             ($SUPERSIM_L2_HOST)
                Host address for L2 instances

          --odyssey.enabled                   (default: false)                   ($SUPERSIM_ODYSSEY_ENABLED)
                Enable odyssey experimental features

          --dependency.set value                                                 ($SUPERSIM_DEPENDENCY_SET)
                Override local chain IDs in the dependency set.(format: '[901,902]' or '[]')

          --log.level value                   (default: INFO)                    ($SUPERSIM_LOG_LEVEL)
                The lowest log level that will be output

          --log.format value                  (default: text)                    ($SUPERSIM_LOG_FORMAT)
                Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json',
                'json-pretty',

          --log.color                         (default: false)                   ($SUPERSIM_LOG_COLOR)
                Color the log output if in terminal mode

          --log.pid                           (default: false)                   ($SUPERSIM_LOG_PID)
                Show pid in the log

          --help, -h                          (default: false)
                show help
```

## Notes

### Fork height

The fork height is determined by L1 block height (default `latest`). This is then used to derive the corresponding L2 block to start from.

### Interoperability contracts

By default, interop contracts are not deployed on forked networks. To include them, run `supersim` with the `--interop.enabled` flag.

```sh theme={null}
supersim fork --chains=op,base,zora --interop.enabled
```

## Next steps

* Explore the Supersim [included contracts](/app-developers/reference/tools/supersim/included-contracts) being used to help replicate the OP Stack environment.

- Learn how to [deposit transactions](/app-developers/tutorials/bridging/deposit-transactions) with Supersim, using a much simpler approach that bypasses the derivation pipeline.


# Included contracts
Source: https://docs.optimism.io/app-developers/reference/tools/supersim/included-contracts

Learn about the Supersim included contracts.

The `supersim` chain environment includes contracts already deployed to help replicate the OP Stack interop environment. See [OP Chain A](./chain-a) for contract address examples for a L2 system.

## OP Stack system contracts (L1)

These are the L1 contracts that are required for a rollup as part of the OP Stack protocol. Examples are the [OptimismPortal](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol), [L1StandardBridge](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1StandardBridge.sol), and [L1CrossDomainMessenger](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol).

For more details, see [example contracts](/op-mainnet/network-information/op-addresses#ethereum-mainnet) or the [source code](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/src/L1).

## OP Stack L2 contracts (L2)

The OP Stack system contracts on the L2 are included at the standard addresses by default.

* [Standard OP Stack predeploys (L2)](https://specs.optimism.io/protocol/predeploys.html)
* [Interoperability predeploys (*experimental*) (L2)](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs)
* [OP Stack preinstalls (L2)](https://specs.optimism.io/protocol/preinstalls.html?utm_source=op-docs\&utm_medium=docs)

## Periphery contracts (L2)

L2 chains running on `supersim` also includes some useful contracts for testing purposes that are not part of the OP Stack by default.

### L2NativeSuperchainERC20

A simple ERC20 included in Supersim for testing cross-chain token transfers. It includes permissionless minting for easy testing.

Source: [L2NativeSuperchainERC20.sol](https://github.com/ethereum-optimism/supersim/blob/main/contracts/src/L2NativeSuperchainERC20.sol)

Deployed address: `0x420beeF000000000000000000000000000000001`

#### Minting new tokens

```bash theme={null}
cast send 0x420beeF000000000000000000000000000000001 "mint(address _to, uint256 _amount)" $RECIPIENT_ADDRESS 1ether  --rpc-url $L2_RPC_URL
```

## Next steps

* Get network details about the two OP Stack systems spun up in vanilla mode: [OPChainA (chainID 901)](/app-developers/reference/tools/supersim/chain-a) and [OPChainB (chainID 902)](/app-developers/reference/tools/supersim/chain-b).

- Learn how to [deposit transactions](/app-developers/tutorials/bridging/deposit-transactions) with Supersim, using a much simpler approach that bypasses the derivation pipeline.


# Vanilla mode
Source: https://docs.optimism.io/app-developers/reference/tools/supersim/vanilla

Learn how to use Supersim in vanilla mode (non-forked).

This guide explains how to start `supersim` in vanilla (non-forked) mode. By default, two OP Stack systems will be spun up in vanilla mode:

* OPChainA (chainID 901)
* OPChainB (chainID 902)
  Both "roll up" into a single L1 chain (chainID 900).

## How it works

```sh theme={null}
supersim
```

Vanilla mode will start 3 chains, with the OP Stack contracts & periphery contracts already deployed.

* (1) L1 Chain
  * Chain 900
* (2) L2 Chains
  * Chain 901
  * Chain 902

### Example startup logs

```
Available Accounts
-----------------------
(0): 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
(1): 0x70997970C51812dc3A010C7d01b50e0d17dc79C8
(2): 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC
(3): 0x90F79bf6EB2c4f870365E785982E1f101E93b906
(4): 0x15d34AAf54267DB7D7c367839AAf71A00a2C6A65
(5): 0x9965507D1a55bcC2695C58ba16FB37d819B0A4dc
(6): 0x976EA74026E726554dB657fA54763abd0C3a0aa9
(7): 0x14dC79964da2C08b23698B3D3cc7Ca32193d9955
(8): 0x23618e81E3f5cdF7f54C3d65f7FBc0aBf5B21E8f
(9): 0xa0Ee7A142d267C1f36714E4a8F75612F20a79720

Private Keys
-----------------------
(0): 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
(1): 0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d
(2): 0x5de4111afa1a4b94908f83103eb1f1706367c2e68ca870fc3fb9a804cdab365a
(3): 0x7c852118294e51e653712a81e05800f419141751be58f605c371e15141b007a6
(4): 0x47e179ec197488593b187f80a00eb0da91f1b9d0b13f8733639f19c30a34926a
(5): 0x8b3a350cf5c34c9194ca85829a2df0ec3153be0318b5e2d3348e872092edffba
(6): 0x92db14e403b83dfe3df233f83dfa3a0d7096f21ca9b0d6d6b8d88b2b4ec1564e
(7): 0x4bbbf85ce3377467afe5d46f804f221813b2bb87f24d81f60f1fcdbf7cbf4356
(8): 0xdbda1821b80551c9d65939329250298aa3472ba22feea921c0cf5d620ea67b97
(9): 0x2a871d0798f97d79848a013d4936a73bf4cc922c825d33c1cf7073dff6d409c6

Orchestrator Config:
L1:
  Name: L1    Chain ID: 900    RPC: http://127.0.0.1:8545    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-900
L2:
  Name: OPChainA    Chain ID: 901    RPC: http://127.0.0.1:9545    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-901
  Name: OPChainB    Chain ID: 902    RPC: http://127.0.0.1:9546    LogPath: /var/folders/0w/ethers-phoenix/T/anvil-chain-902
```

## Configuration

```
NAME:
   supersim - Superchain Multi-L2 Simulator

USAGE:
   supersim [global options] command [command options]

VERSION:
   untagged

DESCRIPTION:
   Local multichain optimism development environment

COMMANDS:
   fork     Locally fork a network in the superchain registry
   docs     Display available docs links
   help, h  Shows a list of commands or help for one command

GLOBAL OPTIONS:

    --admin.port value                  (default: 8420)                    ($SUPERSIM_ADMIN_PORT)
          Listening port for the admin server

    --interop.l2tol2cdm.override value                                     ($SUPERSIM_INTEROP_L2TO2CDM_OVERRIDE)
          Path to the L2ToL2CrossDomainMessenger build artifact that overrides
          the default implementation

    --l1.port value                     (default: 8545)                    ($SUPERSIM_L1_PORT)
          Listening port for the L1 instance. `0` binds to any available port

    --l2.count value                    (default: 2)                       ($SUPERSIM_L2_COUNT)
          Number of L2s. Max of 5

    --l2.starting.port value            (default: 9545)                    ($SUPERSIM_L2_STARTING_PORT)
          Starting port to increment from for L2 chains. `0` binds each chain to any
          available port

    --interop.autorelay                 (default: false)                   ($SUPERSIM_INTEROP_AUTORELAY)
          Automatically relay messages sent to the L2ToL2CrossDomainMessenger using
          account 0xa0Ee7A142d267C1f36714E4a8F75612F20a79720

    --interop.delay value               (default: 0)                       ($SUPERSIM_INTEROP_DELAY)
          Delay before relaying messages sent to the L2ToL2CrossDomainMessenger

    --logs.directory value                                                 ($SUPERSIM_LOGS_DIRECTORY)
          Directory to store logs

    --l1.host value                     (default: "127.0.0.1")             ($SUPERSIM_L1_HOST)
          Host address for the L1 instance

    --l2.host value                     (default: "127.0.0.1")             ($SUPERSIM_L2_HOST)
          Host address for L2 instances

    --odyssey.enabled                   (default: false)                   ($SUPERSIM_ODYSSEY_ENABLED)
          Enable odyssey experimental features

    --dependency.set value                                                 ($SUPERSIM_DEPENDENCY_SET)
          Override local chain IDs in the dependency set.(format: '[901,902]' or '[]')

    --log.color                         (default: false)                   ($SUPERSIM_LOG_COLOR)
          Color the log output if in terminal mode

    --log.format value                  (default: text)                    ($SUPERSIM_LOG_FORMAT)
          Format the log output. Supported formats: 'text', 'terminal', 'logfmt', 'json',
          'json-pretty',

    --log.level value                   (default: INFO)                    ($SUPERSIM_LOG_LEVEL)
          The lowest log level that will be output

    --log.pid                           (default: false)                   ($SUPERSIM_LOG_PID)
          Show pid in the log

   MISC

    --help, -h                          (default: false)
          show help

    --version, -v                       (default: false)
          print the version
```

## Next steps

* Explore the Supersim [included contracts](/app-developers/reference/tools/supersim/included-contracts) being used to help replicate the OP Stack interop environment.
* Get network details about the two OP Stack systems spun up in vanilla mode: [OPChainA (chainID 901)](/app-developers/reference/tools/supersim/chain-a) and [OPChainB (chainID 902)](/app-developers/reference/tools/supersim/chain-b).

- Learn how to [deposit transactions](/app-developers/tutorials/bridging/deposit-transactions) with Supersim, using a much simpler approach that bypasses the derivation pipeline.


# Account abstraction
Source: https://docs.optimism.io/app-developers/tools-sdks/account-abstraction

This guide explains how to use account abstraction to remove friction from your app experience

<Info>
  This page includes providers that meet specific [inclusion criteria](#inclusion-criteria), as outlined below. Please visit the [community account abstractions page](https://github.com/ethereum-optimism/developers/blob/main/community/tools/account-abstraction.md) for an additional listing of third-party account abstraction tools.
</Info>

[ERC-4337](https://www.erc4337.io/docs/paymasters/introduction), also known as Account Abstraction, enables more opportunities for apps and wallet developers to innovate on user experiences, including the ability to:

* Batch transactions together (e.g. approve and execute a swap in one go)
* Offer wallets with easy recovery and no seed phrase
* Sponsor the gas fees for transactions
* Enable users to pay gas in the token(s) of their choice

## Bundlers

The OP Stack includes support for the `eth_sendRawTransactionConditional` RPC method to assist bundlers on shared 4337 mempools. See the [specification](/op-stack/features/send-raw-transaction-conditional) for how this method is implemented in op-geth.

If used by the chain operator, also see the supplemental [op-txproxy](/chain-operators/tools/op-txproxy) service which may apply additional restrictions prior to reaching the block builder.

<Info>
  As of today, this endpoint is not enabled by default in the stack. The operator must explicitly configure this.
</Info>

## Account abstraction tools

Ready to enable account abstraction experiences in your app? Here's some helpful information on account abstraction infrastructure like ERC-4337 bundler and gas manager APIs that are available on OP Mainnet:

* [Alchemy](https://www.alchemy.com/account-abstraction):
  Account Kit is a complete solution for account abstraction. Using Account Kit, you can create a smart contract wallet for every user that leverages account abstraction to simplify every step of your app's onboarding experience. It also offers Gas Manager and Bundler APIs for sponsoring gas and batching transactions.

* [Biconomy](https://docs.biconomy.io/): is an Account Abstraction toolkit that enables you to provide the simplest UX for your app or wallet. It offers modular smart accounts, as well as paymasters and bundlers as a service for sponsoring gas and executing transactions at scale.

* [GroupOS](https://docs.groupos.xyz/introduction/group-os): provides Smart Wallets that are ERC-4337 compliant smart wallets, offering full flexibility, programmability and extensibility as well as out-of-the-box toolkit groups need to gaslessly onboard and activate wallets to games, applications, and/or protocols.

* [Openfort](https://openfort.io/docs/?utm_source=optimism\&utm_medium=docs\&utm_campaign=backlinks): an open-source wallet infrastructure solution. The core offerings include embedded wallets, global wallets and AA infrastructure (Paymaster and Bundler). It enables rapid integration of wallet functionality, intuitive onboarding, and stablecoin flows.

* [Pimlico](https://docs.pimlico.io/): provides an infrastructure platform that makes building smart accounts simpler. If you are developing an ERC-4337 smart account, they provide bundlers, verifying paymasters, ERC-20 paymasters, and much more.

* [Reown](https://reown.com/?utm_source=optimism\&utm_medium=docs\&utm_campaign=backlinks) gives developers the tools to build user experiences that make digital ownership effortless, intuitive, and secure. Using Reown's AppKit SDK, you can enable your users to create a smart wallet using their social logins, configure a paymaster to sponsor gas fees, enable chain abstraction and a lot more.

* [Safe](https://docs.safe.global/home/what-is-safe): provides modular smart account infrastructure and account abstraction stack via their Safe\{Core} Account Abstraction SDK, API, and Protocol.

* [Stackup](https://docs.stackup.sh/docs): provides smart account tooling for building account abstraction within your apps. They offer Paymaster and Bundler APIs for sponsoring gas and sending account abstraction transactions.

* [thirdweb](https://portal.thirdweb.com/react/v5/account-abstraction/get-started?utm_source=opdocs\&utm_medium=docs):
  offers the complete tool-kit to leverage account abstraction technology to enable seamless user experiences for your users. This includes Account Factory contracts that lets your users spin up Smart Accounts, Bundler for UserOps support, and Paymaster to enable gas sponsorships.

## Helpful tips

* [EIP-1271 Signature Validation](https://eip1271.io/)
* [Making smart accounts work with WalletConnect v2](https://safe-global.notion.site/WalletConnect-v2-update-Issues-and-solutions-for-smart-wallets-3fc32fad6af4485fa5823eaebd486819)


# Block explorers
Source: https://docs.optimism.io/app-developers/tools-sdks/block-explorers

Learn about different block explorers you can use to interact with contracts and view transaction history for OP Mainnet and OP Sepolia.

## Blockscout

We have a Blockscout explorer for [OP Mainnet](https://optimism.blockscout.com) and [OP Sepolia](https://optimism-sepolia.blockscout.com/). It includes:

* [Verified testnet contract source code, along with the ability to interact with it](https://optimism.blockscout.com/verified-contracts)
* [Detailed testnet transaction information](https://optimism.blockscout.com/tx/0xa1b04233084d4067ec0bb3e09301012900f0e209f14a3d406f3d6dc696eea138)

Blockscout also has some OP-Mainnet-specific features:

* [An interactive list of deposits (L1-L2)](https://optimism.blockscout.com/l2-deposits)
* [An interactive list of withdrawals (L2-L1)](https://optimism.blockscout.com/l2-withdrawals)
* [Transaction batches](https://optimism.blockscout.com/l2-txn-batches)
* [App marketplace](https://optimism.blockscout.com/apps)
* And much more!

## Etherscan

We have Etherscan explorers for the [OP Mainnet](https://explorer.optimism.io) and the [OP Sepolia](https://testnet-explorer.optimism.io/).
Etherscan has lots of tools to help you debug transactions.

Optimistic Etherscan has all the tools you expect from Etherscan, such as:

* [Verified contract source code, along with the ability to interact with it](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F#code)
* [Detailed transaction information](https://explorer.optimism.io/tx/0x292423266d6da24126dc4e0e81890c22a67295cc8b1a987e71ad84748511452f)
* And everything else you might find on Etherscan!

It's also got some OP-Mainnet-specific features:

* [A list of L1-to-L2 transactions](https://explorer.optimism.io/txsEnqueued)
* [A list of L2-to-L1 transactions](https://explorer.optimism.io/txsExit)
* [A tool for finalizing L2-to-L1 transactions](https://explorer.optimism.io/messagerelayer)
* And more! Just check it out and click around to find all of the available features.

## Superscan by Routescan

[Superscan](https://superscan.network) is the dev-focused OP Stack explorer unified at the ecosystem level, powered by [Routescan](https://routescan.io). On the Superscan, developers can quickly glance at transactions, blocks, addresses, deployed contracts and more across OP Stack chains in unified pages.

The Superscan currently includes:

* Mainnet - OP Mainnet, Base, Zora, Mode, Cyber, Orderly, Fraxtal, Public Goods Network
* Testnet - Zora, Mode, Orderly, Fraxtal

## Tenderly

Tenderly's [Developer Explorer](https://docs.tenderly.co/developer-explorer?mtm_campaign=ext-docs\&mtm_kwd=optimism) for OP Mainnet and OP Sepolia allows you to monitor and inspect transactions, providing a high level of detail and additional tools:

Tenderly Developer Explorer lets you:

* Keep track of specific [contracts](https://docs.tenderly.co/developer-explorer/contracts?mtm_campaign=ext-docs\&mtm_kwd=optimism) and their transactions
* Inspect [transaction execution](https://docs.tenderly.co/developer-explorer/inspect-transaction?mtm_campaign=ext-docs\&mtm_kwd=optimism) with fully decoded transaction trace
* [Debug](https://docs.tenderly.co/debugger?mtm_campaign=ext-docs\&mtm_kwd=optimism) failing and [simulate](https://docs.tenderly.co/simulator-ui/using-simulation-ui?mtm_campaign=ext-docs\&mtm_kwd=optimism) correct transactions before sending them on-chain
* Evaluate [function-level gas usage](https://docs.tenderly.co/debugger/gas-profiler?mtm_campaign=ext-docs\&mtm_kwd=optimism) for any transaction
* Set up [Alerts](https://docs.tenderly.co/alerts/tutorials-and-quickstarts/alerting-quickstart-guide?mtm_campaign=ext-docs\&mtm_kwd=optimism) to monitor interactions, access control, asset transfers, and contracts' state changes
* Create a [Virtual TestNet](https://docs.tenderly.co/virtual-testnets?mtm_campaign=ext-docs\&mtm_kwd=optimism) from a specific OP Mainnet or OP Chain transaction for systematic research

## Access to pre-regenesis history

Because of our final regenesis on 11 November 2021, older transactions are not part of the current blockchain and do not appear on [Etherscan](https://explorer.optimism.io/?utm_source=op-docs\&utm_medium=docs).
However, you **can** access transaction history between 23 June 2021 and the final regenesis using a number of different tools. For detailed instructions, see [Regenesis History](/op-mainnet/pre-bedrock-history/regenesis-history).

## Next Steps

* Looking for other developer tools? See the [building apps overview](/app-developers/guides/building-apps) to explore more options!


# Analytics tools
Source: https://docs.optimism.io/app-developers/tools-sdks/data/analytics-tools

Learn about platforms you can use to gather analytics and set up customizations about OP Mainnet.

The following guide lists platforms you can use to gather analytics and set up customizations about OP Mainnet.

## Blocknative

[Blocknative](https://www.blocknative.com/) lets you [decode](http://docs.blocknative.com/ethernow/batch-decoder-api) and [analyze](https://docs.blocknative.com/blocknative-data-archive/blob-archive) OP Stack Batches submitted to the Ethereum L1. You can inspect, analyze, decode, and download the data of any batch – confirmed on-chain or not – via public APIs or visually through the [Ethernow Explorer](http://ethernow.xyz). Below you can find links to the different resources:

* [Batch Decoding API](http://docs.blocknative.com/ethernow/batch-decoder-api): decode OP Stack Batch transactions into their human-readable JSON format.
* [Blob Archive API](https://docs.blocknative.com/blocknative-data-archive/blob-archive): take any versioned hash of an OP Stack Blob and receive the blob data (even beyond the 4096 epoch window of storage).
* [Mempool Archive](https://docs.blocknative.com/blocknative-data-archive/mempool-archive): Analyze any OP Stack transaction that was in the Ethereum mempool to see detection time, time pending, gas, etc.
* [Ethernow Explorer](http://ethernow.xyz): Visually see transactions and batches enter the mempool and get organized into blocks. Use this filter to see OP Stack Batches enter the mempool and land on-chain.

## Tenderly

[Tenderly](https://tenderly.co/?mtm_campaign=ext-docs\&mtm_kwd=optimism) provides comprehensive monitoring and security solutions for OP-powered Chains, allowing you to stay informed and respond proactively to potential issues in real time.

* Configure [Tenderly Alerts](https://docs.tenderly.co/alerts/intro-to-alerts?mtm_campaign=ext-docs\&mtm_kwd=optimism) for monitoring wallets and setting up real-time notifications on transactions and contract events. Notifications trigger external webhooks, PagerDuty, or chat apps like Telegram and Slack.
* Rely on [Developer Explorer](https://docs.tenderly.co/developer-explorer?mtm_campaign=ext-docs\&mtm_kwd=optimism) to monitor and analyze transaction execution with a high level of detail.
* Use [Web3 Actions](https://docs.tenderly.co/web3-actions/intro-to-web3-actions?mtm_campaign=ext-docs\&mtm_kwd=optimism) to automate predefined responses, improving security and user experience.
* Integrate [Simulation RPC](https://docs.tenderly.co/simulations/single-simulations?mtm_campaign=ext-docs\&mtm_kwd=optimism#simulate-via-rpc) to predict transaction outcomes such as the expected asset changes, precise gas usage, and emitted events.

## Dune Analytics

[Dune Analytics](https://dune.com) allows anyone to create dashboards that present information about OP Chains (OP Mainnet, Base, and Zora are available). See [Dune Docs](https://dune.com/docs/) for more info.
You can find a list of community created dashboards for OP Chains [here](https://dune.com/browse/dashboards?q=tags%3Aop%2Coptimism%2Csuperchain\&order=trending\&time_range=24h), or [create your own](https://docs.dune.com/#queries) dashboard.

For developers building apps on OP chains, Dune's developer platform, [Sim](https://sim.dune.com/), provides real-time onchain data access via [Sim APIs](https://docs.sim.dune.com/) and custom indexing with [Sim IDX](https://docs.sim.dune.com/idx).

Here are some of our favorite dashboards so far:

* [OP Chains / Superchain - L2 Activity, Chain Economics](https://dune.com/oplabspbc/op-stack-chains-l1-activity)
* [OP Chains / Superchain - Popular Apps & Project Usage Trends](https://dune.com/oplabspbc/superchain-op-chains-apps-and-project-usage-trends)
* [By OP Chain - L2/L1 Chain Economics](https://dune.com/oplabspbc/optimism-l2-l1-economics)
* [OP Token House Delegates](https://dune.com/optimismfnd/optimism-op-token-house)
* [Superchain NFTs](https://dune.com/oplabspbc/superchain-nfts)

## Additional tools and resources

Here are some additional tools and resources for OP Mainnet analytics and development:

* L2 Usage and Comparison: [growthepie](https://www.growthepie.xyz/)
* OP Analytics (Incentive Tracking, Helper Functions, Public Analysis): [OP Analytics on GitHub](https://github.com/ethereum-optimism/op-analytics)
* Contribute to NumbaNERDs: [Issues on GitHub](https://github.com/ethereum-optimism/op-analytics/issues)


# Data and Dashboards
Source: https://docs.optimism.io/app-developers/tools-sdks/data/data-and-dashboards

Learn about various dashboards and terms to explore various OP Stack metrics.

The following resources are available to help you explore various OP Stack metrics:

* [Data Glossary](/app-developers/tools-sdks/data/data-glossary): Definitions, methodology, and calculation notes for key metrics
* [Superchain Health Dashboard](https://docs.google.com/spreadsheets/d/1f-uIW_PzlGQ_XFAmsf9FYiUf0N9l_nePwDVrw0D5MXY/edit?gid=192497306#gid=192497306): High-level metrics across OP Stack chains
* [Superchain Strategic Focus Dashboard](https://app.hex.tech/61bffa12-d60b-484c-80b9-14265e268538/app/d28726b2-ff11-4f94-8a9f-6bb0a86f4b46/latest): In-depth metrics with chain-level splits and industry benchmarks
* [Optimism Superchain Raw Onchain Data](https://console.cloud.google.com/bigquery/analytics-hub/exchanges/projects/523274563936/locations/us/dataExchanges/optimism_192d403716e/listings/optimism_superchain_raw_onchain_data_192fdc72e35): Raw Blocks, Logs, Transactions, Traces data for OP Stack chains, updated daily.
* [Optimism Superchain 4337 Account Abstraction Data](https://console.cloud.google.com/bigquery/analytics-hub/exchanges/projects/523274563936/locations/us/dataExchanges/optimism_192d403716e/listings/optimism_superchain_4337_account_abstraction_data_1954d8919e1): Decoded account abstraction UserOps across OP Stack chains.


# Data Glossary
Source: https://docs.optimism.io/app-developers/tools-sdks/data/data-glossary

This glossary explains various data terms.

This glossary is a living document and will be updated over time as new metrics emerge or definitions evolve.

| Metric                    | What It Measures                                                       | Why It Matters                                                    |
| ------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
| Real Economic Value (REV) | Fees paid by users to transact (txn fees + out-of-protocol tips)       | Captures users' willingness to pay for onchain activity           |
| Collective Revenue        | ETH earned by the Optimism Collective                                  | Revenue can be directed by governance to support ecosystem growth |
| Total Value Locked (TVL)  | Tokens locked in DeFi protocols and other apps                         | Supply side of the DeFi ecosystem                                 |
| Gas Used per Second       | Average compute consumed onchain                                       | Measures throughput and execution load                            |
| Median Transaction Fee    | Typical cost for a user to transact                                    | Lower fees reduce friction and may unlock broader usage           |
| Market Share              | OP Stack ecosystem's share of activity vs. the broader crypto industry | Tracks relative performance against L2s or the broader market     |

## Measure Demand

### Transaction Fees Paid

**Metric:** Real Economic Value (REV)

**Definition:** The total fees paid to execute a transaction onchain. This includes both the traditional gas fees required for inclusion onchain and additional fees paid to transaction execution services (e.g., Jito, Flashbots, Timeboost).

**Calculation:** Gas Fees + Out-of-Protocol Tips (e.g., Jito, Flashbots, Timeboost)

* Out-of-Protocol Tips can be sourced from Defillama's MEV category

**Why it matters:**

* REV is a topline metric that "measures the monetary demand to transact onchain" (Blockworks).
* It's used as a proxy for users' willingness to pay, capturing all transaction fees to better reflect real demand (excludes app-level fees like DEX swap costs).

### Revenue

**Metric:** Estimated Optimism Collective Revenue (Collective Revenue)

**Definition:** The amount of ETH expected to be earned by the Optimism Collective from revenue sharing.

**Calculation:** For each chain, take the greater of (a) 2.5% of Chain Revenue or (b) 15% of Net Onchain Profit. OP Mainnet contributes 100% of Net Onchain Profit.

**Key Components:**

* **Net Onchain Profit:** Chain Revenue - L1 Gas Fees
* **Chain Revenue:** Sum of the L1 Data Fee + L2 Base Fee + L2 Priority Fee + L2 Operator Fee (Also includes any additional fee types added in the future.)
* *L1 Gas Fees:* Total gas fees spent by the chain on L1 in transaction batches (including blob costs) and state output submissions or dispute games.
* **Transaction Batches:** All transactions where the transaction from address is the `batcherHash` address as defined in the chains' `SystemConfigProxy` contract, and the transaction to address is the chain's `batch_inbox_address` as defined in the rollup config.
* **State Output Submissions or Dispute Games:** All transactions where the transaction from address is the `Proposer` and the transaction to address is either the `outputOracleProxy` or the `disputeGameFactoryProxy` as defined in the chains' `SystemConfigProxy` contract.
* Each chain's `SystemConfigProxy` contract can be found in the superchain-registry.
* **Resolving Dispute Games:** All transactions sent to dispute game contracts created by the `disputeGameFactoryProxy`, where the transaction's method id (function call) is either `Resolve`, `ResolveClaim`, or `ClaimCredit`.

**Why it matters:**

* This is what the Optimism Collective earns by operating OP Stack chains, which can be directed by governance to support ecosystem growth.
* See How (and why) the OP Stack drives fees to the Optimism Collective (Optimism blog, Aug 2024)

## Onchain Signals

### Value Onchain

**Metric:** Total Value Locked (TVL)

**Definition:** "Value of all coins held in smart contracts of the protocol" (Defillama).

**Calculation:** The sum of all USD value of assets locked in applications, as reported by DefiLlama.

* TVL can be priced in USD or a crypto asset like ETH, but both are subject to price volatility. USD is often used because it's easier to interpret and consistent across the broader crypto ecosystem.

**Why it Matters:** TVL represents the supply side of onchain economic activity for use in protocols such as Decentralized Exchanges (DEXs) and lending markets. Strong TVL in the right places may enable greater onchain demand.

#### How to Measure Growth: Net TVL Flows

Because TVL is influenced by market fluctuations, it can be misleading when trying to measure true growth or user behavior. Net TVL Flows can adjust for this by tracking the net change in token balances, valued at current prices.

**Calculation:** ( `# of Tokens on Day N` - `# of Tokens on Day 0` ) \* `Price of Tokens on Day N`

**Example:** If an app has 100,000 ETH locked on Day 0 when ETH/USD is $2,000, and 90,000 ETH locked at $3,000 on Day N:

* Net TVL Flows = −10,000 ETH × $3,000 = $30 million in net outflows
* Naive TVL change would suggest growth: $200 million → $270 million

## Network Usage & Infrastructure

**Metric:** Gas Used per Second (gas/s)

**Definition:** "Gas refers to the unit that measures the amount of computational effort required to execute specific operations on Ethereum" (ethereum.org). Gas Used is tracked as an average rate per second for simplicity.

**Why it Matters:** Gas, sometimes referred to as blockspace, is the limited resource that blockchains provide. Gas used shows how much of that resource is actually being consumed.

**Caution:** Gas is only comparable across chains that use Ethereum-equivalent gas units.

### User Experience (UX)

**Metric:** Median Transaction Fee (USD)

**Definition:** The median gas fee paid to submit a transaction, expressed in USD for simplicity and easier comparison across ecosystems.

**Calculation:** Median of all transaction fees over a period of time, marked at the USD price at the time of the transaction.

**Why it Matters:** This metric serves as a proxy for the cost to transact. Lower median fees enable broader usage by reducing friction, lowering breakeven costs, and unlocking use cases that would otherwise be cost-prohibitive.

## Market Share

**Definition:** The OP Stack ecosystem's share of a broader market segment for any measure (e.g., L2s, total crypto).

**Calculation:** OP Stack Metric Value / Total Market Metric Value

**Why it Matters:** Market share helps isolate whether growth is driven by the OP Stack ecosystem itself, or is simply part of a broader market trend. A rising share signals outperformance, while a declining share suggests that other ecosystems are growing faster.


# Oracles
Source: https://docs.optimism.io/app-developers/tools-sdks/data/oracles

Learn about different oracles and how you can use them to access offchain data onchain as well as random number generation.

<Info>
  This page includes providers that meet specific [inclusion criteria](#inclusion-criteria), as outlined below. Please visit the [community oracles page](https://github.com/ethereum-optimism/developers/blob/main/community/tools/oracles.md) for an additional listing of third-party Oracles.
</Info>

This reference guide lists different Oracles you can use when building on Optimism. [Oracles](https://ethereum.org/en/developers/docs/oracles/) provide offchain data onchain. This allows code running on a blockchain to access a wide variety of information.
For example, a [stablecoin](https://ethereum.org/en/stablecoins/) that accepts ETH as collateral needs to know the ETH/USD exchange rate:

* How many stablecoins can we give a user for a given amount of ETH?
* Do we need to liquidate any deposits because they are under collateralized?

## Security and decentralization

Different oracles have different security assumptions and different levels of decentralization.
Usually they are either run by the organization that produces the information, or have a mechanism to reward entities that provide accurate information and penalize those that provide incorrect information.

## Types of oracles

There are two types of oracles:

1. **Push oracles** are updated continuously and always have up to date information available onchain.

2. **Pull oracles** are only updated when information is requested by a contract.
   Pull oracles are themselves divided into two types:
   1. Double-transaction oracles, which require two transactions.
      The first transaction is the request for information, which usually causes the oracle to emit an event that triggers some offchain mechanism to provide the answer (through its own transaction).
      The second transaction actually reads onchain the result from the oracle and uses it.
   2. Single-transaction oracles, which only require one transaction. The way this works is that the transaction that requests the information includes a callback (address and the call data to provide it).
      When the oracle is updated (which also happens through a transaction, but one that is not sent by the user), the oracle uses the callback to inform a contract of the result.

## Random number generation (RNG)

Random number generation in blockchain applications ensures that smart contracts can access unbiased random values. This is essential for certain use cases like generative NFTs, gaming, commit & reveal schemes and more. Various approaches include using a trusted third party, blockhash-based methods, Verifiable Random Functions (VRF), quantum random numbers to name a few. Each method has trade-offs between simplicity, security, and trust assumptions, allowing developers to select the most suitable option for their use case.

## List of oracles

### Gas oracle

OP Mainnet provides a [Gas Price Oracle](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/GasPriceOracle.sol) that provides information about [gas prices and related parameters](/op-stack/transactions/fees).
It can also calculate the total cost of a transaction for you before you send it.

This contract is a predeploy at address `0x420000000000000000000000000000000000000F`:

* [On OP Mainnet](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F#readContract)
* [On OP Sepolia](https://testnet-explorer.optimism.io/address/0x420000000000000000000000000000000000000F)

This is a push Oracle.
OP Mainnet (and the testnets) updates the gas price parameters onchain whenever those parameters change.
The L1 gas price, which can be volatile, is only pushed once every 5 minutes, and each time can change only by up to 20%.

* [Blocknative](https://docs.blocknative.com/gas-prediction) provides real-time gas estimation powered by predictive modeling to forecast gas price distribution for select OP Stack chains, including OP Mainnet and Base. The [API](https://docs.blocknative.com/gas-prediction) is also available on Ethereum Mainnet to estimate base fee costs.

### API3

The [API3 Market](https://market.api3.org/optimism) provides access to 200+ price feeds on [Optimism Mainnet](https://market.api3.org/optimism) and [Testnet](https://market.api3.org/optimism-sepolia-testnet). The price feeds operate as a native push oracle and can be activated instantly via the Market UI.

The price feeds are delivered by an aggregate of [first-party oracles](https://docs.api3.org/oev-searchers/glossary.html#first-party-oracles) using signed data and support [OEV recapture](https://docs.api3.org/dapps/integration/security-considerations.html#oracle-extractable-value-oev).
Unlike traditional data feeds, reading [API3 price feeds](https://docs.api3.org/oev-searchers/in-depth/#dapps-catalog) enables dApps to auction off the right to update the price feeds to searcher bots which facilitates more efficient liquidation processes for users and LPs of DeFi money markets. The OEV recaptured is returned to the dApp.

API3's QRNG provides dApps with truly random numbers based on quantum mechanics at no charge. More details are available on the [API3 website](https://api3.org/).

### Chainlink

[Chainlink](https://chain.link/) is the industry-standard decentralized computing platform powering the verifiable web.
Chainlink powers verifiable applications and high-integrity markets for banking, DeFi, global trade, gaming, and other major sectors.

Chainlink provides a number of [price feeds](https://docs.chain.link/docs/optimism-price-feeds/).
Those feeds are available on the production network @ [OP Mainnet](https://docs.chain.link/data-feeds/price-feeds/addresses?network=optimism\&page=1#optimism-mainnet).

* Data Feeds: Chainlink Data Feeds provide a secure, reliable, and decentralized source of off-chain data to power unique smart contract use cases for DeFi and beyond.
* Automation: Chainlink Automation is an ultra-reliable and performant smart contract automation solution enabling developers to quickly scale their operations in a verifiable, decentralized, and cost-efficient manner, to build next-generation apps.
* CCIP: Chainlink CCIP provides a secure interoperability protocol for powering token transfers and sending arbitrary messages cross-chain.

This is a push Oracle. See the [Using Data Feeds guide](https://docs.chain.link/docs/get-the-latest-price/) to learn how to use the Chainlink feeds.

* Chainlink VRF provides cryptographically secure randomness for blockchain-based applications. More details [here](https://chain.link/vrf)

### Chronicle

The first Oracle on Ethereum, Chronicle's decentralized Oracle network was originally built within MakerDAO for the development of DAI and is now available to builders on OP Mainnet and OP Stack chains.

* **Data Feeds**: Builders can choose from 65+ data feeds, including crypto assets, yield rates, and RWAs. Chronicle's data is sourced via custom-built data models, only utilizing Tier 1 Primary Sources, such as the markets where tokens are actively traded, including Coinbase, Binance, Uniswap, and Curve.
* **Transparency & Integrity**: Chronicle's Oracle network is fully transparent and verifiable. Via [The Chronicle](https://chroniclelabs.org/dashboard/oracle/DAI/USD?blockchain=OPT\&txn=0x53e60e6e79eb938e5ca3ca6c56b0795e003dd6b3a17cfd810ca5042b3d33b680\&contract=0x104916d38828DA8B83a88A1775Aa058e1F0B1647), the data supply chain for any Oracle can be viewed in real-time and historically, including data sources and the identity of all Validators/Signers. Users can cryptographically challenge the integrity of every Oracle update using the 'verify' feature. Data is independently sourced by a [community of Validators](https://chroniclelabs.org/validators), including Gitcoin, Etherscan, Infura, DeFi Saver, and MakerDAO.
* **Gas Efficiency:** Pioneering the Schnorr-based Oracle architecture, Chronicle's Oracles use 60-80% less gas per update than other Oracle providers. This lowest cost per update allows Push Oracle updates to be made more regularly, ensuring more accurate and granular data reporting.

Every Oracle implementation is customized to fit your needs. Implement one of our existing data models or contact Chronicle to develop custom Oracle data feeds via [Discord](https://discord.gg/CjgvJ9EspJ) or [Email](mailto:gm@chroniclelabs.org). Developers can dive deeper into Chronicle Protocol's architecture and unique design choices [via the docs](https://docs.chroniclelabs.org/).

### Gelato

[Gelato VRF](https://www.gelato.network/) enables smart contracts on Optimism to access verifiable randomness. Gelato VRF offers real randomness for blockchain applications by leveraging Drand, a trusted decentralized source for random numbers.

Gelato VRF (Verifiable Random Function) provides trustable randomness on EVM-compatible blockchains. Here's a brief overview:

* Contract Deployment: Use GelatoVRFConsumerBase.sol as an interface for requesting random numbers.
* Requesting Randomness: Emit the RequestedRandomness event to signal the need for a random number.
* Processing: Gelato VRF fetches the random number from Drand.
* Delivery: The fulfillRandomness function delivers the random number to the requesting contract.

Ready to integrate? Head over to the [Gelato VRF Quick Start Guide](https://docs.gelato.network/web3-services/vrf/quick-start).

### Pyth Network

The Pyth Network is a financial oracle network which delivers over 400 low-latency, high-fidelity price feeds across cryptocurrencies, FX pairs, equities, ETFs, and commodities.

* Pyth's price data is sourced from over [95 first-party sources](https://pyth.network/publishers) including exchanges, market makers, and financial services providers.
* Pyth [Price Feeds](https://www.pyth.network/developers/price-feed-ids) offer both the real-time spot price of the asset as well as an accompanying confidence interval band around that price
* The Pyth [TradingView](https://docs.pyth.network/guides/how-to-create-tradingview-charts) integration allows users to view and display Pyth prices on their own website and UI.

You can explore the full catalog of Pyth Price Feed IDs for [OP Mainnet and Sepolia (EVM Stable)](https://www.pyth.network/developers/price-feed-ids).

* Pyth Entropy allows developers to quickly and easily generate secure random numbers on the blockchain. More details [here](https://pyth.network/blog/secure-random-numbers-for-blockchains)

### RedStone

[RedStone](https://redstone.finance/) offers flexible Data Feeds for Lending Markets, Perpetuals, Options, Stablecoins, Yield Aggregators and other types of novel DeFi protocols. The infrastructure is well battle-tested and secures hundreds of millions of USD across mainnet.

Builders can choose how they want to consume the data among 3 dedicated models:

* [RedStone Core](https://docs.redstone.finance/docs/dapps/redstone-pull/) (pull oracle) - less than 10s update time, broad spectrum of feeds, best for most use cases. All [Core Price Feeds](https://app.redstone.finance/#/app/tokens) are available on OP Mainnet & OP Sepolia.
* [RedStone Classic](https://docs.redstone.finance/docs/dapps/redstone-push/) (push oracle) - for protocols designed for the traditional oracle interface, customizable heartbeat and deviation threshold.
* [Hybrid (push + push) ERC7412](https://docs.redstone.finance/docs/dapps/redstone-erc7412/) - specifically for Perps and Options, highest update frequency and front-running protection.

Interested in integration? [Get in contact](https://discord.com/invite/PVxBZKFr46) with the RedStone team!

### Stork

[Stork](https://stork.network) delivers price feeds with ultra-low latency, high uptime, and broad asset coverage for DeFi applications on OP Mainnet and OP Stack chains.

* **Ultra-Low Latency**: Stork provides price data at ultra-low latency, enabling protocols to maintain functionality during high-volatility periods and support time-sensitive trading operations.
* **High Reliability**: With best-in-class uptime and reliability, Stork supports perpetuals markets, lending protocols, and DeFi ecosystems that require consistent data availability.
* **Day 1 Asset Support**: Price feeds for new digital assets are available from Day 1, allowing protocols to launch new markets immediately after token generation events.
* **Broad Coverage**: Stork provides comprehensive asset coverage across crypto assets, equities, ETFs and commodities, supporting a wide range of DeFi use cases from derivatives trading to collateralized lending.

Visit the [Stork documentation](https://docs.stork.network) to get started.

### DIA

[DIA](https://www.diadata.org/) is a cross-chain, trustless oracle network delivering verifiable price feeds for Optimism. DIA sources raw trade data directly from primary markets and computes it onchain, ensuring complete transparency and data integrity.

* Complete verifiability from source to destination smart contract.
* Direct data sourcing from 100+ primary markets eliminating intermediary risk.
* Support for 20,000+ assets across all major asset classes.
* Custom oracle configuration with tailored sources and methodologies.

To get started:

* [Explore the Optimism Oracle Integration Guide](https://www.diadata.org/docs/guides/chain-specific-guide/optimism)
* [Request a Custom Oracle](https://www.diadata.org/docs/guides/how-to-guides/request-a-custom-oracle)

## Next steps

* Looking for other developer tools? See the [building apps overview](/app-developers/guides/building-apps) to explore more options!


# Testnet faucets
Source: https://docs.optimism.io/app-developers/tools-sdks/faucets

Learn how to get testnet ETH on test networks like Sepolia and OP Sepolia for development and testing purposes.

Faucets are developer tools that allow you to get free ETH (and other tokens) on test networks like Sepolia and OP Sepolia so that you can send transactions and create smart contracts.
Here you'll find a list of active faucets that you can try out.
Different faucets use different authentication methods, so you may have to try a few before you find one that works for you.
Faucets can occasionally also run out of ETH, so if you're having trouble getting ETH from a faucet, try another one.

<Info>
  Tokens on test networks like Sepolia or OP Sepolia have no value and are only meant for testing.
  Optimists only take what they need so that others can use faucets too!
</Info>

## Optimism's faucet

The [Optimism's faucet](https://console.optimism.io/faucet?utm_source=op-docs\&utm_medium=docs) is a developer tool hosted by Optimism that allows developers to get free testnet ETH to test apps on testnet OP Chains like Base Sepolia, OP Sepolia, PGN Sepolia, Zora Sepolia, and other OP Stack chains.
Optimism's faucet is a great place to start if you're looking for testnet ETH.

## Additional faucets

| Faucet Name                                                                                                                     | Supported Networks                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [Alchemy Faucet](https://sepoliafaucet.com)                                                                                     | Sepolia                                                                                                                                      |
| [Chain Platform Faucet](https://faucet.chainplatform.co/faucets/ethereum-sepolia/)                                              | Sepolia                                                                                                                                      |
| [Ethereum Ecosystem Faucets](https://www.ethereum-ecosystem.com/faucets)                                                        | Sepolia, OP Sepolia, Base Sepolia                                                                                                            |
| [ETHGlobal Testnet Faucet](https://ethglobal.com/faucet)                                                                        | Sepolia, OP Sepolia, Base Sepolia, Zora Sepolia, Holesky                                                                                     |
| [Farcaster Frame Faucet by LearnWeb3](https://warpcast.com/haardikkk/0x28f4237d)                                                | Sepolia, OP Sepolia                                                                                                                          |
| [Infura Faucet](https://www.infura.io/faucet/sepolia)                                                                           | Sepolia                                                                                                                                      |
| [Native USDC Faucet](https://faucet.circle.com/)                                                                                | Sepolia, OP Sepolia                                                                                                                          |
| [QuickNode Faucet](https://faucet.quicknode.com/optimism/)                                                                      | Sepolia, OP Sepolia                                                                                                                          |
| [Tenderly Unlimited Faucet](https://docs.tenderly.co/virtual-testnets/unlimited-faucet?mtm_campaign=ext-docs\&mtm_kwd=optimism) | OP Sepolia, OP Mainnet, and [85+ other networks](https://docs.tenderly.co/supported-networks?mtm_campaign=ext-docs\&mtm_kwd=optimism)        |
| [thirdweb OP Sepolia Faucet](https://thirdweb.com/op-sepolia-testnet?utm_source=opdocs\&utm_medium=docs)                        | OP Sepolia                                                                                                                                   |
| [thirdweb Sepolia Faucet](https://thirdweb.com/sepolia?utm_source=opdocs\&utm_medium=docs)                                      | Sepolia                                                                                                                                      |
| [ethfaucet.com](https://ethfaucet.com?utm_source=opdocs\&utm_medium=docs)                                                       | Sepolia, OP Sepolia, Base Sepolia, Zora Sepolia, Unichain Sepolia, Ink Sepolia, Mode Sepolia, Shape Sepolia, Worldchain Sepolia, BOB Sepolia |

## Bridge from Sepolia

If you have testnet ETH on Sepolia, you can bridge it to OP Sepolia (and vice versa) using the [Superchain Bridges UI](https://app.optimism.io/bridge/?utm_source=op-docs\&utm_medium=docs) or this collection of [Superchain Testnet Tools](https://www.superchain.tools/).

## Next steps

* If you're new to onchain development, check out [Optimism Unleashed](https://cryptozombies.io/en/optimism) by CryptoZombies and [Superchain Builder NFT](https://web.archive.org/web/20231218203510/https://blog.thirdweb.com/guides/optimism-superchain-faucet-nft/) by ThirdWeb.
* If you're familiar with onchain development, check out the [Optimism Ecosystem's Contributions Dashboard](https://github.com/ethereum-optimism/ecosystem-contributions) for project ideas that Optimism is looking for.
* Looking for other developer tools? See the [building apps overview](/app-developers/guides/building-apps) to explore more options!


# Tools & SDKs Listing Criteria
Source: https://docs.optimism.io/app-developers/tools-sdks/listing-criteria

What a tool or SDK must meet to be listed on the support matrix, the removal rule, and the maintenance sweep that keeps listings accurate.

This page governs the [Tools & SDKs support matrix](/app-developers/tools-sdks/support-matrix).
It exists so that adding or removing a listing is the application of written
policy, not a per-pull-request argument. The approach follows the
[ethereum.org product-listing policy](https://ethereum.org/en/contributing/adding-products/),
which uses published criteria plus a standing removal rule for the same reason.

Listings must also satisfy the site-wide
[content guide](/op-stack/contribute/content-guide): the matrix is a routing
page (clause 3 of the three-clause test), so every listing links one canonical
documentation home and restates nothing.

## Listing Criteria

A tool or SDK is eligible for the matrix only if **all** of the following hold:

1. **Open source, public repository.** The source is publicly available and
   the repository is linkable from the matrix.
2. **Works with the OP Stack as documented.** A developer can follow the
   tool's own quickstart against an OP Stack chain and succeed. Listings for
   tools that only incidentally support the OP Stack must link the
   OP-Stack-relevant entry point, not a generic homepage.
3. **Actively maintained.** The project ships releases and responds to
   issues. An archived or visibly abandoned repository is disqualifying.
4. **Has one canonical documentation home.** There is a single place we can
   link as the source of truth (per the content guide's dual-sourcing ban we
   will not maintain a copy of its documentation here).
5. **Honest support status.** The listing's support status must match what
   the owner declares in its own repository or docs. Experimental or preview
   software is listed as such, never as production.
6. **Third-party listings are marked.** Any listing not owned by the Optimism
   Collective passes through the `<ThirdPartyContent>` component, per the
   [content guide](/op-stack/contribute/content-guide).

## Proposing a Listing

Open a pull request against the
[matrix page](/app-developers/tools-sdks/support-matrix) that adds one row and,
in the PR description, states how the tool meets each criterion above — with
links as evidence (repository, docs home, release page, the owner's own status
declaration). Reviewers apply this page; if a criterion is unclear, the fix is
a PR to this page, not an exception.

## Removal Rule

A listing is removed — not left stale — when it no longer meets the criteria.
Typical triggers:

* The repository is archived, or releases and issue activity have stopped.
* The documented quickstart no longer works against an OP Stack chain.
* The canonical docs home is gone or no longer maintained.
* The owner's declared status changed and the listing was not updated
  (in that case, update the row instead if the tool still qualifies).

Removal is an ordinary pull request that cites the failed criterion. Rows are
never soft-deprecated in place: the ethereum.org experience this policy is
modeled on shows that stale curated tables are worse than absent ones.

## Maintenance Sweep

Curated listings rot silently, so accuracy is maintained by a scheduled sweep
rather than by hoping readers report drift:

* **What is checked.** Every sweep re-verifies all four cells of every row —
  purpose, owner, canonical docs link, and support status — against the
  upstream repository and docs, and re-checks each criterion above.
* **What is recorded.** The sweep PR (or its "no changes" note) lists what
  was checked and the upstream sources consulted, so the next sweep starts
  from evidence.
* **Who runs it.** The docs maintainers own the sweep as part of the
  standing docs review rotation; anyone may run one ahead of schedule by
  opening the same kind of PR.
* **Outcome.** Each row is updated, confirmed, or removed under the
  removal rule. A sweep that cannot verify a row treats it as failing.

## Next Steps

* Browse the [Tools & SDKs support matrix](/app-developers/tools-sdks/support-matrix).
* Read the [content guide](/op-stack/contribute/content-guide) for the
  site-wide rules this policy inherits.


# Consensus
Source: https://docs.optimism.io/app-developers/tools-sdks/op-alloy/building/consensus



The `op-alloy-consensus` crate provides an Optimism consensus interface.
It contains constants, types, and functions for implementing Optimism EL
consensus and communication. This includes an extended `OpTxEnvelope` type
with [deposit transactions](https://specs.optimism.io/protocol/deposits.html), and receipts containing OP Stack
specific fields (`deposit_nonce` + `deposit_receipt_version`).

In general a type belongs in this crate if it exists in the
`alloy-consensus` crate, but was modified from the base Ethereum protocol
in the OP Stack. For consensus types that are not modified by the OP Stack,
the `alloy-consensus` types should be used instead.

## Block

[`op-alloy-consensus`](https://crates.io/crates/op-alloy-consensus) exports an Optimism block type, [`OpBlock`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/type.OpBlock.html).

This type simply re-uses the `alloy-consensus` block type, with `OpTxEnvelope`
as the type of transactions in the block.

## Transactions

Optimism extends the Ethereum [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) transaction envelope to include a
deposit variant.

### [`OpTxEnvelope`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/transaction/enum.OpTxEnvelope.html)

The [`OpTxEnvelope`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/transaction/enum.OpTxEnvelope.html) type is based on [Alloy](https://github.com/alloy-rs/alloy)'s
`TxEnvelope` type.

Optimism modifies the `TxEnvelope` to the following.

* Legacy
* EIP-2930
* EIP-1559
* EIP-7702
* Deposit

Deposit is a custom transaction type that is either an L1 attributes
deposit transaction or a user-submitted deposit transaction. Read more
about deposit transactions in [the specs](https://specs.optimism.io).

### Transaction Types ([`OpTxType`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/transaction/enum.OpTxType.html))

The [`OpTxType`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/transaction/enum.OpTxType.html) enumerates the transaction types using their byte identifier,
represents as a `u8` in rust.

## Receipt Types

Just like [`op-alloy-consensus`](https://crates.io/crates/op-alloy-consensus) defines transaction types,
it also defines associated receipt types.

[`OpReceiptEnvelope`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/enum.OpReceiptEnvelope.html) defines an [Eip-2718](https://eips.ethereum.org/EIPS/eip-2718) receipt envelope type
modified for the OP Stack. It contains the following variants - mapping
directly to the `OpTxEnvelope` variants defined above.

* Legacy
* EIP-2930
* EIP-1559
* EIP-7702
* Deposit

There is also an [`OpDepositReceipt`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/struct.OpDepositReceipt.html) type, extending the alloy receipt
type with a deposit nonce and deposit receipt version.


# RPC Engine Types
Source: https://docs.optimism.io/app-developers/tools-sdks/op-alloy/building/engine



The [`op-alloy-rpc-types-engine`](https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/) crate provides Optimism types for interfacing
with the Engine API in the OP Stack.

Optimism defines a custom payload attributes type called [`OpPayloadAttributes`](https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/struct.OpPayloadAttributes.html).
`OpPayloadAttributes` extends alloy's [`PayloadAttributes`](https://docs.rs/alloy-rpc-types-engine/latest/alloy_rpc_types_engine/payload/struct.PayloadAttributes.html) with a few fields: transactions,
a flag for enabling the tx pool, the gas limit, EIP 1559 parameters, and a
minimum base fee (used after the Jovian hardfork).

Optimism also returns a custom type for the `engine_getPayload` request for both V3 and
V4 payload envelopes. These are the [`OpExecutionPayloadEnvelopeV3`](https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/payload/v3/struct.OpExecutionPayloadEnvelopeV3.html) and
[`OpExecutionPayloadEnvelopeV4`](https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/payload/v4/struct.OpExecutionPayloadEnvelopeV4.html) types, which both wrap payload envelope types
from [`alloy-rpc-types-engine`](https://crates.io/crates/alloy-rpc-types-engine).


# Building
Source: https://docs.optimism.io/app-developers/tools-sdks/op-alloy/building/index



This section offers in-depth documentation into the various `op-alloy` crates.
Some of the primary crates and their types are listed below.

* [`op-alloy-consensus`](https://crates.io/crates/op-alloy-consensus) provides [`OpBlock`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/type.OpBlock.html),
  [`OpTxEnvelope`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/transaction/enum.OpTxEnvelope.html), [`OpReceiptEnvelope`](https://docs.rs/op-alloy-consensus/latest/op_alloy_consensus/enum.OpReceiptEnvelope.html),
  and more.
* [`op-alloy-rpc-types-engine`](https://crates.io/crates/op-alloy-rpc-types-engine) provides the
  [`OpPayloadAttributes`](https://docs.rs/op-alloy-rpc-types-engine/latest/op_alloy_rpc_types_engine/struct.OpPayloadAttributes.html).


# op-alloy
Source: https://docs.optimism.io/app-developers/tools-sdks/op-alloy/intro



Welcome to the hands-on guide for getting started with `op-alloy`!

`op-alloy` connects applications to the OP Stack, leveraging high
performance types, traits, and middleware from [Alloy](https://github.com/alloy-rs/alloy).

<Warning>
  **Development Status**

  `op-alloy` is in active development, and is not yet ready for use in production.
  During development, this documentation will evolve quickly and may contain inaccuracies.

  Please [open an issue](https://github.com/ethereum-optimism/optimism/issues/new) if you find any errors or have any suggestions for
  improvements, and also feel free to [contribute](https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md) to the project!
</Warning>

## Sections

### [Getting Started](/app-developers/tools-sdks/op-alloy/starting)

To get started with op-alloy, add its crates as a dependency and take your first steps.

### [Building with op-alloy](/app-developers/tools-sdks/op-alloy/building/index)

Walk through types and functionality available in different `op-alloy` crates.

### [Contributing](https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md)

Contributors are welcome! It is built and maintained by Alloy contributors,
members of [OP Labs](https://github.com/ethereum-optimism), and the broader open source community.

`op-alloy` follows and expands the OP Stack standards set in the [specs](https://specs.optimism.io).

### Licensing

`op-alloy` is licensed under the combined Apache 2.0 and MIT License, along
with a SNAPPY license for snappy encoding use.


# Add op-alloy to your project
Source: https://docs.optimism.io/app-developers/tools-sdks/op-alloy/starting

Add the op-alloy crates to a Rust project with Cargo and pick the feature flags you need.

[op-alloy](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-alloy) consists of a number of crates that provide a range of functionality
essential for interfacing with any OP Stack chain.

The most succinct way to work with `op-alloy` is to add the [`op-alloy`](https://crates.io/crates/op-alloy) crate
with the `full` feature flag from the command-line using Cargo.

```txt theme={null}
cargo add op-alloy --features full
```

Alternatively, you can add the following to your `Cargo.toml` file.

```txt theme={null}
op-alloy = { version = "2.0", features = ["full"] }
```

For more fine-grained control over the features you wish to include, you can add the individual
crates to your `Cargo.toml` file, or use the `op-alloy` crate with the features you need.

After `op-alloy` is added as a dependency, crates re-exported by `op-alloy` are now available.

```rust theme={null}
use op_alloy::{
   consensus::OpBlock,
   network::Optimism,
   rpc_types::OpTransactionReceipt,
   rpc_types_engine::OpPayloadAttributes,
};
```

## Features

The [`op-alloy`](https://crates.io/crates/op-alloy) defines many [feature flags](https://docs.rs/crate/op-alloy/latest/features) including the following.

Default

* `std`
* `k256`
* `serde`

Full enables the most commonly used crates: `consensus`, `network`, `rpc-types`,
`rpc-types-engine`, and `rpc-jsonrpsee`. The `provider` crate is not part of `full`
and is enabled with its own `provider` feature.

* `full`

The `k256` feature flag enables the `k256` feature on the `op-alloy-consensus` crate.

* `k256`

Arbitrary enables arbitrary features on crates, deriving the `Arbitrary` trait on types.

* `arbitrary`

Serde derives serde's Serialize and Deserialize traits on types.

* `serde`

Additionally, individual crates can be enabled using their shorthand names.
For example, the `consensus` feature flag provides the `op-alloy-consensus` re-export
so `op-alloy-consensus` types can be used from `op-alloy` through `op_alloy::consensus::InsertTypeHere`.

## Crates

* [`op-alloy-network`](https://crates.io/crates/op-alloy-network)
* [`op-alloy-provider`](https://crates.io/crates/op-alloy-provider)
* [`op-alloy-consensus`](https://crates.io/crates/op-alloy-consensus) (supports `no_std`)
* [`op-alloy-rpc-jsonrpsee`](https://crates.io/crates/op-alloy-rpc-jsonrpsee)
* [`op-alloy-rpc-types`](https://crates.io/crates/op-alloy-rpc-types) (supports `no_std`)
* [`op-alloy-rpc-types-engine`](https://crates.io/crates/op-alloy-rpc-types-engine) (supports `no_std`)

## `no_std`

As noted above, the following crates are `no_std` compatible.

* [`op-alloy-consensus`](https://crates.io/crates/op-alloy-consensus)
* [`op-alloy-rpc-types-engine`](https://crates.io/crates/op-alloy-rpc-types-engine)
* [`op-alloy-rpc-types`](https://crates.io/crates/op-alloy-rpc-types)

To add `no_std` support to a crate, ensure the [check\_no\_std](https://github.com/ethereum-optimism/optimism/blob/develop/rust/op-alloy/scripts/check_no_std.sh)
script is updated to include this crate once `no_std` compatible.


# op-revm
Source: https://docs.optimism.io/app-developers/tools-sdks/op-revm

op-revm is the Optimism variant of revm, implementing OP Stack modifications to the EVM.

`op-revm` is the Optimism variant of [revm](https://github.com/bluealloy/revm) —
the OP Stack's modifications to the Ethereum Virtual Machine, packaged as a
custom EVM built on top of the upstream `revm` framework.

## Features

`op-revm` extends `revm` with everything the OP Stack needs on top of vanilla
Ethereum execution:

* **Deposit transactions** — the L1-to-L2 deposit transaction type and its
  execution semantics.
* **L1 cost accounting** — `L1BlockInfo` and per-transaction L1 fee / blob fee
  calculation.
* **Operator fees** — operator fee handling introduced in Isthmus and refined
  in Jovian.
* **OP-specific precompiles** — including accelerated BN254 pairing.
* **OP halt reasons & transaction errors** — OP Stack–specific execution
  failure modes.
* **Hardfork-aware spec selection** — `OpSpecId` selects the right behavior for
  each OP Stack hardfork (Bedrock, Regolith, Canyon, Ecotone, Fjord, Granite,
  Holocene, Isthmus, Jovian, …).

## Provenance

`op-revm` is vendored from upstream
[`bluealloy/revm`'s `crates/op-revm`](https://github.com/bluealloy/revm/tree/main/crates/op-revm)
and imported into the monorepo so it can evolve in lock-step with the rest of
the OP Stack Rust code. The upstream release history lives in the
[revm releases](https://github.com/bluealloy/revm/releases).

## Crate features

The crate exposes the usual `revm` feature knobs, forwarded through to the
underlying `revm` crate:

* `default = ["std", "c-kzg", "secp256k1", "portable", "blst"]`
* `std` — enables `std`-dependent code paths in `revm`, `alloy-primitives`,
  `serde_json`, etc.
* `serde` — derives `serde` impls and forwards to `revm/serde` and
  `alloy-primitives/serde`.
* `portable`, `c-kzg`, `secp256k1`, `blst`, `bn` — pass-through feature gates
  for the cryptographic backends.
* `dev`, `memory_limit`, `optional_balance_check`, `optional_block_gas_limit`,
  `optional_eip3541`, `optional_eip3607`, `optional_no_base_fee`,
  `optional_fee_charge` — debugging and testing knobs forwarded to `revm`.

`op-revm` supports `no_std` builds: disabling default features (or building
with `--no-default-features`) produces a crate suitable for fault-proof and
zkVM targets such as `riscv32imac-unknown-none-elf`.

## Building & testing

From the `rust/` workspace root:

```bash theme={null}
# Build
cargo build -p op-revm

# Run tests with all features
cargo nextest run -p op-revm --all-features

# no_std check (mirrors upstream's riscv32imac CI)
cargo build -p op-revm \
  --target riscv32imac-unknown-none-elf \
  --no-default-features
```

The `no_std` build is also exercised by `just check-no-std` and runs in CI on
every PR that touches `rust/**`.

## Using op-revm

`op-revm` is the EVM used by [op-reth](/op-stack/components/op-reth) for OP Stack block
execution, and by [Kona](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona) inside the fault-proof
program and rollup node. Most users will consume it transitively through one
of those components rather than depending on it directly; depend on `op-revm`
directly only when building a custom OP Stack execution environment (for
example, an alternate client or a zkVM proof backend).

## License

`op-revm` is licensed under the MIT License — see
[`rust/op-revm/LICENSE`](https://github.com/ethereum-optimism/optimism/blob/develop/rust/op-revm/LICENSE).


# Supersim Multichain Development Environment
Source: https://docs.optimism.io/app-developers/tools-sdks/supersim

Learn how to use the Supersim local dev environment tool designed to simulate the OP Stack multi-chain environment.

<Info>
  Interop is currently in active development and not yet ready for production use. The information provided here may change. Check back regularly for the most up-to-date information.
</Info>

[Supersim](https://github.com/ethereum-optimism/Supersim) is a local development environment tool designed to simulate the OP Stack for developers building multi-chain applications. It provides a simplified way to test and develop applications that interact with multiple chains within the OP Stack ecosystem.

## Supersim workflow

```mermaid theme={null}
graph LR
    A[Write Smart Contracts] --> B[Deploy on Supersim]
    B --> C[Test Cross-Chain Interactions]
    C --> D[Debug and Refine]
    D --> B
    C --> E[Ready for Production]
```

This diagram illustrates the typical workflow for developers using Supersim, from writing smart contracts to testing and refining cross-chain interactions.

## Features and benefits

* Simulates multiple OP Stack chains locally (e.g., chain 901, 902)
* Supports testing of cross-chain messaging and interactions
* Includes pre-deployed interoperability contracts
* Offers a CLI interface for starting and managing Supersim instances
* Provides local JSON-RPC endpoints for each simulated chain
* Allows for custom configuration of chain parameters
* Facilitates testing of Superchain-specific features like cross-chain token transfers
* Easy to use with common Ethereum development tools
* Supports chain forking

## Supersim CLI interaction

```mermaid theme={null}
graph TD
    A[Developer] --> B[Supersim CLI]
    B --> C[Chain 901]
    B --> D[Chain 902]
    B --> E[...]
    C --> F[JSON-RPC Endpoint]
    D --> G[JSON-RPC Endpoint]
    E --> H[JSON-RPC Endpoint]
```

This diagram illustrates how developers interact with Supersim through the CLI, which simulates OP Stack-specific features (specifically interop) on locally run chains, each with its own JSON-RPC endpoint and pre-deployed interoperability contracts.

## Next steps

* View more [Supersim tutorials](/app-developers/tutorials/development/supersim/first-steps)


# Tools & SDKs Support Matrix
Source: https://docs.optimism.io/app-developers/tools-sdks/support-matrix

One page that differentiates the OP Stack SDK surfaces and developer tools — what each is for, who owns it, where its canonical docs live, and its support status.

<Warning>
  Items on this page refer to third-party projects or products that are not
  maintained by Optimism. They are provided for convenience; refer to each
  project's own documentation as the source of truth.
</Warning>

This page is the canonical hub for the tools and SDKs that surround the OP Stack.
Following the [content guide](/op-stack/contribute/content-guide), each listing
links exactly one canonical documentation home — this page routes, it does not
restate. What gets listed here (and what gets removed) is governed by the
[listing criteria](/app-developers/tools-sdks/listing-criteria).

## Support Status Levels

| Status                | Meaning                                                                                    |
| --------------------- | ------------------------------------------------------------------------------------------ |
| **Production**        | Stable and recommended for production use by its owner.                                    |
| **Developer preview** | Usable today, but its owner has declared it not yet ready for production; APIs may change. |
| **Experimental**      | A staging ground. Features may change, move, or be upstreamed elsewhere.                   |

## The Matrix

| Tool                                                                                           | Purpose                                                                                                                                                                                                    | Owner                                                                                                                                                                                              | Canonical docs                                                                                                                                | Support status                                                                                  |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [`viem/op-stack`](https://viem.sh/op-stack)                                                    | General-purpose TypeScript client for OP Stack chains: deposits, withdrawals, L1 gas estimation, and all standard chain interaction, built into viem                                                       | [wevm](https://github.com/wevm/viem) (third party)                                                                                                                                                 | [viem.sh/op-stack](https://viem.sh/op-stack)                                                                                                  | Production                                                                                      |
| [`@eth-optimism/viem`](https://github.com/ethereum-optimism/ecosystem/tree/main/packages/viem) | viem extension for OP Stack features that have not yet been upstreamed into viem — Superchain interop actions and utilities; used by this site's bridging and interop tutorials                            | Optimism ([`ecosystem`](https://github.com/ethereum-optimism/ecosystem) repo)                                                                                                                      | [Package README & SDK reference](https://github.com/ethereum-optimism/ecosystem/tree/main/packages/viem#readme)                               | Experimental                                                                                    |
| [Actions SDK](https://github.com/ethereum-optimism/actions) (`@eth-optimism/actions-sdk`)      | High-level abstractions for building onchain apps — wallet, lend, and swap namespaces over Superchain protocols                                                                                            | Optimism ([`actions`](https://github.com/ethereum-optimism/actions) repo)                                                                                                                          | [Actions quickstart](/app-developers/quickstarts/actions) and [reference](/app-developers/reference/actions/integrating-wallets) on this site | Developer preview                                                                               |
| [wagmi](https://wagmi.sh)                                                                      | React hooks for Ethereum apps; works with OP Stack chains as with any EVM chain                                                                                                                            | [wevm](https://github.com/wevm/wagmi) (third party)                                                                                                                                                | [wagmi.sh](https://wagmi.sh)                                                                                                                  | Production                                                                                      |
| [supersim](/app-developers/tools-sdks/supersim)                                                | Local Superchain simulator: one L1 plus multiple OP Stack L2s for testing L1↔L2 and L2↔L2 message passing without deploying to live networks                                                               | Optimism ([`supersim`](https://github.com/ethereum-optimism/supersim) repo)                                                                                                                        | [Supersim docs](https://supersim.pages.dev)                                                                                                   | Developer preview (all releases are alpha pre-releases; interop features in active development) |
| [super-cli](https://github.com/ethereum-optimism/super-cli) (`sup`)                            | Foundry companion CLI for multichain workflows: deploy and verify contracts on multiple chains at once, bridge funds, use connected wallets                                                                | Optimism ([`super-cli`](https://github.com/ethereum-optimism/super-cli) repo)                                                                                                                      | [Repository README](https://github.com/ethereum-optimism/super-cli#readme)                                                                    | Experimental                                                                                    |
| [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) tooling        | Not an SDK — the source-of-truth library of chain configs that OP Stack software (such as `op-node` and `op-geth`) consumes, plus the `just` tasks and validation checks used to add and verify a chain    | Optimism ([`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry) repo)                                                                                                  | [Registry operations docs](https://github.com/ethereum-optimism/superchain-registry/tree/main/docs)                                           | Production                                                                                      |
| [op-alloy](/app-developers/tools-sdks/op-alloy/intro)                                          | Rust crates for interfacing with OP Stack chains: consensus, RPC, engine, and network types built on the [Alloy](https://github.com/alloy-rs/alloy) ecosystem; the type layer consumed by kona and op-reth | Optimism ([`rust/op-alloy`](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-alloy) in the monorepo)                                                                             | [op-alloy docs](/app-developers/tools-sdks/op-alloy/intro) on this site                                                                       | Developer preview (owner-declared not yet production-ready; APIs may change)                    |
| [op-revm](/app-developers/tools-sdks/op-revm)                                                  | Rust crate implementing the OP Stack's EVM: a revm variant with deposit transactions, L1 and operator fee accounting, and OP-specific precompiles; the EVM inside op-reth and kona                         | Optimism ([`rust/op-revm`](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-revm) in the monorepo, vendored from upstream [`bluealloy/revm`](https://github.com/bluealloy/revm)) | [op-revm docs](/app-developers/tools-sdks/op-revm) on this site                                                                               | Production (consumed transitively through op-reth or kona by most users)                        |

## Choose an SDK Surface

Three of the rows above are TypeScript SDK surfaces that are easy to confuse.
The distinction:

* **Start with [`viem/op-stack`](https://viem.sh/op-stack).** viem provides
  first-class OP Stack support in the core library: extend any viem client
  with `publicActionsL2()` (and friends) imported from `viem/op-stack` to get
  deposits, withdrawals, and L1 gas estimation. If a feature is available
  here, this is its production home. Super Root withdrawal proving requires
  `viem` `2.51.0` or later.
* **Reach for [`@eth-optimism/viem`](https://github.com/ethereum-optimism/ecosystem/tree/main/packages/viem)
  when you need what viem does not have yet.** The package's stated goal is
  to upstream as much as possible into viem itself; until then it is the
  home of Superchain interop actions and other pre-production features. The
  [interop tutorials](/app-developers/tutorials/interoperability/manual-relay)
  and [bridging tutorials](/app-developers/tutorials/bridging/cross-dom-bridge-erc20)
  on this site use it.
* **Use the [Actions SDK](/app-developers/quickstarts/actions) for app-level
  building blocks, not chain plumbing.** Where the two viem surfaces expose
  protocol operations, the Actions SDK offers wallet, lend, and swap
  namespaces for building end-user apps. It is a developer preview and not
  yet ready for production use.

Building in Rust rather than TypeScript? Start from
[op-alloy](/app-developers/tools-sdks/op-alloy/intro) for OP Stack types and RPC
surfaces and [op-revm](/app-developers/tools-sdks/op-revm) for execution, and see
the [Stack Components index](/op-stack/components/index) for the Rust clients
themselves (op-reth, kona-node, kona-client).

## Using wagmi With the OP Stack

If you build with React, you likely start from wagmi — and it works with OP
Stack chains out of the box. OP Stack chains are standard EVM chains, and
`wagmi/chains` ships their definitions (`optimism`, `base`, `zora`, and every
other chain from `viem/chains`). Nothing OP-specific is required for reads,
writes, or wallet connections.

For OP Stack–specific operations — deposits, withdrawals, interop — use the
fact that wagmi is a wrapper over viem:

1. Get a viem client from wagmi with the
   [`useClient`](https://wagmi.sh/react/api/hooks/useClient) or
   [`useConnectorClient`](https://wagmi.sh/react/api/hooks/useConnectorClient)
   hooks, following wagmi's own
   [viem guide](https://wagmi.sh/react/guides/viem).
2. Extend that client with the [`viem/op-stack`](https://viem.sh/op-stack)
   actions and call them directly.

For Superchain interop specifically, the experimental
[`@eth-optimism/wagmi`](https://github.com/ethereum-optimism/ecosystem/tree/main/packages/wagmi)
package provides React hooks (such as `useSendL2ToL2Message`) over
`@eth-optimism/viem`. Treat it like its underlying package: experimental.

## Next Steps

* Read the [listing criteria and maintenance-sweep policy](/app-developers/tools-sdks/listing-criteria)
  that govern this page.
* Adding a chain rather than building an app? See
  [Join the Superchain Registry](/chain-operators/guides/join-superchain-registry).
* For where content belongs in general, see the
  [content guide](/op-stack/contribute/content-guide).


# Transferring ETH
Source: https://docs.optimism.io/app-developers/tutorials/bridging/bridge-crosschain-eth

Learn how to transfer ETH across the OP Stack interop cluster

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

<Info>
  This tutorial provides step-by-step instructions for how to send ETH from one chain in the OP Stack interop cluster to another.
  For a conceptual overview,
  see the [interoperable ETH explainer](/op-stack/interop/superchain-eth-bridge).
</Info>

## Overview

Crosschain ETH transfers across OP Stack chains are facilitated through the [SuperchainETHBridge](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainETHBridge.sol) contract.
This tutorial walks through how to send ETH from one chain to another.
You can do this on [Supersim](/app-developers/tools-sdks/supersim) or production once it is released.

### What you'll build

* A TypeScript application to transfer ETH between chains

### What you'll learn

* How to send ETH on the blockchain and between blockchains
* How to relay messages between chains

## Prerequisites

Before starting this tutorial, ensure your development environment meets the following requirements:

### Technical knowledge

* Intermediate TypeScript knowledge
* Understanding of smart contract development
* Familiarity with blockchain concepts

### Development environment

* Unix-like operating system (Linux, macOS, or WSL for Windows)
* Node.js version 16 or higher
* Git for version control

### Required tools

The tutorial uses these primary tools:

* Foundry: For smart contract development
* Supersim: For local blockchain simulation
* TypeScript: For implementation
* Viem: For blockchain interaction

<Steps>
  <Step title="Install prerequisite software">
    1. Install [Foundry](https://book.getfoundry.sh/getting-started/installation).
    2. Install [Node](https://nodejs.org/en).
    3. Install [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).
       The exact mechanism to do this depends on your operating system; most come with it preinstalled.
  </Step>

  <Step title="Configure the network">
    You can run this tutorial either with [Supersim](/app-developers/tools-sdks/supersim) running locally, or using the [Interop devnet](/app-developers/guides/building-apps).
    Select the correct tab and follow the directions.

    <Tabs>
      <Tab title="Supersim">
        1. Follow [Install Supersim](/app-developers/tutorials/development/supersim/installation) to set up Supersim for running blockchains with Interop.

        2. Start Supersim.

           ```sh theme={null}
           ./supersim --interop.autorelay
           ```

        3. Supersim uses Foundry's `anvil` blockchains, which start with ten prefunded accounts.
           Set these environment variables to access one of those accounts on the L2 blockchains.

           ```sh theme={null}
           export PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
           ```

        4. Specify the URLs to the chains.

           ```sh theme={null}
           SRC_URL=http://localhost:9545
           DST_URL=http://localhost:9546
           ```

        <Expandable title="Sanity check">
          Get the ETH balances for your address on both the source and destination chains.

          ```sh theme={null}
          cast balance --ether `cast wallet address $PRIVATE_KEY` --rpc-url $SRC_URL
          cast balance --ether `cast wallet address $PRIVATE_KEY` --rpc-url $DST_URL
          ```
        </Expandable>
      </Tab>

      <Tab title="Interop Devnets">
        1. Set `PRIVATE_KEY` to the private key of an address that has [Sepolia ETH](https://cloud.google.com/application/web3/faucet/ethereum/sepolia).

           ```sh theme={null}
           export PRIVATE_KEY=0x <PRIVATE_KEY>
           ```

        2. Send ETH to the two L2 blockchains via their OptimismPortal contracts on Sepolia.

           ```sh theme={null}
           cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIVATE_KEY --value 0.02ether 0x7385d89d38ab79984e7c84fab9ce5e6f4815468a
           cast send --rpc-url https://endpoints.omniatech.io/v1/eth/sepolia/public --private-key $PRIVATE_KEY --value 0.02ether 0x55f5c4653dbcde7d1254f9c690a5d761b315500c
           ```

        3. Wait a few minutes until you can see the ETH [on the block explorer](https://sid.testnet.routescan.io/) for your address.

        4. Specify the URLs to the chains.

           ```sh theme={null}
           SRC_URL=https://interop-alpha-0.optimism.io
           DST_URL=https://interop-alpha-1.optimism.io          
           ```

        <Expandable title="Sanity check">
          Get the ETH balances for your address on both the source and destination chains.

          ```sh theme={null}
          cast balance --ether `cast wallet address $PRIVATE_KEY` --rpc-url $SRC_URL
          cast balance --ether `cast wallet address $PRIVATE_KEY` --rpc-url $DST_URL
          ```
        </Expandable>
      </Tab>
    </Tabs>
  </Step>

  <Step title="Transfer ETH using Foundry">
    Run these commands:

    ```sh theme={null}
    DST_CHAINID=`cast chain-id --rpc-url $DST_URL`
    MY_ADDRESS=`cast wallet address $PRIVATE_KEY`
    SUPERCHAIN_ETH_BRIDGE=0x4200000000000000000000000000000000000024
    BEFORE=`cast balance $MY_ADDRESS --rpc-url $DST_URL | cast from-wei`          
    cast send --rpc-url $SRC_URL --private-key $PRIVATE_KEY $SUPERCHAIN_ETH_BRIDGE "sendETH(address,uint256)" $MY_ADDRESS $DST_CHAINID --value 0.001ether
    sleep 10
    AFTER=`cast balance $MY_ADDRESS --rpc-url $DST_URL | cast from-wei`
    echo -e Balance before transfer\\t$BEFORE
    echo -e Balance after transfer\\t$AFTER
    ```
  </Step>

  <Step title="Create the TypeScript project">
    <Note>Messages are relayed automatically in the interop devnet.</Note>

    <Steps>
      <Step title="Create a new TypeScript project">
        ```sh theme={null}
        mkdir transfer-eth
        cd transfer-eth
        npm init -y
        npm install --save-dev -y viem tsx @types/node @eth-optimism/viem typescript
        mkdir src
        ```
      </Step>

      <Step title="Download the SuperchainETHBridge ABI">
        ```sh theme={null}
        curl https://raw.githubusercontent.com/ethereum-optimism/optimism/refs/heads/develop/packages/contracts-bedrock/snapshots/abi/SuperchainETHBridge.json > src/SuperchainETHBridge.abi.json
        ```
      </Step>

      <Step title="Create src/transfer-eth.mts">
        ```typescript theme={null}
            import {
                createWalletClient,
                http,
                publicActions,
                getContract,
                Address,
                formatEther,
                parseEther,
            } from 'viem'

            import { privateKeyToAccount } from 'viem/accounts'

            import {
                supersimL2A,
                supersimL2B,
                interopAlpha0,
                interopAlpha1
            } from '@eth-optimism/viem/chains'

            import {
                walletActionsL2,
                publicActionsL2,
                contracts as optimismContracts
            } from '@eth-optimism/viem'

            import superchainEthBridgeAbi from './SuperchainETHBridge.abi.json'

            const supersimAddress = '0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266'
            const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
            const sourceChain = account.address === supersimAddress ? supersimL2A : interopAlpha0
            const destinationChain = account.address === supersimAddress ? supersimL2B : interopAlpha1

            const sourceWallet = createWalletClient({
                chain: sourceChain,
                transport: http(),
                account,
            }).extend(publicActions)
                .extend(publicActionsL2())
                .extend(walletActionsL2())

            const destinationWallet = createWalletClient({
                chain: destinationChain,
                transport: http(),
                account,
            }).extend(publicActions)
                .extend(publicActionsL2())
                .extend(walletActionsL2())

            const ethBridgeOnSource = await getContract({
                address: optimismContracts.superchainETHBridge.address,
                abi: superchainEthBridgeAbi,
                client: sourceWallet,
            })

            const reportBalance = async (address: string): Promise<void> => {
                const sourceBalance = await sourceWallet.getBalance({ address })
                const destinationBalance = await destinationWallet.getBalance({ address })

                console.log(`
                    Address: ${address}
                    Balance on source chain: ${formatEther(sourceBalance)}
                    Balance on destination chain: ${formatEther(destinationBalance)}
                `)
            }

            console.log('Before transfer')
            await reportBalance(account.address)

            const sourceHash = await ethBridgeOnSource.write.sendETH({
                value: parseEther('0.001'),
                args: [account.address, destinationChain.id],
            })
            const sourceReceipt = await sourceWallet.waitForTransactionReceipt({
                hash: sourceHash,
            })

            console.log('After transfer on source chain')
            await reportBalance(account.address)

            const sentMessages = await sourceWallet.interop.getCrossDomainMessages({
                logs: sourceReceipt.logs,
            })
            const sentMessage = sentMessages[0]
            const relayMessageParams = await sourceWallet.interop.buildExecutingMessage({
                log: sentMessage.log,
            })

            const relayMsgTxnHash = await destinationWallet.interop.relayCrossDomainMessage(relayMessageParams)
            await destinationWallet.waitForTransactionReceipt({ hash: relayMsgTxnHash })

            console.log('After relaying message to destination chain')
            await reportBalance(account.address)
        ```
      </Step>
    </Steps>

    <Expandable title="Explanation of `transfer-eth.mts`">
      ```typescript theme={null}
          import { 
              supersimL2A, 
              supersimL2B, 
              interopAlpha0, 
              interopAlpha1 
          } from '@eth-optimism/viem/chains'
      ```

      Import all chain definitions from `@eth-optimism/viem`.

      ```typescript theme={null}
          const supersimAddress="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
          const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
          const sourceChain = account.address == supersimAddress ? supersimL2A : interopAlpha0
          const destinationChain = account.address == supersimAddress ? supersimL2B : interopAlpha1
      ```

      If the address we use is `0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266`, one of the prefunded addresses on `anvil`, assume we're using Supersim.
      Otherwise, use Interop devnet.

      ```typescript theme={null}
          const sourceHash = await ethBridgeOnSource.write.sendETH({
              value: parseEther('0.001'),
              args: [account.address, destinationChain.id]
          })
          const sourceReceipt = await sourceWallet.waitForTransactionReceipt({
              hash: sourceHash
          })
      ```

      To relay a message we need the information in the receipt.
      Also, we need to wait until the transaction with the relayed message is actually part of a block.

      ```typescript theme={null}
          const sentMessages = await sourceWallet.interop.getCrossDomainMessages({
              logs: sourceReceipt.logs,
          })
          const sentMessage = sentMessages[0]
      ```

      A single transaction can send multiple messages.
      But here we know we sent just one, so we look for the first one in the list.

      ```typescript theme={null}
          const relayMessageParams = await sourceWallet.interop.buildExecutingMessage({
              log: sentMessage.log,
          })

          const relayMsgTxnHash = await destinationWallet.interop.relayCrossDomainMessage(relayMessageParams)
      ```

      This is how you use `@eth-optimism/viem` to create an executing message.
    </Expandable>
  </Step>

  <Step title="Run the example">
    1. Run the example.

       ```sh theme={null}
       npx tsx src/transfer-eth.mts
       ```

    2. Read the results.

       ```
       Before transfer

               Address: 0x7ED53BfaA58B79Dd655B2f229258C093b6C09A8C
               Balance on source chain: 0.020999799151902245
               Balance on destination chain: 0.026999459226731331
       ```

       The initial state. Note that the address depends on your private key; it should be different from mine.

       ```
       After transfer on source chain

               Address: 0x7ED53BfaA58B79Dd655B2f229258C093b6C09A8C
               Balance on source chain: 0.019999732176717961
               Balance on destination chain: 0.026999459226731331
       ```

       After the initiating message the balance on the source chain is immediately reduced.
       Notice that even though we are sending 0.001 ETH, the balance on the source chain is reduced by a bit more (here, approximately 67 gwei).
       This is the cost of the initiating transaction on the source chain.
       Of course, as there has been no transaction on the destination chain, that balance is unchanged.

       ```
       After relaying message to destination chain

               Address: 0x7ED53BfaA58B79Dd655B2f229258C093b6C09A8C
               Balance on source chain: 0.019999732176717961
               Balance on destination chain: 0.027999278943880868    
       ```

       Now the balance on the destination chain increases, by slightly less than 0.001 ETH.
       The executing message also has a transaction cost (in this case, about 180gwei).
  </Step>
</Steps>

## Next steps

* Check out the [SuperchainETHBridge guide](/op-stack/interop/superchain-eth-bridge) for more information.
* Review the [OP Stack interop explainer](/op-stack/interop/explainer) for answers to common questions about interoperability.


# Bridging ERC-20 tokens to OP Mainnet
Source: https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-bridge-erc20

Learn how to use @eth-optimism/viem and viem packages to transfer ERC-20 tokens between Layer 1 (Ethereum or Sepolia) and Layer 2 (OP Mainnet or OP Sepolia).

This tutorial explains how you can use [@eth-optimism/viem](https://www.npmjs.com/package/@eth-optimism/viem) and [viem](https://viem.sh/op-stack) to bridge ERC-20 tokens between L1 (Ethereum or Sepolia) and L2 (OP Mainnet or OP Sepolia).
The `@eth-optimism/viem` and `viem` packages are an easy way to add bridging functionality to your javascript-based application.
They also provide some safety rails to prevent common mistakes that could cause tokens to be made inaccessible.

Behind the scenes, `@eth-optimism/viem` package uses the [Standard Bridge](/app-developers/guides/bridging/standard-bridge) contracts to transfer tokens.
Make sure to check out the [Standard Bridge guide](/app-developers/guides/bridging/standard-bridge) if you want to learn more about how the bridge works under the hood.

<Info>
  The Standard Bridge **does not** support [**fee on transfer tokens**](https://github.com/d-xo/weird-erc20#fee-on-transfer) or [**rebasing tokens**](https://github.com/d-xo/weird-erc20#balance-modifications-outside-of-transfers-rebasingairdrops) because they can cause bridge accounting errors.
</Info>

## Supported networks

Viem supports any of the [OP Stack networks](https://viem.sh/op-stack/chains).
If you want to use a network that isn't included by default, you can add it to Viem's chain [configurations](https://viem.sh/op-stack/chains#configuration).

## Dependencies

* [node](https://nodejs.org/en/)
* [pnpm](https://pnpm.io/installation)

## Create a demo project

You're going to use the  library for this tutorial.
Since  is a [Node.js](https://nodejs.org/en/) library, you'll need to create a Node.js project to use it.

<Steps>
  <Step title="Make a project folder">
    ```bash theme={null}
    mkdir bridging-erc20-tokens
    cd bridging-erc20-tokens
    ```
  </Step>

  <Step title="Initialize the project">
    ```bash theme={null}
    pnpm init
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm add @eth-optimism/viem viem
    ```
  </Step>
</Steps>

## Get ETH on Sepolia and OP Sepolia

This tutorial explains how to bridge tokens from Sepolia to OP Sepolia.
You will need to get some ETH on both of these testnets.

<TutorialFaucets />

## Add a private key to your environment

You need a private key in order to sign transactions.
Set your private key as an environment variable with the `export` command.
Make sure this private key corresponds to an address that has ETH on .

<Info>
  Want to create a new wallet for this tutorial?
  If you have [`cast`](https://book.getfoundry.sh/getting-started/installation) installed you can run `cast wallet new` in your terminal to create a new wallet and get the private key.
</Info>

```bash theme={null}
export TUTORIAL_PRIVATE_KEY=0x...
```

## Start the Node REPL

You're going to use the Node REPL to interact with .
To start the Node REPL, run the following command in your terminal:

```bash theme={null}
node
```

This will bring up a Node REPL prompt that allows you to run JavaScript code.

## Import dependencies

You need to import some dependencies into your Node REPL session.
The `@eth-optimism/viem` package uses ESM modules, and to use in the Node.js REPL, you need to use dynamic imports with await.
Here's how to do it:

<Steps>
  <Step title="Import the @eth-optimism/viem package">
    ```js theme={null}

    const viem = await import('viem');
    const { createPublicClient, createWalletClient, http, formatEther, parseEther} = viem;
    const accounts = await import('viem/accounts');
    const { privateKeyToAccount } = accounts;
    const viemChains = await import('viem/chains');
    const { optimismSepolia, sepolia } = viemChains;
    const opActions = await import('@eth-optimism/viem/actions');
    const { depositERC20, withdrawOptimismERC20 } = opActions;
    ```
  </Step>
</Steps>

## Set session variables

You'll need a few variables throughout this tutorial.
Let's set those up now.

<Steps>
  <Step title="Load your private key">
    This step retrieves your private key from the environment variable you set earlier and converts it into an account object that Viem can use for transaction signing.

    The private key is essential for authorizing transactions on both L1 and L2 networks.
    For security reasons, we access it from an environment variable rather than hardcoding it.

    ```js theme={null}
    const PRIVATE_KEY = process.env.TUTORIAL_PRIVATE_KEY;
    const account = privateKeyToAccount(PRIVATE_KEY);
    ```
  </Step>

  <Step title="Create the RPC providers and wallets">
    Here we establish the connections to both networks by creating four different clients:

    1. L1 Public Client: For reading data from the Sepolia network
    2. L1 Wallet Client: For signing and sending transactions on Sepolia
    3. L2 Public Client: For reading data from OP Sepolia
    4. L2 Wallet Client: For signing and sending transactions on OP Sepolia

    Each client is configured with the appropriate chain information and RPC endpoint.
    This dual-network setup allows us to seamlessly interact with both layers using the same account.
    Replace `<YOUR_API_KEY>` with your API key from a RPC provider.

    ```js theme={null}
    const L1_RPC_URL = 'https://ethereum-sepolia-rpc.publicnode.com';
    const L2_RPC_URL = 'https://sepolia.optimism.io';

    const publicClientL1 = createPublicClient({
      chain: sepolia,
      transport: http(L1_RPC_URL),
    });

    const walletClientL1 = createWalletClient({
      account,
      chain: sepolia,
      transport: http(L1_RPC_URL),
    });

    const publicClientL2 = createPublicClient({
      chain: optimismSepolia,
      transport: http(L2_RPC_URL),
    });

    const walletClientL2 = createWalletClient({
      account,
      chain: optimismSepolia,
      transport: http(L2_RPC_URL),
    });
    ```
  </Step>

  <Step title="Set the L1 and L2 ERC-20 addresses">
    We define the addresses of the ERC-20 tokens on both networks.
    These are specially deployed test tokens with corresponding implementations on both L1 (Sepolia) and L2 (OP Sepolia).

    The L2 token is configured to recognize deposits from its L1 counterpart.
    We also define a constant `oneToken` representing the full unit (10^18 wei) to simplify our deposit and withdrawal operations.

    ```js theme={null}
    const l1Token = "0x5589BB8228C07c4e15558875fAf2B859f678d129";
    const l2Token = "0xD08a2917653d4E460893203471f0000826fb4034";
    ```

    <Info>
      If you're coming from the [Create an L2 token for the Standard
      Bridge](./standard-bridge-standard-token) tutorial, you can use the addresses
      of your own ERC-20 tokens here instead.
    </Info>
  </Step>
</Steps>

## Get L1 tokens

You're going to need some tokens on L1 that you can bridge to L2.
The L1 testing token located at [`0x5589BB8228C07c4e15558875fAf2B859f678d129`](https://sepolia.etherscan.io/address/0x5589BB8228C07c4e15558875fAf2B859f678d129) has a `faucet` function that makes it easy to get tokens.

<Steps>
  <Step title="Set the ERC20 ABI">
    The Application Binary Interface (ABI) defines how to interact with the smart contract functions. This ERC-20 ABI includes several critical functions:

    * `balanceOf`: Allows us to check token balances for any address
    * `faucet`: A special function in this test token that mints new tokens to the caller
    * `approve`: Required to grant the bridge permission to transfer tokens on our behalf
    * `allowance`: To check how many tokens we've approved for the bridge
    * `decimals` and `symbol`: Provide token metadata

    This comprehensive ABI gives us everything we need to manage our tokens across both L1 and L2.

    ```js theme={null}
    const erc20ABI = [
      {
        inputs: [
          {
            internalType: "address",
            name: "account",
            type: "address",
          },
        ],
        name: "balanceOf",
        outputs: [
          {
            internalType: "uint256",
            name: "",
            type: "uint256",
          },
        ],
        stateMutability: "view",
        type: "function",
      },
      {
        inputs: [],
        name: "faucet",
        outputs: [],
        stateMutability: "nonpayable",
        type: "function",
      },
      {
        inputs: [
          {
            internalType: "address",
            name: "spender",
            type: "address"
          },
          {
            internalType: "uint256",
            name: "value",
            type: "uint256"
          }
        ],
        name: "approve",
        outputs: [
          {
            internalType: "bool",
            name: "",
            type: "bool"
          }
        ],
        stateMutability: "nonpayable",
        type: "function"
      },
    ];
    ```
  </Step>

  <Step title="Request some tokens">
    Now we'll call the `faucet` function on the L1 test token contract to receive free tokens for testing.
    This transaction will mint new tokens directly to our wallet address.

    The function doesn't require any parameters - it simply credits a predetermined amount to whoever calls it.
    We store the transaction hash for later reference and wait for the transaction to be confirmed.

    ```js theme={null}
    console.log('Getting tokens from faucet...');
    const tx = await walletClientL1.writeContract({
      address: l1Token,
      abi: erc20ABI,
      functionName: 'faucet',
      account,
    });
    console.log('Faucet transaction:', tx);
    ```
  </Step>

  <Step title="Check your token balance">
    After using the faucet, we verify our token balance by calling the `balanceOf` function on the L1 token contract.

    This step confirms that we've successfully received tokens before proceeding with the bridging process.
    The balance is returned in the smallest unit (wei), but we format it into a more readable form using the `formatEther` utility function from `viem`, since this token uses 18 decimal places.

    ```js theme={null}
    const l1Balance = await publicClientL1.readContract({
      address: l1Token,
      abi: erc20ABI,
      functionName: 'balanceOf',
      args: [account.address]
    });
    console.log(`L1 Balance after receiving faucet: ${formatEther(l1Balance)}`);
    ```
  </Step>
</Steps>

## Deposit tokens

Now that you have some tokens on L1, you can deposit those tokens into the `L1StandardBridge` contract.
You'll then receive the same number of tokens on L2 in return.

<Steps>
  <Step title="Define the amount to deposit">
    We define a variable `oneToken` that represents 1 full token in its base units (wei).
    ERC-20 tokens typically use 18 decimal places, so 1 token equals 10^18 wei.

    This constant helps us work with precise token amounts in our transactions, avoiding rounding errors and ensuring exact value transfers.
    We'll use this value for both deposits and withdrawals

    ```js theme={null}
    const oneToken = parseEther('1')
    ```
  </Step>

  <Step title="Allow the Standard Bridge to access your tokens">
    ERC-20 tokens require a two-step process for transferring tokens on behalf of a user.
    First, we must grant permission to the bridge contract to spend our tokens by calling the `approve` function on the token contract.

    We specify the bridge address from the chain configuration and the exact amount we want to bridge.
    This approval transaction must be confirmed before the bridge can move our tokens.

    ```js theme={null}
    const bridgeAddress = optimismSepolia.contracts.l1StandardBridge[sepolia.id].address;
    const approveTx = await walletClientL1.writeContract({
      address: l1Token,
      abi: erc20ABI,
      functionName: 'approve',
      args: [bridgeAddress, oneToken],
    });
    console.log('Approval transaction:', approveTx);
    ```
  </Step>

  <Step title="Wait for approval">
    After submitting the approval transaction, we need to wait for it to be confirmed on L1.
    We use the `waitForTransactionReceipt` function to monitor the transaction until it's included in a block.

    The receipt provides confirmation details, including which block includes our transaction.
    This step ensures our approval is finalized before attempting to bridge tokens.

    ```js theme={null}
    await publicClientL1.waitForTransactionReceipt({ hash: approveTx });
    ```
  </Step>

  <Step title="Deposit your tokens">
    Now we can execute the actual bridging operation using the `depositERC20` function from the `@eth-optimism/viem` package.

    This function handles all the complex interactions with the `L1StandardBridge` contract for us.
    We provide:

    * The addresses of both the L1 and L2 tokens
    * The amount to bridge
    * The target chain (OP Sepolia)
    * Our wallet address as the recipient on L2
    * A minimum gas limit for the L2 transaction

    This streamlined process ensures our tokens are safely transferred to L2.

    ```js theme={null}
    console.log('Depositing tokens to L2...');
    const depositTx = await depositERC20(walletClientL1, {
      tokenAddress: l1Token,
      remoteTokenAddress: l2Token,
      amount: oneToken,
      targetChain: optimismSepolia,
      to: account.address,
      minGasLimit: 200000,
    });
    console.log(`Deposit transaction hash: ${depositTx}`);
    ```

    <Info>
      Using a smart contract wallet? As a safety measure, `depositERC20` will fail
      if you try to deposit ETH from a smart contract wallet without specifying a
      `recipient`. Add the `recipient` option to the `depositERC20` call to fix
      this. Check out the [@eth-optimism/viem
      docs](https://github.com/ethereum-optimism/ecosystem/tree/main/packages/viem) for
      more info on the options you can pass to `depositERC20`.
    </Info>
  </Step>

  <Step title="Wait for the deposit to be relayed">
    After initiating the deposit, we need to wait for the L1 transaction to be confirmed.
    This function tracks the transaction until it's included in an L1 block.

    Note that while this confirms the deposit was accepted on L1, there will still be a short delay (typically a few minutes) before the tokens appear on L2, as the transaction needs to be processed by the Optimism sequencer.

    ```js theme={null}
    const depositReceipt = await publicClientL1.waitForTransactionReceipt({ hash: depositTx });
    console.log(`Deposit confirmed in block ${depositReceipt.blockNumber}`);
    ```
  </Step>

  <Step title="Check your token balance on L1">
    After the deposit transaction is confirmed, we check our token balance on L1 again to verify that the tokens have been deducted.

    This balance should be lower by the amount we bridged, as those tokens are now escrowed in the `L1StandardBridge` contract.
    This step helps confirm that the first part of the bridging process completed successfully:

    ```js theme={null}
    const l1BalanceAfterDeposit = await publicClientL1.readContract({
      address: l1Token,
      abi: erc20ABI,
      functionName: 'balanceOf',
      args: [account.address]
    });
    console.log(`L1 Balance after deposit: ${formatEther(l1BalanceAfterDeposit)}`);
    ```
  </Step>

  <Step title="Check your token balance on L2">
    After allowing some time for the L2 transaction to be processed, we check our token balance on L2 to verify that we've received the bridged tokens.

    The newly minted L2 tokens should appear in our wallet at the same address we used on L1.
    This step confirms the complete success of the bridge operation from L1 to L2.

    ```js theme={null}
    const l2Balance = await publicClientL2.readContract({
      address: l2Token,
      abi: erc20ABI,
      functionName: 'balanceOf',
      args: [account.address]
    });
    console.log(`L2 Balance after withdrawal: ${formatEther(l2Balance)}`);
    ```
  </Step>
</Steps>

## Withdraw tokens

You just bridged some tokens from L1 to L2.
Nice!
Now you're going to repeat the process in reverse to bridge some tokens from L2 to L1.

<Steps>
  <Step title="Initiate the withdrawal">
    To move tokens back to L1, we use the `withdrawOptimismERC20` function from the `@eth-optimism/viem` package.
    This function interacts with the `L2StandardBridge` contract to initialize the withdrawal process.
    We specify:

    * The L2 token address
    * The amount to withdraw (we're using half of a token in this tutorial)
    * Our address as the recipient on L1
    * A minimum gas limit for the transaction

    Unlike deposits, withdrawals from L2 to L1 are not immediate and require a multi-step process including a 7-day challenge period for security reasons.

    ```js theme={null}
    console.log('Withdrawing tokens back to L1...');
    const withdrawTx = await withdrawOptimismERC20(walletClientL2, {
      tokenAddress: l2Token,
      amount: oneToken / 2n, 
      to: account.address,
      minGasLimit: 200000,
    });
    console.log(`Withdrawal transaction hash: ${withdrawTx}`);
    ```
  </Step>

  <Step title="Wait for the transaction receipt">
    Similar to deposits, we wait for the withdrawal transaction to be confirmed on L2.
    This receipt provides confirmation that the withdrawal has been initiated.

    The transaction logs contain critical information that will be used later in the withdrawal verification process.
    This is only the first step in the withdrawal - the tokens are now locked on L2, but not yet available on L1.

    ```js theme={null}
    const withdrawReceipt = await publicClientL2.waitForTransactionReceipt({ hash: withdrawTx });
    console.log(`Withdrawal initiated in L2 block ${withdrawReceipt.blockNumber}`);
    ```

    <Info>
      This step can take a few minutes. Feel free to take a quick break while you
      wait.
    </Info>
  </Step>

  <Step title="Check your token balance on L2">
    After the withdrawal transaction is confirmed, we check our token balance on L2 again to verify that the tokens have been deducted.
    Our L2 balance should now be lower by the amount we initiated for withdrawal.

    At this point, the withdrawal process has begun, but the tokens are not yet available on L1 - please refer to [Withdraw ETH](./cross-dom-bridge-eth#withdraw-eth) to continue with the “prove” and “finalize” withdrawal steps.

    ```js theme={null}
    const l2Balance = await publicClientL2.readContract({
      address: l2Token,
      abi: erc20ABI,
      functionName: 'balanceOf',
      args: [account.address]
    });
    console.log(`L2 Balance after withdrawal initiation: ${formatEther(l2Balance)}`);
    ```
  </Step>
</Steps>

## Next steps

Congrats!
You've just deposited and withdrawn tokens using `@eth-optimism/viem` package.
You should now be able to write applications that use the `@eth-optimism/viem` package to transfer ERC-20 tokens between L1 and L2.
Although this tutorial used Sepolia and OP Sepolia, the same process works for Ethereum and OP Mainnet.


# Submitting Transactions from L1
Source: https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-bridge-eth

Learn how to process deposit transactions and withdrawals with Viem.

<Info>
  **Learn the OP Stack — stop 10 of 13.**
  You've read how deposits and withdrawals work. In this project you walk
  both directions end to end from code, using Viem. When you're done,
  continue to
  [Fault proofs explainer](/op-stack/fault-proofs/explainer).
</Info>

This tutorial explains how to use [Viem](https://viem.sh/op-stack) to process cross-domain transactions:

* [Deposited transactions](https://specs.optimism.io/protocol/deposits.html): Also known as deposits, these are transactions initiated on L1 and executed on L2. They can be used to submit arbitrary L2 transactions from L1.

* [Withdrawals](https://specs.optimism.io/protocol/withdrawals.html): These are cross-domain transactions initiated on L2 and finalized by a transaction executed on L1. They can be used to send arbitrary messages on L1 from L2 via the `OptimismPortal`.

Both deposit transactions and withdrawals can transfer ETH and data.

## Supported networks

Viem supports any of the [OP Stack networks](https://viem.sh/op-stack/chains).
The OP Stack networks are included in Viem by default.
If you want to use a network that isn't included by default, you can add it to Viem's chain [configurations](https://viem.sh/op-stack/chains#configuration).

## Dependencies

* [node](https://nodejs.org/en/)
* [pnpm](https://pnpm.io/installation)

## Create a demo project

You're going to use the  library for this tutorial.
Since  is a [Node.js](https://nodejs.org/en/) library, you'll need to create a Node.js project to use it.

<Steps>
  <Step title="Make a project folder">
    ```bash theme={null}
    mkdir bridge-eth
    cd bridge-eth
    ```
  </Step>

  <Step title="Initialize the project">
    ```bash theme={null}
    pnpm init
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm add viem@^2.51.0
    ```
  </Step>
</Steps>

## Get ETH on Sepolia

This tutorial explains how to bridge ETH from Sepolia to OP Sepolia.
You will need to get some ETH on Sepolia to follow along.

<TutorialFaucets />

## Add a private key to your environment

You need a private key in order to sign transactions.
Set your private key as an environment variable with the `export` command.
Make sure this private key corresponds to an address that has ETH on .

<Info>
  Want to create a new wallet for this tutorial?
  If you have [`cast`](https://book.getfoundry.sh/getting-started/installation) installed you can run `cast wallet new` in your terminal to create a new wallet and get the private key.
</Info>

```bash theme={null}
export TUTORIAL_PRIVATE_KEY=0x...
```

## Start the Node REPL

You're going to use the Node REPL to interact with .
To start the Node REPL, run the following command in your terminal:

```bash theme={null}
node
```

This will bring up a Node REPL prompt that allows you to run JavaScript code.

## Import dependencies

You need to import some dependencies into your Node REPL session.

<Steps>
  <Step title="Import Viem and other packages">
    ```js theme={null}
    const { createPublicClient, http, createWalletClient, parseEther, formatEther } = require('viem');
    const { sepolia, optimismSepolia } = require('viem/chains');
    const { privateKeyToAccount } = require('viem/accounts');
    const { getL2TransactionHashes, publicActionsL1, publicActionsL2, walletActionsL1, walletActionsL2, isSuperGameType } = require('viem/op-stack');
    ```
  </Step>

  <Step title="Load private key and set account">
    ```js theme={null}
    const PRIVATE_KEY = process.env.TUTORIAL_PRIVATE_KEY;
    const account = privateKeyToAccount(PRIVATE_KEY);
    ```
  </Step>

  <Step title="Create L1 public client for reading from the Sepolia network">
    ```js theme={null}
    const publicClientL1 = createPublicClient({
        chain: sepolia,
        transport: http("https://ethereum-sepolia-rpc.publicnode.com"),
    }).extend(publicActionsL1()) 
    ```
  </Step>

  <Step title="Create L1 wallet client for sending transactions on Sepolia">
    ```js theme={null}
    const walletClientL1 = createWalletClient({
        account,
        chain: sepolia,
        transport: http("https://ethereum-sepolia-rpc.publicnode.com"),
    }).extend(walletActionsL1());
    ```
  </Step>

  <Step title="Create L2 public client for interacting with OP Sepolia">
    ```js theme={null}
    const publicClientL2 = createPublicClient({
        chain: optimismSepolia,
        transport: http("https://sepolia.optimism.io"),
    }).extend(publicActionsL2());
    ```
  </Step>

  <Step title="Create L2 wallet client on OP Sepolia">
    ```js theme={null}
    const walletClientL2 = createWalletClient({
        account,
        chain: optimismSepolia,
        transport: http("https://sepolia.optimism.io"),
    }).extend(walletActionsL2());
    ```
  </Step>
</Steps>

## Get ETH on Sepolia

You're going to need some ETH on L1 that you can bridge to L2.
You can get some Sepolia ETH from [this faucet](https://sepoliafaucet.com).

## Deposit ETH

Now that you have some ETH on L1, in addition to using the method described in [Bridging ETH](/app-developers/guides/bridging/standard-bridge#bridging-eth), you can also deposit ETH using the approach shown in the example below.

If you are using a contract account, you should pay attention to [Address Aliasing](https://specs.optimism.io/protocol/deposits.html#address-aliasing).

<Tabs>
  <Tab title="depositETH">
    <Steps>
      <Step title="Check your wallet balance on L1">
        See how much ETH you have on L1 so you can confirm that the deposit worked later on.

        ```js theme={null}
        const l1Balance = await publicClientL1.getBalance({ address: account.address });
        console.log(`L1 Balance: ${formatEther(l1Balance)} ETH`); 
        ```

        <Info>
          We used `formatEther` method from `viem` to format the balance to ether.
        </Info>
      </Step>

      <Step title="Create the deposit transaction">
        Use [buildDepositTransaction](https://viem.sh/op-stack/actions/buildDepositTransaction) to build the deposit transaction parameters on L2.

        Be sure to understand the meanings of the optional parameters `mint` and `value`. You can also use someone else’s address as the `to` value if desired.

        ```js theme={null}
        const depositArgs = await publicClientL2.buildDepositTransaction({
        mint: parseEther("0.01"),
        to: account.address,
        });
        ```
      </Step>

      <Step title="Send the deposit transaction">
        Send the deposit transaction on L1 and log the L1 transaction hash.

        ```js theme={null}
        const depositHash = await walletClientL1.depositTransaction(depositArgs);
        console.log(`Deposit transaction hash on L1: ${depositHash}`);
        ```
      </Step>

      <Step title="Wait for L1 transaction">
        Wait for the L1 transaction to be processed and log the receipt.

        ```js theme={null}
        const depositReceipt = await publicClientL1.waitForTransactionReceipt({ hash: depositHash });
        console.log('L1 transaction confirmed:', depositReceipt);
        ```
      </Step>

      <Step title="Extract the L2 transaction hash">
        Extracts the corresponding L2 transaction hash from the L1 receipt, and logs it.
        This hash represents the deposit transaction on L2.

        ```js theme={null}
        const [l2Hash] = getL2TransactionHashes(depositReceipt);
        console.log(`Corresponding L2 transaction hash: ${l2Hash}`);
        ```
      </Step>

      <Step title="Wait for the L2 transaction to be processed">
        Wait for the L2 transaction to be processed and confirmed and logs the L2 receipt to verify completion.

        ```js theme={null}
        const l2Receipt = await publicClientL2.waitForTransactionReceipt({
        hash: l2Hash,
        }); 
        console.log('L2 transaction confirmed:', l2Receipt);
        console.log('Deposit completed successfully!');
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Full Code">
    ```js theme={null}
    const { createPublicClient, http, createWalletClient, parseEther, formatEther } = require('viem');
    const { sepolia, optimismSepolia } = require('viem/chains');
    const { privateKeyToAccount } = require('viem/accounts');
    const { getL2TransactionHashes, publicActionsL1, publicActionsL2, walletActionsL1, walletActionsL2, isSuperGameType } = require('viem/op-stack');

    const PRIVATE_KEY = process.env.TUTORIAL_PRIVATE_KEY;
    const account = privateKeyToAccount(PRIVATE_KEY);

    const publicClientL1 = createPublicClient({
    chain: sepolia,
    transport: http("https://ethereum-sepolia-rpc.publicnode.com"),
    }).extend(publicActionsL1()) 

    const walletClientL1 = createWalletClient({
    account,
    chain: sepolia,
    transport: http("https://ethereum-sepolia-rpc.publicnode.com"),
    }).extend(walletActionsL1());

    const publicClientL2 = createPublicClient({
    chain: optimismSepolia,
    transport: http("https://sepolia.optimism.io"),
    }).extend(publicActionsL2());

    const walletClientL2 = createWalletClient({
    account,
    chain: optimismSepolia,
    transport: http("https://sepolia.optimism.io"),
    }).extend(walletActionsL2());

    const l1Balance = await publicClientL1.getBalance({ address: account.address });
    console.log(`L1 Balance: ${formatEther(l1Balance)} ETH`); 

    async function depositETH() {

    const depositArgs = await publicClientL2.buildDepositTransaction({
    mint: parseEther("0.01"),
    to: account.address,
    });

    const depositHash = await walletClientL1.depositTransaction(depositArgs);
    console.log(`Deposit transaction hash on L1: ${depositHash}`);

    const depositReceipt = await publicClientL1.waitForTransactionReceipt({ hash: depositHash });
    console.log('L1 transaction confirmed:', depositReceipt);

    const [l2Hash] = getL2TransactionHashes(depositReceipt);
    console.log(`Corresponding L2 transaction hash: ${l2Hash}`);

    const l2Receipt = await publicClientL2.waitForTransactionReceipt({
    hash: l2Hash,
    }); 
    console.log('L2 transaction confirmed:', l2Receipt);
    console.log('Deposit completed successfully!');
    } 
    ```
  </Tab>
</Tabs>

## Withdraw ETH

You just bridged some ETH from L1 to L2.
Nice!
Now you’re going to repeat the process in reverse to bridge some ETH from L2 to L1.

In addition to the method described in [Bridging ETH](/app-developers/guides/bridging/standard-bridge#bridging-eth), you can also withdraw ETH using the example approach shown below.

<Tabs>
  <Tab title="withdrawETH">
    <Steps>
      <Step title="Create the withdrawal transaction">
        Uses `buildInitiateWithdrawal` to create the withdrawal parameters.
        Converts the withdrawal amount to `wei` and specifies the recipient on L1.

        ```js theme={null}
        //Add the same imports used in DepositETH function
        const withdrawalArgs = await publicClientL1.buildInitiateWithdrawal({
        value: parseEther('0.005'),
        to: account.address,
        });
        ```
      </Step>

      <Step title="Executing the withdrawal">
        This sends the withdrawal transaction on L2, which initiates the withdrawal process on L2 and logs a transaction hash for tracking the withdrawal.

        ```js theme={null}
        const withdrawalHash = await walletClientL2.initiateWithdrawal(withdrawalArgs);
        console.log(`Withdrawal transaction hash on L2: ${withdrawalHash}`);
        ```
      </Step>

      <Step title="Confirming L2 transaction">
        Wait one hour (max) for the L2 Output containing the transaction to be proposed, and log the receipt, which contains important details like the block number etc.

        ```js theme={null}
        const withdrawalReceipt = await publicClientL2.waitForTransactionReceipt({ hash: withdrawalHash });
        const withdrawalBlock = await publicClientL2.getBlock({
        blockNumber: withdrawalReceipt.blockNumber
        });
        const respectedGameType = await publicClientL1.readContract({
        abi: [{
        inputs: [],
        name: 'respectedGameType',
        outputs: [{ type: 'uint32' }],
        stateMutability: 'view',
        type: 'function'
        }],
        address: publicClientL2.chain.contracts.portal[publicClientL1.chain.id].address,
        functionName: 'respectedGameType'
        });
        const proveContext = isSuperGameType(Number(respectedGameType))
        ? { l2Timestamp: withdrawalBlock.timestamp }
        : {};
        console.log('L2 transaction confirmed:', withdrawalReceipt);
        ```
      </Step>

      <Step title="Wait for withdrawal prove">
        Next, is to prove to the bridge on L1 that the withdrawal happened on L2. To achieve that, you first need to wait until the withdrawal is ready to prove.

        ```js theme={null}
        const { game, withdrawal } = await publicClientL1.waitToProve({
        ...proveContext,
        receipt: withdrawalReceipt,
        targetChain: walletClientL2.chain
        });
        ```

        Build parameters to prove the withdrawal on the L2.

        ```js theme={null}
        const proveArgs = await publicClientL2.buildProveWithdrawal({
        game,
        withdrawal,
        });
        ```
      </Step>

      <Step title="Prove the withdrawal on the L1">
        Once the withdrawal is ready to be proven, you'll send an L1 transaction to prove that the withdrawal happened on L2.

        ```js theme={null}
        const proveHash = await walletClientL1.proveWithdrawal(proveArgs);

        const proveReceipt = await publicClientL1.waitForTransactionReceipt({ hash: proveHash });
        ```
      </Step>

      <Step title="Wait for withdrawal finalization">
        Before a withdrawal transaction can be finalized, you will need to wait for the finalization period.
        This can only happen after the fault proof period has elapsed. On OP Mainnet, this takes 7 days.

        ```js theme={null}
        const awaitWithdrawal = await publicClientL1.waitToFinalize({
        targetChain: walletClientL2.chain,
        withdrawalHash: withdrawal.withdrawalHash,
        });
        ```

        <Info>
          We're currently testing fault proofs on OP Sepolia, so withdrawal times
          reflect Mainnet times.
        </Info>
      </Step>

      <Step title="Finalize the withdrawal">
        ```js theme={null}
        const finalizeHash = await walletClientL1.finalizeWithdrawal({
        targetChain: walletClientL2.chain,
        withdrawal,
        });
        ```
      </Step>

      <Step title="Wait until the withdrawal is finalized">
        ```js theme={null}
        const finalizeReceipt = await publicClientL1.waitForTransactionReceipt({
        hash: finalizeHash
        });
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Full Code">
    ```js theme={null}
    //Add the same imports used in DepositETH function
    const withdrawalArgs = await publicClientL1.buildInitiateWithdrawal({
    value: parseEther('0.005'),
    to: account.address,
    });

    const withdrawalHash = await walletClientL2.initiateWithdrawal(withdrawalArgs);
    console.log(`Withdrawal transaction hash on L2: ${withdrawalHash}`);

    const withdrawalReceipt = await publicClientL2.waitForTransactionReceipt({ hash: withdrawalHash });
    const withdrawalBlock = await publicClientL2.getBlock({
    blockNumber: withdrawalReceipt.blockNumber
    });
    const respectedGameType = await publicClientL1.readContract({
    abi: [{
    inputs: [],
    name: 'respectedGameType',
    outputs: [{ type: 'uint32' }],
    stateMutability: 'view',
    type: 'function'
    }],
    address: publicClientL2.chain.contracts.portal[publicClientL1.chain.id].address,
    functionName: 'respectedGameType'
    });
    const proveContext = isSuperGameType(Number(respectedGameType))
    ? { l2Timestamp: withdrawalBlock.timestamp }
    : {};
    console.log('L2 transaction confirmed:', withdrawalReceipt);

    const { game, withdrawal } = await publicClientL1.waitToProve({
    ...proveContext,
    receipt: withdrawalReceipt,
    targetChain: walletClientL2.chain
    });

    const proveArgs = await publicClientL2.buildProveWithdrawal({
    game,
    withdrawal,
    });

    const proveHash = await walletClientL1.proveWithdrawal(proveArgs);

    const proveReceipt = await publicClientL1.waitForTransactionReceipt({ hash: proveHash });

    const awaitWithdrawal = await publicClientL1.waitToFinalize({
    targetChain: walletClientL2.chain,
    withdrawalHash: withdrawal.withdrawalHash,
    });

    const finalizeHash = await walletClientL1.finalizeWithdrawal({
    targetChain: walletClientL2.chain,
    withdrawal,
    });

    const finalizeReceipt = await publicClientL1.waitForTransactionReceipt({
    hash: finalizeHash
    });

    ```
  </Tab>
</Tabs>

<Info>
  Recommend checking with [getWithdrawalStatus](https://viem.sh/op-stack/actions/getWithdrawalStatus) before the `waitToProve` and `waitToFinalize` actions.

  ```js theme={null}
  const status = await publicClientL1.getWithdrawalStatus({
  ...proveContext,
  receipt: withdrawalReceipt,
  targetChain: walletClientL2.chain
  })
  console.log(`Withdrawal status: ${status}`)
  ```
</Info>

## Submitting Arbitrary L2 Transactions from L1

EOAs can submit any transaction on L1 that needs to be executed on L2. This also makes it possible for users to interact with contracts on L2 even when the [Sequencer is down](/op-stack/transactions/forced-transaction).

If the caller is a contract on L1, you need to pay attention to [Address Aliasing](https://specs.optimism.io/protocol/deposits.html#address-aliasing).

If you have just completed the [Bridging ERC-20 tokens to OP Mainnet](/app-developers/tutorials/bridging/cross-dom-bridge-erc20) tutorial, you can try initiating an ERC-20 transfer transaction on L1 that will be executed on L2.

`encodeFunctionData` and `erc20Abi` can be imported from Viem.

```js theme={null}
const oneToken = parseEther('1')
// L2 faucet token contract
const to = "0xD08a2917653d4E460893203471f0000826fb4034"

const data = encodeFunctionData({
  abi: erc20Abi,
  functionName: "transfer",
  args: [
    "0x000000000000000000000000000000000000dEaD", // recipient
    oneToken / 2n, 
  ],
});

const args = await publicClientL2.buildDepositTransaction({
  account,
  data,
  to,
});
```

## Use `OptimismPortal` to Send Arbitrary Messages on L1 from L2

The `L2ToL1MessagePasser` contract’s `initiateWithdrawal` function accepts a `_target` address and `_data` bytes. These are passed to a CALL opcode on L1 when `finalizeWithdrawalTransaction` is executed after the challenge period.

This means that, by design, the `OptimismPortal` contract can be used to send arbitrary transactions on L1, with the `OptimismPortal` acting as the `msg.sender`.

## Important Considerations

<Info>
  * The purpose of this tutorial is to introduce deposited transactions and withdrawals. You should first consider whether the [standard bridge](/app-developers/guides/bridging/standard-bridge) and the [messenger](/app-developers/guides/bridging/messaging) meet your use case requirements.
  * When working with deposited transactions, consider the implications of [Address Aliasing](https://specs.optimism.io/protocol/deposits.html#address-aliasing).
  * When working with withdrawals, consider that [OptimismPortal can send arbitrary messages on L1](https://specs.optimism.io/protocol/withdrawals.html#optimismportal-can-send-arbitrary-messages-on-l1).
  * Challenge period: The 7-day withdrawal challenge period is crucial for security.
  * Gas costs: Withdrawals involve transactions on both L2 and L1, each incurring gas fees.
  * Private key handling: Use secure key management practices in real applications.
  * RPC endpoint security: Keep your API key (or any RPC endpoint) secure.
</Info>


# Communicating between OP Stack and Ethereum in Solidity
Source: https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-solidity

Learn how to write Solidity contracts on OP Stack and Ethereum that can talk to each other.

This tutorial explains how to write Solidity contracts on OP Stack and Ethereum that can talk to each other.
Here you'll use a contract on OP Stack that can set a "greeting" variable on a contract on Ethereum, and vice-versa.
This is a simple example, but the same technique can be used to send any kind of message between the two chains.

You won't actually be deploying any smart contracts as part of this tutorial.
Instead, you'll reuse existing contracts that have already been deployed to OP Stack and Ethereum.
Later in the tutorial you'll learn exactly how these contracts work so you can follow the same pattern to deploy your own contracts.

<Info>
  Just looking to bridge tokens between OP Stack and Ethereum?
  Check out the tutorial on [Bridging ERC-20 Tokens to OP Stack With viem](./cross-dom-bridge-erc20).
</Info>

## Message passing basics

OP Stack uses a smart contract called the `CrossDomainMessenger` to pass messages between OP Stack and Ethereum.
Both chains have a version of this contract (the `L1CrossDomainMessenger` and the `L2CrossDomainMessenger`).
Messages sent from Ethereum to OP Stack are automatically relayed behind the scenes.
Messages sent from OP Stack to Ethereum must be explicitly relayed with a second transaction on Ethereum.
Read more about message passing in the guide to [Sending Data Between L1 and L2](/app-developers/guides/bridging/messaging).

## Dependencies

* [node](https://nodejs.org/en/)
* [pnpm](https://pnpm.io/installation)

## Get ETH on Sepolia and OP Sepolia

This tutorial explains how to send messages from Sepolia to OP Sepolia.
You will need to get some ETH on both of these testnets.

<TutorialFaucets />

## Review the contracts

You're about to use two contracts that have already been deployed to Sepolia and OP Sepolia, the `Greeter` contracts.
You can review the source code for the L1 `Greeter` contract [here on Etherscan](https://sepolia.etherscan.io/address/0x31A6Dd971306bb72f2ffF771bF30b1B98dB8B2c5#code).
You can review the source code for the L2 `Greeter` contract [here on Etherscan](https://testnet-explorer.optimism.io/address/0x5DE8a2957eddb140567fF90ba5d57bc9769f3055#code).
Both contracts have exactly the same source code.

Feel free to review the source code for these two contracts now if you'd like.
This tutorial will explain how these contracts work in detail later on in the [How It Works](#how-it-works) section below.

## Interact with the L1 Greeter

You're first going to use the L1 `Greeter` contract to set the greeting on the L2 `Greeter` contract.
You'll send a transaction directly to the L1 `Greeter` contract which will ask the `L1CrossDomainMessenger` to send a message to the L2 `Greeter` contract.
After just a few minutes, you'll see the corresponding greeting set on the L2 `Greeter` contract.

<Steps>
  <Step title="Connect to Etherscan">
    Sending a message to the L2 `Greeter` contract via the L1 `Greeter` contract requires that you call the `sendGreeting` function.
    For simplicity, you'll interact with the contract directly on Etherscan.
    Open up the [L1 `Greeter` contract on Sepolia Etherscan](https://sepolia.etherscan.io/address/0x31A6Dd971306bb72f2ffF771bF30b1B98dB8B2c5#writeContract) and click the "Connect to Web3" button.
  </Step>

  <Step title="Send your greeting">
    Put a greeting into the field next to the "sendGreeting" function and click the "Write" button.
    You can use any greeting you'd like.
  </Step>

  <Step title="Wait a few minutes">
    It will take a few minutes for your message to reach L2.
    Feel free to take a quick break while you wait.

    <Info>
      You can use viem to programmatically check the status of any message between L1 and L2.
      Later on in this tutorial you'll learn how to use viem and the `waitToProve` function to wait for various message statuses.
      This same function can be used to wait for a message to be relayed from L1 to L2.
    </Info>
  </Step>

  <Step title="Check the L2 Greeter">
    After a few minutes, you should see the greeting on the L2 `Greeter` contract change to the greeting you set.
    Open up the [L2 `Greeter` contract on OP Sepolia Etherscan](https://testnet-explorer.optimism.io/address/0x5DE8a2957eddb140567fF90ba5d57bc9769f3055#readContract) and click the "Read Contract" button.
    Paste your address into the field next to the "greeting" function and click the "Query" button.
    You should see the message you sent from L1.
  </Step>

  <Info>
    Haven't seen your message yet?
    You might need to wait a little longer.
    L2 transactions triggered on L1 are typically processed within one minute but can occasionally be slightly delayed.
  </Info>
</Steps>

## Interact with the L2 Greeter

Now you're going to use the L2 `Greeter` contract to set the greeting on the L1 `Greeter` contract.
You'll send a transaction directly to the L2 `Greeter` contract which will ask the `L2CrossDomainMessenger` to send a message to the L1 `Greeter` contract.
Unlike the previous step, you'll need to relay the message from L2 to L1 yourself.
You'll do this by sending two transactions on Sepolia, one proving transaction and one relaying transaction.

<Steps>
  <Step title="Connect to Etherscan">
    Just like before, sending a message to the L1 `Greeter` contract via the L2 `Greeter` contract requires that you call the `sendGreeting` function.
    Open up the [L2 `Greeter` contract on OP Sepolia Etherscan](https://testnet-explorer.optimism.io/address/0x5DE8a2957eddb140567fF90ba5d57bc9769f3055#writeContract) and click the "Connect to Web3" button.
  </Step>

  <Step title="Send your greeting">
    Put a greeting into the field next to the "sendGreeting" function and click the "Write" button.
    You can use any greeting you'd like.

    <Info>
      Copy the transaction hash from the transaction you just sent.
      You'll need this for the next few steps.
      Feel free to keep this tab open so you can easily copy the transaction hash later.
    </Info>
  </Step>

  <Step title="Create a demo project">
    You're going to use viem to prove and relay your message to L1.

    ```bash theme={null}
    mkdir cross-dom
    cd cross-dom
    pnpm init
    pnpm add viem@^2.51.0
    ```
  </Step>

  <Step title="Add environment variables">
    Set your private key and transaction hash as environment variables.

    ```bash theme={null}
    export TUTORIAL_PRIVATE_KEY=0x...
    export TUTORIAL_TRANSACTION_HASH=0x...
    ```
  </Step>

  <Step title="Run the script in a Node REPL">
    Start a Node.js REPL with `node` and paste the following script to monitor, prove, and finalize the cross-domain message:

    ```js theme={null}
    const { createPublicClient, http, createWalletClient } = require('viem');
    const { optimismSepolia, sepolia } = require('viem/chains');
    const { publicActionsL1, publicActionsL2, walletActionsL1, walletActionsL2, getWithdrawals, isSuperGameType } = require('viem/op-stack');
    const { privateKeyToAccount } = require('viem/accounts');

    const l1Provider = createPublicClient({
      chain: sepolia,
      transport: http('https://eth-sepolia.g.alchemy.com/v2/your-key')
    }).extend(publicActionsL1());

    const l2Provider = createPublicClient({
      chain: optimismSepolia,
      transport: http('https://opt-sepolia.g.alchemy.com/v2/your-key')
    }).extend(publicActionsL2());

    const account = privateKeyToAccount(process.env.TUTORIAL_PRIVATE_KEY);

    const l1Wallet = createWalletClient({
      account,
      chain: sepolia,
      transport: http('https://eth-sepolia.g.alchemy.com/v2/your-key')
    }).extend(walletActionsL1());

    const l2Wallet = createWalletClient({
      account,
      chain: optimismSepolia,
      transport: http('https://opt-sepolia.g.alchemy.com/v2/your-key')
    }).extend(walletActionsL2());

    const receipt = await l2Provider.getTransactionReceipt({
      hash: process.env.TUTORIAL_TRANSACTION_HASH
    });
    const withdrawalBlock = await l2Provider.getBlock({
      blockNumber: receipt.blockNumber
    });
    const respectedGameType = await l1Provider.readContract({
      abi: [{
        inputs: [],
        name: 'respectedGameType',
        outputs: [{ type: 'uint32' }],
        stateMutability: 'view',
        type: 'function'
      }],
      address: l2Provider.chain.contracts.portal[l1Provider.chain.id].address,
      functionName: 'respectedGameType'
    });
    const proveContext = isSuperGameType(Number(respectedGameType))
      ? { l2Timestamp: withdrawalBlock.timestamp }
      : {};

    console.log('Waiting for message to be provable...');
    await l1Provider.getWithdrawalStatus({
      ...proveContext,
      receipt,
      targetChain: l2Provider.chain
    });

    console.log('Proving message...');
    const { game, withdrawal } = await l1Provider.waitToProve({
      ...proveContext,
      receipt,
      targetChain: l2Provider.chain
    });

    const proveArgs = await l2Provider.buildProveWithdrawal({
      account,
      game,
      withdrawal
    });

    await l1Wallet.proveWithdrawal(proveArgs);

    console.log('Waiting for message to be relayable...');
    await l1Provider.waitToFinalize({
      targetChain: l2Provider.chain,
      withdrawalHash: withdrawal.withdrawalHash
    });

    console.log('Relaying message...');
    await l1Wallet.finalizeWithdrawal({
      targetChain: l2Wallet.chain,
      withdrawal
    });

    console.log('Message relayed!');
    ```
  </Step>

  <Step title="Verify the L1 greeting">
    After finalization, open the [L1 `Greeter` contract on Sepolia Etherscan](https://sepolia.etherscan.io/address/0x31A6Dd971306bb72f2ffF771bF30b1B98dB8B2c5#readContract).
    Confirm that the greeting has been updated to the message you sent from L2.
  </Step>
</Steps>

## How it works

Congratulations! You've successfully sent a message from L1 to L2 and from L2 to L1.
This section explains how the `Greeter` contracts work so you can follow the same pattern to deploy your own contracts.
Luckily, both `Greeter` contracts are exactly the same so it's easy to see how everything comes together.

### The Messenger variable

The `Greeter` contract has a `MESSENGER` variable that keeps track of the `CrossDomainMessenger` contract on the current chain.
Check out the [Contract Addresses page](/op-mainnet/network-information/op-addresses) to see the addresses of the `CrossDomainMessenger` contracts on whatever network you'll be using.

```solidity theme={null}
address public immutable MESSENGER;
```

### The other Greeter variable

The `Greeter` contract also has an `OTHER_GREETER` variable that keeps track of the `Greeter` contract on the other chain.
On L1, this variable is set to the address of the L2 `Greeter` contract, and vice-versa.

```solidity theme={null}
address public immutable OTHER_GREETER;
```

### The Greetings mapping

The `Greeter` contract keeps track of the different greetings that users have sent inside a `greetings` mapping.
By using a mapping, this contract can keep track of greetings from different users at the same time.

```solidity theme={null}
mapping(address => string) public greetings;
```

### The Constructor

The `Greeter` has a simple constructor that sets the `MESSENGER` and `OTHER_GREETER` variables.

```solidity theme={null}
constructor(address messenger, address otherGreeter) {
  MESSENGER = messenger;
  OTHER_GREETER = otherGreeter;
}
```

### The sendGreeting function

The `sendGreeting` function is the most important function in the `Greeter` contract.
This is what you called earlier to send messages in both directions.
All this function does is use the `sendMessage` function found within the `CrossDomainMessenger` contract to send a message to the `Greeter` contract on the other chain.

```solidity theme={null}
function sendGreeting(string calldata newGreeting) external payable {
  ICrossDomainMessenger(MESSENGER).sendMessage(
    OTHER_GREETER,
    abi.encodeWithSelector(Greeter.setGreeting.selector, msg.sender, newGreeting),
    100_000
  );
}
```

### The setGreeting function

The `setGreeting` function is the function that actually sets the greeting.
This function is called by the `CrossDomainMessenger` contract on the other chain.
It checks explicitly that the function can only be called by the `CrossDomainMessenger` contract.
It also checks that the `CrossChainMessenger` says that the message came from the `Greeter` contract on the other chain.
Finally, it sets the greeting in the `greetings` mapping.

```solidity theme={null}
function setGreeting(address sender, string calldata newGreeting) external {
  require(msg.sender == MESSENGER, "Only messenger");
  require(
    ICrossDomainMessenger(MESSENGER).xDomainMessageSender() == OTHER_GREETER,
    "Only remote greeter"
  );
  greetings[sender] = newGreeting;
}
```

<Info>
  The two `require` statements in this function are important.
  Without them, anyone could call this function and set the greeting to whatever they want.
  You can follow a similar pattern in your own smart contracts.
</Info>

## Conclusion

You just learned how you can write Solidity contracts on Sepolia and OP Sepolia that can talk to each other.
You can follow the same pattern to write contracts that can talk to each other on Ethereum and OP Stack.

```solidity theme={null}
interface ICrossDomainMessenger {
  function sendMessage(address target, bytes calldata message, uint32 gasLimit) external;
  function xDomainMessageSender() external view returns (address);
}
```

This sort of cross-chain communication is useful for a variety of reasons.
For example, the [Standard Bridge](/app-developers/guides/bridging/standard-bridge) contracts use this same system to bridge ETH and ERC-20 tokens between Ethereum and OP Stack.
One cool way to take advantage of cross-chain communication is to do most of your heavy lifting on OP Stack and then send a message to Ethereum only when you have important results to share.
This way you can take advantage of the low gas costs on OP Stack while still being able to use Ethereum when you need it.


# Deposit transactions
Source: https://docs.optimism.io/app-developers/tutorials/bridging/deposit-transactions

Learn about using deposit transactions with `supersim`.

Supersim supports [deposit transactions](/op-stack/bridging/deposit-flow). It uses a very lightweight solution without the `op-node` derivation pipeline by listening directly to the `TransactionDeposited` events on the `OptimismPortal` contract and simply forwarding the transaction to the applicable L2.

The execution engine used with Supersim must support the Optimism [deposit transaction type](https://specs.optimism.io/protocol/deposits.html#the-deposited-transaction-type).

## `OptimismPortal`

When starting Supersim, the L1 contracts for each L2 chain are emitted as output to the console. The `L1CrossDomainMessenger`, `L1StandardBridge`, and `OptimismPortal` can be used to initiate deposits in the same manner as one would on a production network like OP Mainnet or Base.

```bash theme={null}
Chain Configuration
-----------------------
L1: Name: Local  ChainID: 900  RPC: http://127.0.0.1:8545  LogPath: ...

L2: Predeploy Contracts Spec ( https://specs.optimism.io/protocol/predeploys.html )

  * Name: OPChainA  ChainID: 901  RPC: http://127.0.0.1:9545  LogPath: ...
    L1 Contracts:
     - OptimismPortal:         0x37a418800d0c812A9dE83Bc80e993A6b76511B57
     - L1CrossDomainMessenger: 0xcd712b03bc6424BF45cE6C29Fc90FFDece228F6E
     - L1StandardBridge:       0x8d515eb0e5F293B16B6bBCA8275c060bAe0056B0

  ...
```

If running Supersim in fork mode, the production contracts will be used for each of the forked networks.

```bash theme={null}
Chain Configuration
-----------------------
L1: Name: mainnet  ChainID: 1  RPC: http://127.0.0.1:8545  LogPath: ...

L2: Predeploy Contracts Spec ( https://specs.optimism.io/protocol/predeploys.html )

  * Name: op  ChainID: 10  RPC: http://127.0.0.1:9545  LogPath: ...
    L1 Contracts:
     - OptimismPortal:         0xbEb5Fc579115071764c7423A4f12eDde41f106Ed
     - L1CrossDomainMessenger: 0x25ace71c97B33Cc4729CF772ae268934F7ab5fA1
     - L1StandardBridge:       0x99C9fc46f92E8a1c0deC1b1747d010903E884bE1

  * Name: mode  ChainID: 34443  RPC: http://127.0.0.1:9546  LogPath: ...
    L1 Contracts:
     - OptimismPortal:         0x8B34b14c7c7123459Cf3076b8Cb929BE097d0C07
     - L1CrossDomainMessenger: 0x95bDCA6c8EdEB69C98Bd5bd17660BaCef1298A6f
     - L1StandardBridge:       0x735aDBbE72226BD52e818E7181953f42E3b0FF21

   ...
```

## Sample Deposit Flow

We'll run through a sample deposit directly with the `OptimismPortal` using cast.

<Steps>
  <Step title="Run Supersim">
    ```bash theme={null}
      supersim
    ```
  </Step>

  <Step title="Observe OptimismPortal Contract Address">
    ```bash theme={null}
      ...
      * Name: OPChainA  ChainID: 901 ...
          L1 Contracts:
           - OptimismPortal: 0x37a418800d0c812A9dE83Bc80e993A6b76511B57
      ...
    ```
  </Step>

  <Step title="Send Deposit Transaction On L1">
    We'll be using the first pre-funded account to send this deposit of 1 ether

    ```bash theme={null}
    cast send 0x37a418800d0c812A9dE83Bc80e993A6b76511B57 --value 1ether --rpc-url http://localhost:8545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
    ```
  </Step>

  <Step title="Verify With Supersim Logs">
    ```bash theme={null}
      INFO [11-28|13:56:06.756] OptimismPortal#depositTransaction chain.id=901 l2TxHash=0x592d6e13016751332115df1fce59904176bfe447854196ed1b97ee00f14be469
    ```
  </Step>
</Steps>

## Next steps

* See the [transaction guides](/app-developers/guides/transactions/estimates) for more detailed information.
* Questions about Interop? Check out collection of [interop guides](/op-stack/interop/explainer) or check out this [OP Stack interop design video walk-thru](https://www.youtube.com/watch?v=FKc5RgjtGes).
* For more info about how OP Stack interoperability works under the hood, [check out the specs](https://specs.optimism.io/interop/overview.html?utm_source=op-docs\&utm_medium=docs).


# Replaying a failed deposit
Source: https://docs.optimism.io/app-developers/tutorials/bridging/replay-failed-deposit

Learn how deposit replays work by deliberately failing a deposit against a test contract on OP Sepolia and then replaying it with more gas, end to end.

When a deposit transaction fails on L2 — usually because it ran out of gas or the L2 state didn't allow it to succeed — the message isn't lost. `L2CrossDomainMessenger` records it as a failed message, and you can replay it later, optionally with more gas.

In this tutorial, you'll make a deposit fail on purpose against a test contract, then replay it successfully, so you can see the full failure-and-replay cycle end to end. For the concepts behind deposits and why replays are possible, see [Deposit flow](/op-stack/bridging/deposit-flow).

## Before you begin

* [Foundry](https://book.getfoundry.sh/getting-started/installation) installed (this tutorial uses `cast`).
* A test account private key, funded with a small amount of test ETH on both **Ethereum Sepolia** (L1) and **OP Sepolia** (L2).
* An L1 (Ethereum Sepolia) RPC URL — e.g. a free [Infura](https://infura.io) key or another provider.

<Info>
  **L1 vs L2 network clarification**

  This tutorial involves **two different networks**:

  * **L1**: Ethereum Sepolia testnet (`https://sepolia.infura.io/v3/YOUR_KEY`)
  * **L2**: OP Sepolia testnet (`https://sepolia.optimism.io`)

  You'll send transactions on L1 that trigger actions on L2. Make sure you're using the correct RPC URLs for each step.
</Info>

## Trigger and replay a failed deposit

To see how replays work, you can use [this contract on OP Sepolia](https://testnet-explorer.optimism.io/address/0xEF60cF6C6D0C1c755be104843bb72CDa3D778630#code).

1. Call `stopChanges`, using this Foundry command:

   ```sh theme={null}
   PRIV_KEY=<your private key here>
   export ETH_RPC_URL=https://sepolia.optimism.io
   GREETER=0xEF60cF6C6D0C1c755be104843bb72CDa3D778630
   cast send --private-key $PRIV_KEY $GREETER "stopChanges()"
   ```

2. Verify that `getStatus()` returns false, meaning changes are not allowed, and see the value of `greet()` using Foundry.
   Note that Foundry returns false as zero.

   ```sh theme={null}
   cast call $GREETER "greet()" | cast --to-ascii ; cast call $GREETER "getStatus()"
   ```

3. Get the calldata.
   You can use this Foundry command:

   ```sh theme={null}
   cast calldata "setGreeting(string)" "testing"
   ```

   Or just use this value:

   ```
   0xa41368620000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000000774657374696e6700000000000000000000000000000000000000000000000000
   ```

4. Send a greeting change as a deposit from L1 (Ethereum Sepolia) to L2 (OP Sepolia).
   Use these commands:

   ```sh theme={null}
   # L1 = Ethereum Sepolia
   # Get a free Infura key at https://infura.io or use the public RPC below
   L1_RPC=https://sepolia.infura.io/v3/YOUR_INFURA_KEY    
   L1XDM_ADDRESS=0x5086d1eef304eb5284a0f6720f79403b4e9be294
   FUNC="sendMessage(address,bytes,uint32)"
   CALLDATA=`cast calldata "setGreeting(string)" "testing"`
   cast send --rpc-url $L1_RPC --private-key $PRIV_KEY $L1XDM_ADDRESS $FUNC $GREETER $CALLDATA 10000000
   ```

   The transaction will be successful on **L1 (Ethereum Sepolia)**, but then emit a fail event on **L2 (OP Sepolia)**.

5. The next step is to find the hash of the failed relay. There are several ways to do this:

   **Method A: Using Etherscan Internal Transactions**

   Look in [the internal transactions of the destination contract](https://testnet-explorer.optimism.io/address/0xEF60cF6C6D0C1c755be104843bb72CDa3D778630#internaltx), and select the latest one that appears as a failure. It should be a call to `L2CrossDomainMessenger` at address `0x420...007`.

   **Method B: Using Contract Events (if internal transactions aren't visible)**

   If you can't see internal transactions on Etherscan, check the [L2CrossDomainMessenger contract events](https://testnet-explorer.optimism.io/address/0x4200000000000000000000000000000000000007#events) and look for `FailedRelayedMessage` events with your contract address.

   **Method C: Using cast to query failed messages**

   ```sh theme={null}
   # First, you need the message hash. You can derive it from the L1 transaction, or check events
   L2XDM_ADDRESS=0x4200000000000000000000000000000000000007
   # Replace MSG_HASH with the actual message hash from the FailedRelayedMessage event
   cast call $L2XDM_ADDRESS "failedMessages(bytes32)" $MSG_HASH
   ```

   If the latest internal transaction is a success, it probably means your transaction hasn't relayed yet. Wait until it is, that may take a few minutes.

6. Get the transaction information using Foundry.

   <Info>
     **Wait for the failed relay transaction**

     Make sure you wait for the deposit to be processed on L2 and fail before proceeding. This can take 2-5 minutes. You should see a failed transaction in one of the methods from step 5.
   </Info>

   ```sh theme={null}
   TX_HASH=<transaction hash from the failed relay on L2>
   L2XDM_ADDRESS=0x4200000000000000000000000000000000000007
   REPLAY_DATA=`cast tx $TX_HASH input`
   ```

7. Call `startChanges()` to allow changes using this Foundry command:

   ```sh theme={null}
   cast send --private-key $PRIV_KEY $GREETER "startChanges()"
   ```

   <Info>
     Don't do this prematurely

     If you call `startChanges()` too early, it will happen when the message is relayed to L2, and then the initial deposit will be successful and there will be no need to replay it.
   </Info>

8. Verify that `getStatus()` returns true, meaning changes are not allowed, and see the value of `greet()`.
   Foundry returns true as one.

   ```sh theme={null}
   cast call $GREETER "greet()" | cast --to-ascii ; cast call $GREETER "getStatus()"
   ```

9. Now send the replay transaction.

   ```sh theme={null}
   cast send --private-key $PRIV_KEY --gas-limit 10000000 $L2XDM_ADDRESS $REPLAY_DATA 
   ```

   <Info>
     Why do we need to specify the gas limit?

     The gas estimation mechanism tries to find the minimum gas limit at which the transaction would be successful.
     However, `L2CrossDomainMessenger` does not revert when a replay fails due to low gas limit, it just emits a failure message.
     The gas estimation mechanism considers that a success.

     To get a gas estimate, you can use this command:

     ```sh theme={null}
     cast estimate --from 0x0000000000000000000000000000000000000001 $L2XDM_ADDRESS $REPLAY_DATA
     ```

     That address is a special case in which the contract does revert.
   </Info>

10. Verify the greeting has changed:

    ```sh theme={null}
    cast call $GREETER "greet()" | cast --to-ascii ; cast call $GREETER "getStatus()"
    ```

## Debugging

To debug deposit transactions, you can ask the L2 cross domain messenger for the state of the transaction.

1. Look on Etherscan to see the `FailedRelayedMessage` event. Set `MSG_HASH` to that value.

2. To check if the message is listed as failed, run this:

   ```sh theme={null}
   cast call $L2XDM_ADDRESS "failedMessages(bytes32)" $MSG_HASH
   ```

   To check if it is listed as successful, run this:

   ```sh theme={null}
   cast call $L2XDM_ADDRESS "successfulMessages(bytes32)" $MSG_HASH
   ```

## Next steps

* Read [Deposit flow](/op-stack/bridging/deposit-flow) to understand how deposits are processed across L1 and L2 under the hood.
* Learn about [sending data between L1 and L2](/app-developers/guides/bridging/messaging) from your contracts.


# Create an L2 token for the Standard Bridge
Source: https://docs.optimism.io/app-developers/tutorials/bridging/standard-bridge-standard-token

Learn how to create a standard or custom L2 representation of an L1 ERC-20 token that works with the Standard Bridge on an OP Stack chain.

In this tutorial, you'll create an L2 representation of an L1 ERC-20 token that works with the Standard Bridge system on an OP Stack chain.
This tutorial is meant for developers who already have an existing ERC-20 token on Ethereum and want to create a bridged representation of that token on layer 2.
By the end, you'll have an L2 token contract deployed on OP Sepolia that the Standard Bridge can mint and burn.
This tutorial does not cover the bridging itself: once your L2 token exists, follow [Bridging ERC-20 tokens with viem](./cross-dom-bridge-erc20) to move tokens between L1 and L2.

The Standard Bridge supports two kinds of L2 tokens, and this tutorial covers both:

* A **standard token** deployed through the [`OptimismMintableERC20Factory`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/OptimismMintableERC20Factory.sol).
  Tokens created by this factory contract are compatible with the Standard Bridge system and include basic logic for deposits, transfers, and withdrawals.
  Choose this path if you don't need any specialized logic in your L2 token.
* A **custom token** that implements the [`IOptimismMintableERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/universal/IOptimismMintableERC20.sol) interface itself.
  A custom token allows you to do things like trigger extra logic whenever a token is deposited.
  Choose this path if you need specialized behavior like that.

Both paths share the same setup and fork at the [Create an L2 ERC-20 token](#create-an-l2-erc-20-token) section, where each path has its own tab.

<Info>
  The Standard Bridge **does not** support [**fee on transfer tokens**](https://github.com/d-xo/weird-erc20#fee-on-transfer) or [**rebasing tokens**](https://github.com/d-xo/weird-erc20#balance-modifications-outside-of-transfers-rebasingairdrops) because they can cause bridge accounting errors.
</Info>

## About OptimismMintableERC20s

The Standard Bridge system requires that L2 representations of L1 tokens implement the [`IOptimismMintableERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/universal/IOptimismMintableERC20.sol) interface.
This interface is a superset of the standard ERC-20 interface and includes functions that allow the bridge to properly verify deposits/withdrawals and mint/burn tokens as needed.
Your L2 token contract must implement this interface in order to be bridged using the Standard Bridge system.
This tutorial will show you how to deploy a basic standardized ERC-20 token through the [`OptimismMintableERC20Factory`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/OptimismMintableERC20Factory.sol), or how to write a custom token that implements the interface itself.

## Dependencies

* [cast](https://book.getfoundry.sh/getting-started/installation), used on the standard-token path to deploy through the factory
* A web browser with a wallet extension, used on the custom-token path to deploy with [Remix](https://remix.ethereum.org)

## Get ETH on Sepolia and OP Sepolia

This tutorial explains how to create a bridged ERC-20 token on OP Sepolia.
You will need to get some ETH on both of these testnets.

<TutorialFaucets />

## Get an L1 ERC-20 token address

You will need an L1 ERC-20 token for this tutorial.
If you already have an L1 ERC-20 token deployed on Sepolia, you can skip this step.
Otherwise, you can use the testing token located at [`0x5589BB8228C07c4e15558875fAf2B859f678d129`](https://sepolia.etherscan.io/address/0x5589BB8228C07c4e15558875fAf2B859f678d129) that includes a `faucet()` function that can be used to mint tokens.

## Create an L2 ERC-20 token

Once you have an L1 ERC-20 token, you can create a corresponding L2 ERC-20 token on OP Sepolia.
Pick the tab that matches the kind of token you want to create.

<Tabs>
  <Tab title="Standard token">
    You can deploy your L2 ERC-20 token using the [`OptimismMintableERC20Factory`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/OptimismMintableERC20Factory.sol).
    All tokens created by the factory implement the `IOptimismMintableERC20` interface and are compatible with the Standard Bridge system.

    <Steps>
      <Step title="Add a private key to your environment">
        You need a private key in order to sign transactions.
        Set your private key as an environment variable with the `export` command.
        Make sure this private key corresponds to an address that has ETH on .

        <Info>
          Want to create a new wallet for this tutorial?
          If you have [`cast`](https://book.getfoundry.sh/getting-started/installation) installed you can run `cast wallet new` in your terminal to create a new wallet and get the private key.
        </Info>

        ```bash theme={null}
        export TUTORIAL_PRIVATE_KEY=0x...
        ```
      </Step>

      <Step title="Add an OP Sepolia RPC URL to your environment">
        You'll need an RPC URL in order to connect to OP Sepolia.
        Set your RPC URL as an environment variable with the `export` command.

        ```bash theme={null}
        export TUTORIAL_RPC_URL=https://sepolia.optimism.io
        ```
      </Step>

      <Step title="Add your L1 ERC-20 token address to your environment">
        You'll need to know the address of your L1 ERC-20 token in order to create a bridged representation of it on OP Sepolia.
        Set your L1 ERC-20 token address as an environment variable with the `export` command.

        ```bash theme={null}
        # Replace this with your L1 ERC-20 token if not using the testing token!
        export TUTORIAL_L1_ERC20_ADDRESS=0x5589BB8228C07c4e15558875fAf2B859f678d129
        ```
      </Step>

      <Step title="Deploy your L2 ERC-20 token">
        You can now deploy your L2 ERC-20 token using the [`OptimismMintableERC20Factory`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/OptimismMintableERC20Factory.sol).
        Use the `cast` command to trigger the deployment function on the factory contract.
        This example command creates a token with the name "My Standard Demo Token" and the symbol "L2TKN".
        The resulting L2 ERC-20 token address is printed to the console.

        ```bash theme={null}
        cast send 0x4200000000000000000000000000000000000012 "createOptimismMintableERC20(address,string,string)" $TUTORIAL_L1_ERC20_ADDRESS "My Standard Demo Token" "L2TKN" --private-key $TUTORIAL_PRIVATE_KEY --rpc-url $TUTORIAL_RPC_URL --json | jq -r '.logs[0].topics[2]' | cast parse-bytes32-address
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Custom token">
    This path uses [Remix](https://remix.ethereum.org) so you can easily deploy a token without a framework like [Hardhat](https://hardhat.org) or [Foundry](https://getfoundry.sh).
    You can follow the same general process within your favorite framework if you prefer.

    In this section, you'll be creating an ERC-20 token that can be deposited but cannot be withdrawn.
    This is just one example of the endless ways in which you could customize your L2 token.

    <Steps>
      <Step title="Add OP Sepolia to your wallet">
        You will need to add the OP Sepolia network to your wallet in order to follow this path.
        You can use [this website](https://chainid.link?network=op-sepolia) to connect your wallet to OP Sepolia.
      </Step>

      <Step title="Open Remix">
        Navigate to [Remix](https://remix.ethereum.org) in your browser.
      </Step>

      <Step title="Create a new file">
        Click the 📄 ("Create new file") button to create a new empty Solidity file.
        You can name this file whatever you'd like, for example `MyCustomL2Token.sol`.
      </Step>

      <Step title="Copy the example contract">
        Copy the following example contract into your new file:

        ```solidity theme={null}
        // SPDX-License-Identifier: MIT
        pragma solidity 0.8.20;

        // Import the standard ERC20 implementation from OpenZeppelin
        import { ERC20 } from "@openzeppelin/contracts/token/ERC20/ERC20.sol";
        import { IERC165 } from "@openzeppelin/contracts/utils/introspection/IERC165.sol";

        /**
        * @title ILegacyMintableERC20
        * @notice Legacy interface for the StandardL2ERC20 contract.
        */
        interface ILegacyMintableERC20 {
        function mint(address _to, uint256 _amount) external;
        function burn(address _from, uint256 _amount) external;

        function l1Token() external view returns (address);
        function l2Bridge() external view returns (address);
        }

        /**
        * @title IOptimismMintableERC20
        * @notice Interface for the OptimismMintableERC20 contract.
        */
        interface IOptimismMintableERC20 {
        function remoteToken() external view returns (address);
        function bridge() external view returns (address);
        function mint(address _to, uint256 _amount) external;
        function burn(address _from, uint256 _amount) external;
        }

        /**
        * @title Simplified Semver for tutorial
        * @notice Simple contract to track semantic versioning
        */
        contract Semver {
        string public version;

        // Simple function to convert uint to string for version numbers
        function toString(uint256 value) internal pure returns (string memory) {
            // This function handles numbers from 0 to 999 which is sufficient for versioning
            if (value == 0) {
                return "0";
            }
            
            uint256 temp = value;
            uint256 digits;
            
            while (temp != 0) {
                digits++;
                temp /= 10;
            }
            
            bytes memory buffer = new bytes(digits);
            
            while (value != 0) {
                digits -= 1;
                buffer[digits] = bytes1(uint8(48 + uint256(value % 10)));
                value /= 10;
            }
            
            return string(buffer);
        }

        constructor(uint256 major, uint256 minor, uint256 patch) {
            version = string(abi.encodePacked(
                toString(major),
                ".",
                toString(minor),
                ".",
                toString(patch)
            ));
        }
        }

        /**
        * @title MyCustomL2Token
        * @notice A custom L2 token based on OptimismMintableERC20 that can be deposited 
        *         from L1 to L2, but cannot be withdrawn from L2 to L1.
        */
        contract MyCustomL2Token is IOptimismMintableERC20, ILegacyMintableERC20, ERC20, Semver {
        /// @notice Address of the corresponding token on the remote chain.
        address public immutable REMOTE_TOKEN;

        /// @notice Address of the StandardBridge on this network.
        address public immutable BRIDGE;

        /// @notice Emitted whenever tokens are minted for an account.
        /// @param account Address of the account tokens are being minted for.
        /// @param amount  Amount of tokens minted.
        event Mint(address indexed account, uint256 amount);

        /// @notice Emitted whenever tokens are burned from an account.
        /// @param account Address of the account tokens are being burned from.
        /// @param amount  Amount of tokens burned.
        event Burn(address indexed account, uint256 amount);

        /// @notice A modifier that only allows the bridge to call
        modifier onlyBridge() {
            require(msg.sender == BRIDGE, "MyCustomL2Token: only bridge can mint and burn");
            _;
        }

        /// @param _bridge      Address of the L2 standard bridge.
        /// @param _remoteToken Address of the corresponding L1 token.
        /// @param _name        ERC20 name.
        /// @param _symbol      ERC20 symbol.
        constructor(
            address _bridge,
            address _remoteToken,
            string memory _name,
            string memory _symbol
        )
            ERC20(_name, _symbol)
            Semver(1, 0, 0)
        {
            REMOTE_TOKEN = _remoteToken;
            BRIDGE = _bridge;
        }

        /// @notice Allows the StandardBridge on this network to mint tokens.
        /// @param _to     Address to mint tokens to.
        /// @param _amount Amount of tokens to mint.
        function mint(
            address _to,
            uint256 _amount
        )
            external
            virtual
            override(IOptimismMintableERC20, ILegacyMintableERC20)
            onlyBridge
        {
            _mint(_to, _amount);
            emit Mint(_to, _amount);
        }

        /// @notice Burns tokens from an account.
        /// @dev This function always reverts to prevent withdrawals to L1.
        /// @param _from   Address to burn tokens from.
        /// @param _amount Amount of tokens to burn.
        function burn(
            address _from,
            uint256 _amount
        )
            external
            virtual
            override(IOptimismMintableERC20, ILegacyMintableERC20)
            onlyBridge
        {
            // Instead of calling _burn(_from, _amount), we revert
            // This makes it impossible to withdraw tokens back to L1
            revert("MyCustomL2Token: withdrawals are not allowed");
            
            // Note: The following line would normally execute but is unreachable
            // _burn(_from, _amount);
            // emit Burn(_from, _amount);
        }

        /// @notice ERC165 interface check function.
        /// @param _interfaceId Interface ID to check.
        /// @return Whether or not the interface is supported by this contract.
        function supportsInterface(bytes4 _interfaceId) external pure virtual returns (bool) {
            bytes4 iface1 = type(IERC165).interfaceId;
            // Interface corresponding to the legacy L2StandardERC20
            bytes4 iface2 = type(ILegacyMintableERC20).interfaceId;
            // Interface corresponding to the updated OptimismMintableERC20
            bytes4 iface3 = type(IOptimismMintableERC20).interfaceId;
            return _interfaceId == iface1 || _interfaceId == iface2 || _interfaceId == iface3;
        }

        /// @notice Legacy getter for the remote token. Use REMOTE_TOKEN going forward.
        function l1Token() public view override returns (address) {
            return REMOTE_TOKEN;
        }

        /// @notice Legacy getter for the bridge. Use BRIDGE going forward.
        function l2Bridge() public view override returns (address) {
            return BRIDGE;
        }

        /// @notice Getter for REMOTE_TOKEN.
        function remoteToken() public view override returns (address) {
            return REMOTE_TOKEN;
        }

        /// @notice Getter for BRIDGE.
        function bridge() public view override returns (address) {
            return BRIDGE;
        }
        }
        ```
      </Step>

      <Step title="Review the example contract">
        Take a moment to review the example contract. It's closely based on the official [`OptimismMintableERC20`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/OptimismMintableERC20.sol) contract with one key modification:

        The `burn` function has been modified to always revert, making it impossible to withdraw tokens back to L1.

        Since the bridge needs to burn tokens when users want to withdraw them to L1, this means that users will not be able to withdraw tokens from this contract. Here's the key part of the contract that prevents withdrawals:

        ```solidity theme={null}
        /// @notice Burns tokens from an account.
        /// @dev This function always reverts to prevent withdrawals to L1.
        /// @param _from   Address to burn tokens from.
        /// @param _amount Amount of tokens to burn.
        function burn(
            address _from,
            uint256 _amount
        )
            external
            virtual
            override(IOptimismMintableERC20, ILegacyMintableERC20)
            onlyBridge
        {
            // Instead of calling _burn(_from, _amount), we revert
            // This makes it impossible to withdraw tokens back to L1
            revert("MyCustomL2Token: withdrawals are not allowed");
            
            // Note: The following line would normally execute but is unreachable
            // _burn(_from, _amount);
            // emit Burn(_from, _amount);
        }
        ```
      </Step>

      <Step title="Compile the contract">
        Save the file to automatically compile the contract.
        If you've disabled auto-compile, you'll need to manually compile the contract by clicking the "Solidity Compiler" tab (this looks like the letter "S") and press the blue "Compile" button.

        Make sure you're using Solidity compiler version 0.8.20, the exact version the example contract's `pragma solidity 0.8.20;` requires.
      </Step>

      <Step title="Deploy the contract">
        Open the deployment tab (this looks like an Ethereum logo with an arrow pointing left).
        Make sure that your environment is set to "Injected Provider", your wallet is connected to OP Sepolia, and Remix has access to your wallet.
        Then, select the `MyCustomL2Token` contract from the deployment dropdown and deploy it with the following parameters:

        ```text theme={null}
        _bridge:      "0x4200000000000000000000000000000000000010" // L2 Standard Bridge address
        _remoteToken: "<L1 ERC-20 address>"                        // Your L1 token address
        _name:        "My Custom L2 Token"                         // Your token name
        _symbol:      "MCL2T"                                      // Your token symbol
        ```

        Note: The L2 Standard Bridge address is a predefined address on all OP Stack chains, so it will be the same on OP Sepolia and OP Mainnet.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Bridge some tokens

Now that you have an L2 ERC-20 token, you can bridge some tokens from L1 to L2.
Check out the tutorial on [Bridging ERC-20 tokens with viem](./cross-dom-bridge-erc20) to learn how to bridge your L1 ERC-20 to L2s using viem.
If you deployed the custom example token from this tutorial, remember that the withdrawal step will *not* work for it: the example contract's `burn` function always reverts, which is exactly what that example was meant to demonstrate.

## Add to the Superchain Token List

The [Superchain Token List](https://github.com/ethereum-optimism/ethereum-optimism.github.io#readme) is a common list of tokens deployed on chains within the Optimism Superchain.
This list is used by services like the [Superchain Bridges UI](https://app.optimism.io/bridge?utm_source=op-docs\&utm_medium=docs).
If you want your OP Mainnet token to be included in this list, take a look at the [review process and merge criteria](https://github.com/ethereum-optimism/ethereum-optimism.github.io#review-process-and-merge-criteria).


# Deploy a contract to OP Sepolia
Source: https://docs.optimism.io/app-developers/tutorials/deploy-a-contract

Deploy your first smart contract to an OP Stack chain and interact with it using Foundry.

This tutorial walks you through deploying your first smart contract to an OP Stack chain from scratch.
You'll deploy a small `Greeter` contract to the OP Sepolia testnet with [Foundry](https://getfoundry.sh/), then read from and write to it from the command line.

OP Stack chains are [EVM equivalent](/op-stack/protocol/differences), so the workflow here is the same one you'd use on Ethereum: the only OP-specific detail is the RPC endpoint and chain ID you point at.
By the end you'll have a live contract on OP Sepolia and the commands to interact with any contract you deploy later.

<Info>
  This tutorial uses the OP Sepolia testnet, so you won't spend real funds.
  The same steps work on any OP Stack chain — swap in that chain's RPC URL and fund your account on that network.
</Info>

## Dependencies

* [Foundry](https://book.getfoundry.sh/getting-started/installation) — installed in the first step below.
* A terminal with `curl` available (preinstalled on macOS and most Linux distributions).

## Install Foundry

Foundry is a toolkit for Ethereum development.
This tutorial uses two of its command-line tools: `forge` (to compile and deploy) and `cast` (to send transactions and read state).

<Steps>
  <Step title="Install foundryup">
    ```bash theme={null}
    curl -L https://foundry.paradigm.xyz | bash
    ```

    This installs `foundryup`, Foundry's version manager.
    Follow the on-screen instructions to add it to your `PATH` (you may need to open a new terminal).
  </Step>

  <Step title="Install the Foundry toolchain">
    ```bash theme={null}
    foundryup
    ```
  </Step>
</Steps>

### Verify the install

Confirm `forge` and `cast` are available:

```bash theme={null}
forge --version
cast --version
```

Each command should print a version string.
If the command isn't found, revisit the `PATH` instructions from `foundryup` and open a new terminal.

## Create a project and contract

<Steps>
  <Step title="Initialize a Foundry project">
    ```bash theme={null}
    mkdir first-contract
    cd first-contract
    forge init
    ```

    `forge init` scaffolds a new project with `src/`, `test/`, and `script/` directories.
  </Step>

  <Step title="Add the Greeter contract">
    Replace the contents of `src/Greeter.sol` with the following.
    This is a variation on [Hardhat's Greeter contract](https://github.com/matter-labs/hardhat-zksync/blob/main/examples/upgradable-example/contracts/Greeter.sol): it stores a greeting string, exposes it through `greet()`, and lets anyone update it through `setGreeting()`.

    ```solidity theme={null}
    //SPDX-License-Identifier: MIT
    pragma solidity ^0.8.0;

    contract Greeter {
        string greeting;

        event SetGreeting(
            address indexed sender,     // msg.sender
            string greeting
        );

        function greet() public view returns (string memory) {
            return greeting;
        }

        function setGreeting(string memory _greeting) public {
            greeting = _greeting;
            emit SetGreeting(msg.sender, _greeting);
        }
    }
    ```
  </Step>

  <Step title="Compile the contract">
    ```bash theme={null}
    forge build
    ```
  </Step>
</Steps>

### Verify the build

`forge build` should report a successful compilation and write artifacts to the `out/` directory.
If compilation fails, check that `src/Greeter.sol` matches the code above exactly.

## Configure OP Sepolia and your account

You need two things to deploy: an RPC endpoint for OP Sepolia and a private key to sign the deployment transaction.

<Steps>
  <Step title="Create a deployment account">
    Create a fresh key for this tutorial rather than reusing a key that holds real funds.

    ```bash theme={null}
    cast wallet new
    ```

    This prints an `Address` and a `Private key`.
    Save both somewhere safe.
  </Step>

  <Step title="Set your environment variables">
    Export the OP Sepolia RPC URL and the private key you just created.
    These variables are read by the `forge` and `cast` commands in the rest of the tutorial.

    ```bash theme={null}
    export L2_RPC_URL=https://sepolia.optimism.io
    export PRIVATE_KEY=0x...your-private-key...
    export ACCOUNT_ADDRESS=$(cast wallet address --private-key $PRIVATE_KEY)
    ```
  </Step>
</Steps>

<Info>
  `https://sepolia.optimism.io` is a public, rate-limited endpoint suited to development and testing.
  For a full list of endpoints and production providers, see the [OP Stack RPC directory](/app-developers/reference/rpc-providers).
  For OP Sepolia's chain ID (`11155420`) and other network parameters, see [Connecting to OP Mainnet](/op-mainnet/network-information/connecting-to-op#op-sepolia).
</Info>

## Fund your account

Deploying a contract costs gas, so your account needs testnet ETH on OP Sepolia.

<Steps>
  <Step title="Request testnet ETH">
    Use the [Superchain Faucet](https://console.optimism.io/faucet?utm_source=op-docs\&utm_medium=docs) to send OP Sepolia ETH to your `ACCOUNT_ADDRESS`.
  </Step>
</Steps>

### Verify your balance

Check that the faucet funds have arrived before deploying:

```bash theme={null}
cast balance --ether $ACCOUNT_ADDRESS --rpc-url $L2_RPC_URL
```

The command prints your balance in ETH.
Wait until it's greater than `0` before continuing.

## Deploy the contract

Deploy `Greeter` to OP Sepolia and capture the resulting contract address.

```bash theme={null}
CONTRACT_ADDRESS=$(forge create \
  --rpc-url $L2_RPC_URL \
  --private-key $PRIVATE_KEY \
  Greeter \
  --broadcast \
  | awk '/Deployed to:/ {print $3}')

echo "Deployed to: $CONTRACT_ADDRESS"
```

The `forge create` command compiles (if needed), signs, and broadcasts the deployment transaction.
Its output includes a `Deployed to:` line; the `awk` command extracts that address into the `CONTRACT_ADDRESS` variable so you can reuse it in the next step.

<Info>
  Run `forge create` on its own (without the `awk` pipe) if you want to see the full output — the deployer address, the new contract address, and the transaction hash.
</Info>

### Verify the deployment

Confirm the contract exists on-chain by fetching its bytecode:

```bash theme={null}
cast code $CONTRACT_ADDRESS --rpc-url $L2_RPC_URL
```

A deployed contract returns a long hex string.
If it returns `0x`, the deployment didn't land — re-check your balance and rerun the deploy step.

## Interact with the contract

Now read from and write to your live contract using `cast`.

<Steps>
  <Step title="Read the initial greeting">
    ```bash theme={null}
    cast call --rpc-url $L2_RPC_URL $CONTRACT_ADDRESS "greet()" | cast --to-ascii
    ```

    The greeting starts empty, so this returns an empty string.
  </Step>

  <Step title="Set a new greeting">
    This sends a transaction that calls `setGreeting()`:

    ```bash theme={null}
    cast send \
      --private-key $PRIVATE_KEY \
      --rpc-url $L2_RPC_URL \
      $CONTRACT_ADDRESS \
      "setGreeting(string)" "Hello from OP Sepolia"
    ```
  </Step>

  <Step title="Read the greeting again">
    ```bash theme={null}
    cast call --rpc-url $L2_RPC_URL $CONTRACT_ADDRESS "greet()" | cast --to-ascii
    ```

    This now returns `Hello from OP Sepolia`, confirming your write landed on-chain.
  </Step>
</Steps>

## View your contract on the block explorer

Open an [OP Sepolia block explorer](/app-developers/tools-sdks/block-explorers) and search for your `CONTRACT_ADDRESS` to see the deployment transaction and the `setGreeting` call you just sent.
Publishing (verifying) your contract's source code on the explorer is optional but recommended, because it lets anyone read and interact with the contract from the explorer UI.

## Next steps

* Learn the broader conventions in [Building apps on OP Stack chains](/app-developers/guides/building-apps).
* Understand [the differences between Ethereum and OP Stack chains](/op-stack/protocol/differences).
* Try a cross-chain tutorial next, such as [bridging ERC-20 tokens](/app-developers/tutorials/bridging/cross-dom-bridge-erc20).

<Info>
  **Running your app in production**

  A production application depends on infrastructure your team does not run: RPC endpoints that hold up under real traffic (the public endpoints are rate-limited and not built for production), bridges your users rely on, and a chain whose operator keeps sequencing, upgrades, and incident response going around the clock. These docs cover building and testing. If your application is growing toward dedicated blockspace of its own, [OP Enterprise](https://optimism.io/op-enterprise?utm_source=docs\&utm_medium=docs\&utm_campaign=op-enterprise) offers managed and supported paths to running a chain. These docs stay the reference for what you build either way. OP Enterprise is Optimism's managed offering.
</Info>


# First steps
Source: https://docs.optimism.io/app-developers/tutorials/development/supersim/first-steps

Take your first steps with Supersim.

`supersim` allows testing multichain features **locally**. Previously, testing multichain features required complex docker setups or using a testnet. To see it in practice, this tutorial walks you through sending some ETH from the L1 to the L2.

## Deposit ETH from the L1 into the L2 (L1 to L2 message passing)

<Steps>
  <Step title="Check initial balance on the L2 (chain 901)">
    Grab the balance of the sender account on L2:

    ```sh theme={null}
    cast balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9545
    ```
  </Step>

  <Step title="Send the Ether">
    You can use two different methods to complete this action: `OptimismPortal` or `L1StandardBridge`.

    #### First method: `OptimismPortal`

    * Send the Ether to `OptimismPortal` contract of the respective L2 (on chain 900)

    <Info>
      For chain 901, the contract is `0x37a418800d0c812A9dE83Bc80e993A6b76511B57`.
    </Info>

    * Initiate a bridge transaction on the L1:

    ```sh theme={null}
    cast send 0x37a418800d0c812A9dE83Bc80e993A6b76511B57 --value 0.1ether --rpc-url http://127.0.0.1:8545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
    ```

    #### Second method: `L1StandardBridge`

    * Call `bridgeETH` function on the `L1StandardBridgeProxy` / `L1StandardBridge` contract of the respective L2 on L1 (chain 900)

    <Info>
      For chain 901, the contract is `0x8d515eb0e5F293B16B6bBCA8275c060bAe0056B0`.
    </Info>

    * Initiate a bridge transaction on the L1:

    ```sh theme={null}
    cast send 0x8d515eb0e5F293B16B6bBCA8275c060bAe0056B0 "bridgeETH(uint32 _minGasLimit, bytes calldata _extraData)" 50000 0x --value 0.1ether --rpc-url http://127.0.0.1:8545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
    ```
  </Step>

  <Step title="Check the balance on the L2 (chain 901)">
    Verify that the ETH balance of the sender has increased on the L2:

    ```sh theme={null}
    cast balance 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9545
    ```
  </Step>
</Steps>

## Send an interoperable ERC20 token from chain 901 to 902 (L2 to L2 message passing)

In a typical L2 to L2 cross-chain transfer, two transactions are required:

1. Send transaction on the source chain – This initiates the token transfer on Chain 901.
2. Relay message transaction on the destination chain – This relays the transfer details to Chain 902.

To simplify this process, you can use the `--interop.autorelay` flag. This flag automatically triggers the relay message transaction once the initial send transaction is completed on the source chain, improving the developer experience by removing the need to manually send the relay message.

<Steps>
  <Step title="Start `supersim` with the autorelayer enabled">
    ```sh theme={null}
      supersim --interop.autorelay 
    ```
  </Step>

  <Step title="Mint tokens to transfer on chain 901">
    Run the following command to mint 1000 test ERC20 tokens to the recipient address:

    ```sh theme={null}
    cast send 0x420beeF000000000000000000000000000000001 "mint(address _to, uint256 _amount)"  0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1000  --rpc-url http://127.0.0.1:9545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

    ```
  </Step>

  <Step title="Initiate the send transaction on chain 901">
    Send the tokens from Chain 901 to Chain 902 using the following command:

    ```sh theme={null}
    cast send 0x4200000000000000000000000000000000000028 "sendERC20(address _token, address _to, uint256 _amount, uint256 _chainId)" 0x420beeF000000000000000000000000000000001 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 1000 902 --rpc-url http://127.0.0.1:9545 --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
    ```
  </Step>

  <Step title="Wait for the relayed message to appear on chain 902">
    In a few seconds, you should see the RelayedMessage on chain 902:

    ```sh theme={null}
    # example
    INFO [08-30|14:30:14.698] SuperchainTokenBridge#RelayERC20 token=0x420beeF000000000000000000000000000000001 from=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 to=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 amount=1000 source=901
    ```
  </Step>

  <Step title="Check the balance on chain 902">
    Verify that the balance of the test ERC20 on chain 902 has increased:

    ```sh theme={null}
    cast balance --erc20 0x420beeF000000000000000000000000000000001 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266 --rpc-url http://127.0.0.1:9546
    ```
  </Step>
</Steps>

With the steps above, you've now successfully completed both an L1 to L2 ETH bridge and an L2 to L2 interoperable ERC20 token transfer, all done locally using `supersim`. This approach simplifies multichain testing, allowing you to focus on development without the need for complex setups or relying on external testnets.

## Next steps

* Learn how to start Supersim in [vanilla (non-forked) mode](/app-developers/reference/tools/supersim/vanilla) or [forked mode](/app-developers/reference/tools/supersim/fork).
* Explore the Supersim [included contracts](/app-developers/reference/tools/supersim/included-contracts) being used to help replicate the OP Stack environment.


# Install Supersim
Source: https://docs.optimism.io/app-developers/tutorials/development/supersim/installation

Learn how to install Supersim and start it in vanilla mode.

This page provides installation instructions for `supersim`.

<Steps>
  <Step title="Prerequisites: foundry">
    `supersim` requires `anvil`, which is installed alongside the Foundry toolchain.

    Follow the [Foundry toolchain](https://book.getfoundry.sh/getting-started/installation) guide for detailed instructions.
  </Step>

  <Step title="Install supersim">
    Either download precompiled binaries or install using Homebrew:

    * Precompiled binaries: Download the executable for your platform from the [GitHub releases page](https://github.com/ethereum-optimism/supersim/releases).

    * Homebrew: Install [Homebrew](https://brew.sh/) (OS X, Linux), and then run:

    ```sh theme={null}
    brew tap ethereum-optimism/tap
    brew install supersim
    ```
  </Step>

  <Step title="Start supersim in vanilla mode">
    Start `supersim` in vanilla mode by running:

    ```sh theme={null}
    supersim
    ```

    Vanilla mode will start 3 chains, with the OP Stack contracts already deployed.

    * (1) L1 Chain
      * Chain 900
    * (2) L2 Chains
      * Chain 901
      * Chain 902
  </Step>
</Steps>

## Next steps

* Continue to the [First Steps](/app-developers/tutorials/development/supersim/first-steps) tutorial to try L1 to L2 message passing.
* Explore [Supersim](/app-developers/tools-sdks/supersim) features, particularly in [vanilla mode](/app-developers/reference/tools/supersim/vanilla), which starts 3 chains (L1 and L2).


# Making crosschain contract calls (ping pong)
Source: https://docs.optimism.io/app-developers/tutorials/interoperability/contract-calls

Understand how the CrossChainPingPong example contract uses the L2ToL2CrossDomainMessenger to make crosschain contract calls, and the design choices behind it.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>
This page explains the design of the `CrossChainPingPong.sol` example contract and how it integrates the `L2ToL2CrossDomainMessenger` to make crosschain contract calls. For more info, view the [source code](https://github.com/ethereum-optimism/supersim/blob/main/contracts/src/pingpong/CrossChainPingPong.sol).

## High level overview

`CrossChainPingPong.sol` implements a cross-chain ping-pong game using the `L2ToL2CrossDomainMessenger`.

* Players hit a **virtual ball** back and forth between allowed L2 chains. The game starts with a serve
* from a designated start chain, and each hit increases the rally count. The contract tracks the last hitter's address, chain ID, and the current rally count.

### Diagram

```mermaid theme={null}
sequenceDiagram
    participant Chain1 as Chain 1
    participant Chain2 as Chain 2
    
    Note over Chain1: 🚀 Game Starts (starting chain)
    Note over Chain1: 🏓 Hit Ball
    Chain1->>Chain2: 📤 Send PingPongBall {rallyCount: 1, lastHitter: Chain1}
    Chain1-->>Chain1: Emit BallSent event
    activate Chain2
    Note over Chain2: 📥 Receive Ball
        Chain2-->>Chain2: Emit BallReceived event

    Note over Chain2: 🏓 Hit Ball
    Chain2->>Chain1: 📤 Send PingPongBall {rallyCount: 2, lastHitter: Chain2}
    Chain2-->>Chain2: Emit BallSent event
    deactivate Chain2
    activate Chain1
    Note over Chain1: 📥 Receive Ball
        Chain1-->>Chain1: Emit BallReceived event

    Note over Chain1,Chain2: Game continues...
```

### Flow

<Steps>
  <Step title="Contract Deployment">
    * Deployed on all participating chains
    * Utilizes CREATE2 with the same parameter, `_serverChainId`, resulting in the same address and initial state.
  </Step>

  <Step title="Hit the Ball (Starting Move)">
    * Call `hitBallTo` on the chain with the ball, specifying a destination chain.
    * Contract uses `L2ToL2CrossDomainMessenger` to send the ball data to the specified chain.
    * The reference to the ball is deleted from the serving chain.
  </Step>

  <Step title="Receive on Destination Chain">
    * `L2ToL2CrossDomainMessenger` on destination chain calls `receiveBall`.
    * Contract verifies the message sender and origin.
    * Ball data is stored, indicating its presence on this chain.
  </Step>

  <Step title="Continue Game (Hit)">
    * Any user on the chain currently holding the ball calls `hitBallTo` to send it to another chain.
    * Contract updates the `PingPongBall` data (increment rally count, update last hitter).
    * Process repeats from step 2.
  </Step>
</Steps>

## Walkthrough

Here's an explanation of the functions in the contract, with a focus on how it interacts with `L2ToL2CrossChainMessenger`.

### Initialize contract state

#### Constructor Setup

```solidity theme={null}
constructor(uint256 _serverChainId) {
    if (block.chainid == _serverChainId) {
        ball = PingPongBall(1, block.chainid, msg.sender);
    }
}
```

If the starting chain, initialize the ball allowing it to be hittable.

#### Reliance on CREATE2 for cross chain consistency

While not explicitly mentioned in the code, this contract's design implicitly assumes the use of CREATE2 for deployment. Here's why CREATE2 is crucial for this setup:

* **Predictable Addresses**:
  CREATE2 enables deployment at the same address on all chains, crucial for cross-chain message verification:
  ```solidity theme={null}
  if (messenger.crossDomainMessageSender() != address(this)) revert InvalidCrossDomainSender();
  ```

* **Self-referential Messaging**:
  The contract sends messages to itself on other chains:
  ```solidity theme={null}
  messenger.sendMessage(_toChainId, address(this), _message);
  ```
  This requires `address(this)` to be consistent across chains.

* **Initialization State Considerations**:

  The starting chain id is part of the initcode, meaning a deployment with a differing value would result in a different address via CREATE2. This is a nice feature as there's an implicit agreement on the starting chain from the address.

  Without CREATE2, you would need to:

  * Manually track contract addresses for each chain.
  * Implement a more complex initialization process to register contract addresses across chains.
  * Potentially redesign the security model that relies on address matching.

### Hit the ball

`hitBallTo`: This function is used to hit the ball, when present, to another chain

#### Hitting constraints

```solidity theme={null}
function hitBallTo(uint256 _toChainId) public {
    if (ball.lastHitterAddress == address(0)) revert BallNotPresent();
    if (_toChainId == block.chainid) revert InvalidDestination();
    ...
}
```

* The `ball` contract variable is populated on the chain, indicating its presence
* The destination must be a different chain

### Define receiving handler

```solidity theme={null}
modifier onlyCrossDomainCallback() {
    if (msg.sender != address(messenger)) revert CallerNotL2ToL2CrossDomainMessenger();
    if (messenger.crossDomainMessageSender() != address(this)) revert InvalidCrossDomainSender();

    _;
}

function receiveBall(PingPongBall memory _ball) onlyCrossDomainCallback() external {
    // Hold reference to the ball
    ball = _ball;

    emit BallReceived(messenger.crossDomainMessageSource(), block.chainid, _ball);
}
```

* The handler simply stores reference to the received ball
* The handler can only be invocable by the cross chain messenger
* Since the contract is self-referential, the cross chain sender must be the same contract address

### Hit the ball cross-chain

```solidity theme={null}
function hitBallTo(uint256 _toChainId) public {
    ...

    // Construct a new ball
    PingPongBall memory newBall = PingPongBall(ball.rallyCount + 1, block.chainid, msg.sender);

    // Delete current reference
    delete ball;

    // Send to the destination
    messenger.sendMessage(_toChainId, address(this), abi.encodeCall(this.receiveBall, (newBall)));

    emit BallSent(block.chainid, _toChainId, newBall);
}
```

* Populate a new ball with updated properties
* Delete reference to the current ball so it's no longer hittable
* Invoke the contract on the destination chain matching the `receiveBall` handler defined in (2).

## Takeaways

This is just one of many patterns to use the `L2ToL2CrossDomainMessenger` in your contract to power cross chain calls. Key points to remember:

* **Simple Message Passing**: This design sends simple messages between identical contracts on different chains. Each message contains only the essential game state (rally count, last hitter). More complex systems might involve multiple contracts, intermediary relayers.

* **Cross Chain Sender Verification**: Always verify the sender of cross-chain messages. This includes checking both the immediate caller (the messenger) and the original sender on the source chain.

* **Cross Chain Contract Coordination**: This design uses CREATE2 for consistent contract addresses across chains, simplifying cross-chain verification. Alternative approaches include:
  * Beacon proxy patterns for upgradeable contracts
  * Post-deployment setup where contract addresses are specified after deployment


# Deploying crosschain event composability (contests)
Source: https://docs.optimism.io/app-developers/tutorials/interoperability/event-contests

Understand how the Contests example composes with cross-chain events, using the CrossL2Inbox to consume events emitted by contracts on any OP Stack chain.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>
We showcase cross chain composability through the implementation of contests. Leveraging the same underlying mechanism powering [TicTacToe](/app-developers/tutorials/interoperability/event-reads), these contests can permissionlessly integrate with the events emitted by any contract on OP Stack chains.

<Info>
  See the [frontend documentation](https://github.com/ethereum-optimism/supersim/tree/main/examples/contests) for how the contests UI is presented to the user.
</Info>

## How it works

Unlike [TicTacToe](/app-developers/tutorials/interoperability/event-reads) which is deployed on every participating chain, the contests are deployed on a single L2, behaving like an application-specific OP Stack chain rather than a horizontally scaled app.

<Steps>
  <Step title="Implement contests">
    [Contests.sol](https://github.com/ethereum-optimism/supersim/blob/main/contracts/src/contests/Contests.sol) contains the implementation of the contests. We won't go into the details of the implementation here, but instead focus on how the contests can leverage cross chain event reading to compose with other contracts on OP Stack chains.
  </Step>

  <Step title="Read cross-chain events">
    The system predeploy that enables pulling in validated cross-chain events is the [CrossL2Inbox](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#crossl2inbox).

    ```solidity theme={null}
    contract ICrossL2Inbox {
        function validateMessage(Identifier calldata _id, bytes32 _msgHash) external view;
    }
    ```
  </Step>

  <Step title="Create the contest">
    The two contest options are detailed below: [BlockHash contest](#blockhash-contest) and [TicTacToe contest](#tictactoe-contest).

    #### BlockHash contest

    With the existence of an event that emits the blockhash and height of a block, we can create a contest on the parity of the blockhash being even or odd.

    ```solidity theme={null}
    contract BlockHashEmitter {
        event BlockHash(uint256 blockHeight, bytes32 blockHash);

        function emitBlockHash(uint256 _blockHeight) external {
            bytes32 hash = blockhash(_blockHeight);
            require(hash != bytes32(0));

            emit BlockHash(_blockHeight, hash);
        }
    }
    ```

    Integrating this emitter into a contest is extremely simple.  The `BlockHashContestFactory` is a simple factory that creates a new contest for a given chain and block height.

    #### TicTacToe contest

    A contest for TicTacToe is created on an accepted game between two players, captured by the emitted `AcceptedGame` event. When decoding the event, the game is uniquely identified by the chain it was created on, `chainId`, and the associated `gameId`. These identifying properties of the game are used to create the resolver for the game.

    ```solidity theme={null}
    contract TicTacToeContestFactory {
        Contests  public contests;
        TicTacToe public tictactoe;

        function newContest(Identifier calldata _id, bytes calldata _data) public payable {
            // Validate Log
            require(_id.origin == address(tictactoe), "not an event from the TicTacToe contract");
            CrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(_id, keccak256(_data));

            bytes32 selector = abi.decode(_data[:32], (bytes32));
            require(selector == TicTacToe.AcceptedGame.selector, "incorrect event");

            // Decode the event data
            (uint256 chainId, uint256 gameId, address creator,) = abi.decode(_data[32:], (uint256, uint256, address, address));

            IContestResolver resolver = new TicTacToeGameResolver(contests, tictactoe, chainId, gameId, creator);
            contests.newContest{ value: msg.value }(resolver, msg.sender);
        }
    }
    ```
  </Step>

  <Step title="Resolve contest">
    A contest is identified by and has its outcome determined by the `IContestResolver` instance. The resolver starts in the `UNDECIDED` state, updated into `YES` or `NO` when resolving itself
    with the contest.

    ```solidity theme={null}
    enum ContestOutcome {
        UNDECIDED,
        YES,
        NO
    }

    interface IContestResolver {
        function outcome() external returns (ContestOutcome);
    }
    ```

    #### Resolve BlockHash contest

    When live, **anyone** can resolve the BlockHash contest by simply providing the right `BlockHash` event to the deployed resolver.

    ```solidity theme={null}
    contract BlockHashContestFactory {
        Contests         public contests;
        BlockHashEmitter public emitter; // Same emitter deployed on every chain

        function newContest(uint256 _chainId, uint256 _blockNumber) public payable {
            IContestResolver resolver = new BlockHashResolver(contests, emitter, _chainId, _blockNumber);
            contests.newContest{ value: msg.value }(resolver, msg.sender);
        }
    }

    contract BlockHashResolver is IContestResolver {
        Contests         public contests;
        ContestOutcome   public outcome;
        BlockHashEmitter public emitter;

        // The target chain & block height
        uint256 public chainId;
        uint256 public blockNumber;

        function resolve(Identifier calldata _id, bytes calldata _data) external {
            require(outcome == ContestOutcome.UNDECIDED);

            // Validate Log
            require(_id.origin == address(emitter), "not an event from the emitter");
            require(_id.chainId == chainId, "must match target chain");
            CrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(_id, keccak256(_data));

            bytes32 selector = abi.decode(_data[:32], (bytes32));
            require(selector == BlockHashEmitter.BlockHash.selector, "incorrect event");

            // Event should correspond to the right contest
            uint256 dataBlockNumber = abi.decode(_data[32:64], (uint256));
            require(dataBlockNumber == blockNumber, "must match target block height");

            // Resolve the contest (yes if odd, no if even)
            bytes32 blockHash = abi.decode(_data[64:], (bytes32));
            outcome = uint256(blockHash) % 2 != 0 ? ContestOutcome.YES : ContestOutcome.NO;
            contests.resolveContest(this);
        }

    }
    ```

    #### Resolve TicTacToe contest

    When live, **anyone** can resolve the TicTacToe contest by providing the `GameWon` or `GameDraw` event of the associated game from the TicTacToe contract.

    ```solidity theme={null}
    contract TicTacToeGameResolver is IContestResolver {
        Contests       public contests;
        ContestOutcome public outcome;
        TicTacToe      public tictactoe;

        // @notice Game for this resolver
        Game public game;

        constructor(Contests _contest, TicTacToe _tictactoe, uint256 _chainId, uint256 _gameId, address _creator) {
            contests = _contest;
            tictactoe = _tictactoe;

            game = Game({chainId: _chainId, gameId: _gameId, creator: _creator});
            outcome = ContestOutcome.UNDECIDED;
        }

        // @notice resolve this game by providing the game ending event
        function resolve(Identifier calldata _id, bytes calldata _data) external {
            // Validate Log
            require(_id.origin == address(tictactoe));
            CrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(_id, keccak256(_data));

            // Ensure this is a finalizing event
            bytes32 selector = abi.decode(_data[:32], (bytes32));
            require(selector == TicTacToe.GameWon.selector || selector == TicTacToe.GameDraw.selector, "event not a game outcome");

            // Event should correspond to the right game
            (uint256 _chainId, uint256 gameId, address winner,,) = abi.decode(_data[32:], (uint256, uint256, address, uint8, uint8));
            require(_chainId == game.chainId && gameId == game.gameId);

            // Resolve based on if the creator has won (non-draw)
            outcome = winner == game.creator && selector != TicTacToe.GameDraw.selector ? ContestOutcome.YES : ContestOutcome.NO;
            contests.resolveContest(this);
        }
    }
    ```
  </Step>
</Steps>

## Takeaways

* Leveraging superchain interop, contracts in the superchain can compose with each other in a similar fashion to how they would on a single chain. No restrictions are placed on the kinds of events a contract can consume via the `CrossL2Inbox`.
* In this example, the `BlockHashContestFactory` and `TicTacToeContestFactory` can be seen as just starting points for the `Contests` app chain. As more contracts and apps are created in the superchain, developers can compose with them in a similar fashion without needing to change the `Contests` contract at all.


# Making cross-chain event reads (tic-tac-toe)
Source: https://docs.optimism.io/app-developers/tutorials/interoperability/event-reads

Understand how a horizontally scalable TicTacToe implementation uses CrossL2Inbox event reads to coordinate gameplay across interop chains.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>
This page explains a horizontally scalable implementation of TicTacToe. This [implementation](https://github.com/ethereum-optimism/supersim/blob/main/contracts/src/tictactoe/TicTacToe.sol) allows players to play each other from any chain without cross-chain calls, instead relying on cross-chain event reading. Since OP Stack interop can allow for event reading with a 1-block latency, the experience is the **same as a single-chain implementation**.

<Info>
  Check out the [frontend documentation](https://github.com/ethereum-optimism/supersim/tree/main/examples/tictactoe) to see how the game UI is presented to the player.
</Info>

## How it works

We use events to define the ordering of a game with players only maintaining a local view. By default, a chain is also a part of its own interoperable dependency set, which means players on the same chain can also play each other **with no code changes**!

The system predeploy that enables pulling in validated cross-chain events is the [CrossL2Inbox](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#crossl2inbox).

```solidity theme={null}
contract ICrossL2Inbox {
    function validateMessage(Identifier calldata _id, bytes32 _msgHash) external view;
}
```

This contract relies on a **CREATE2** deployment to ensure a consistent address across all chains, used to assert the origin of the pulled in game event.

<Steps>
  <Step title="Intent to play">
    A game is uniquely identified by the chain it was started from with a unique nonce. This identifier is included in all event fields such that each player can uniquely reference it locally.

    To start a game, a player invokes `newGame` which broadcasts a `NewGame` event that any opponent **on any chain** can react to.

    ```solidity theme={null}
    event NewGame(uint256 chainId, uint256 gameId, address player);

    function newGame() external {
        emit NewGame(block.chainid, nextGameId, msg.sender);
        nextGameId++;
    }
    ```
  </Step>

  <Step title="Accepting a game">
    When a `NewGame` event is observed, any player can declare their intent to play via `acceptGame`, referencing the `NewGame` event. An `AcceptedGame` event is emitted to signal to the creator that a game is ready to begin.

    ```solidity theme={null}
    event AcceptedGame(uint256 chainId, uint256 gameId, address opponent, address player);

    function acceptGame(ICrossL2Inbox.Identifier calldata _newGameId, bytes calldata _newGameData) external {
        if (_newGameId.origin != address(this)) revert IdOriginNotTicTacToe();
        ICrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(_newGameId, keccak256(_newGameData));

        bytes32 selector = abi.decode(_newGameData[:32], (bytes32));
        if (selector != NewGame.selector) revert DataNotNewGame();

        ...

        emit AcceptedGame(chainId, gameId, game.opponent, game.player);
    }
    ```

    To prepare for the game, the event data is decoded and a local view of this game is stored.

    ```solidity theme={null}
    (uint256 chainId, uint256 gameId, address opponent) = abi.decode(_newGameData[32:], (uint256, uint256, address));
    if (opponent == msg.sender) revert SenderIsOpponent();

    // Record Game Metadata (no moves)
    Game storage game = games[chainId][gameId][msg.sender];
    game.player = msg.sender;
    game.opponent = opponent;
    game.gameId = gameId;
    game.lastOpponentId = _newGameId;
    game.movesLeft = 9;

    emit AcceptedGame(chainId, gameId, game.opponent, game.player);
    ```
  </Step>

  <Step title="Starting the game">
    As `AcceptedGame` events are emitted, the player must pick one opponent to play. The opponent's `AcceptedGame` event is used to instantiate the game and play the starting move via the `MovePlayed` event.

    ```solidity theme={null}
    event MovePlayed(uint256 chainId, uint256 gameId, address player, uint8 _x, uint8 _y);

    function startGame(ICrossL2Inbox.Identifier calldata _acceptedGameId, bytes calldata _acceptedGameData, uint8 _x, uint8 _y) external {
        if (_acceptedGameId.origin != address(this)) revert IdOriginNotTicTacToe();
        ICrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(_acceptedGameId, keccak256(_acceptedGameData));

        bytes32 selector = abi.decode(_acceptedGameData[:32], (bytes32));
        if (selector != AcceptedGame.selector) revert DataNotAcceptedGame();

        ...

        emit MovePlayed(chainId, gameId, game.player, _x, _y);
    ```

    The event fields contain the information required to perform the necessary validation.

    * The game identifier for lookup
    * The caller is the appropriate player
    * The player is accepting from the same starting chain

    ```solidity theme={null}
    (uint256 chainId, uint256 gameId, address player, address opponent) = // player, opponent swapped in local view
        abi.decode(_acceptedGameData[32:], (uint256, uint256, address, address));

    // The accepted game was started from this chain, from the sender
    if (chainId != block.chainid) revert GameChainMismatch();
    if (msg.sender != player) revert SenderNotPlayer();

    // Game has not already been started with an opponent.
    Game storage game = games[chainId][gameId][msg.sender];
    if (game.opponent != address(0)) revert GameStarted();

    // Store local view of this game
    ...

    // Locally record the move by the player with 1
    game.moves[_x][_y] = 1;
    game.lastOpponentId = _acceptedGameId;

    emit MovePlayed(chainId, gameId, game.player, _x, _y);
    ```
  </Step>

  <Step title="Making moves">
    Once a game is started, players can continually make moves by invoking `makeMove`, reacting to a `MovePlayed` event of their opponent.

    ```solidity theme={null}
    function makeMove(ICrossL2Inbox.Identifier calldata _movePlayedId, bytes calldata _movePlayedData, uint8 _x, uint8 _y) external {
        if (_movePlayedId.origin != address(this)) revert IdOriginNotTicTacToe();
        ICrossL2Inbox(Predeploys.CROSS_L2_INBOX).validateMessage(_movePlayedId, keccak256(_movePlayedData));

        bytes32 selector = abi.decode(_movePlayedData[:32], (bytes32));
        if (selector != MovePlayed.selector) revert DataNotMovePlayed();
    }
    ```

    Similar to `acceptGame`, validation is performed and the move of their opponent is first locally recorded.

    * The game identifier for lookup
    * The caller is the player for this game
    * The opponent event corresponds to the same game
    * Ordering is enforced by ensuring that the supplied event is always forward progressing.

    ```solidity theme={null}
    (uint256 chainId, uint256 gameId,, uint8 oppX, uint8 oppY) = abi.decode(_movePlayedData[32:], (uint256, uint256, address, uint8, uint8));

    // Game was instantiated for this player & the move is for the same game
    Game storage game = games[chainId][gameId][msg.sender];
    if (game.player != msg.sender) revert GameNotExists();
    if (game.gameId != gameId) revert GameNotExists();

    // The move played event is forward progressing from the last observed event
    if (_movePlayedId.chainId != game.lastOpponentId.chainId) revert IdChainMismatch();
    if (_movePlayedId.blockNumber <= game.lastOpponentId.blockNumber) revert MoveNotForwardProgressing();
    game.lastOpponentId = _movePlayedId;

    // Mark the opponents move
    game.moves[oppX][oppY] = 2;
    game.movesLeft--;
    ```

    When a move is played we check if the game has been drawn or won, determining the subsequent event to emit.

    The `makeMove` function is only callable when an opponent has a new `MovePlayed` event. Therefore, if the game is won or drawn, it cannot be progressed any further by the opponent.

    ```solidity theme={null}
    // Make the players move
    game.moves[_x][_y] = 1;
    game.movesLeft--;

    // Determine the status of the game
    if (_isGameWon(game)) {
        emit GameWon(chainId, gameId, game.player, _x, _y);
    } else if (game.movesLeft == 0) {
        emit GameDraw(chainId, gameId, game.player, _x, _y);
    } else {
        emit MovePlayed(chainId, gameId, game.player, _x, _y);
    }
    ```
  </Step>
</Steps>

## Takeaways

Leveraging superchain interop, we can build new types of horizontally scalable contracts that do not rely on hub/spoke messaging with relayers.

* As new chains are added to the superchain, this contract can be installed by anyone and immediately playable with no necessary code changes. The frontend simply needs to react the addition of a new chain.
* The concept of a "chain" can be completely abstracted away from the user. When connecting their wallet, the frontend can simply pick the chain which the user has funds on with the lowest gas fees.
* Event reading enables a new level of composability for cross-chain interactions. Imagine [contests](/app-developers/tutorials/interoperability/event-contests) contract that resolves based on the outcome of a TicTacToe game via the `GameWon` or `GameLost` event without the need for a trusted oracle, nor permission or native integration with the TicTacToe contract.


# Relay transactions manually
Source: https://docs.optimism.io/app-developers/tutorials/interoperability/manual-relay

Learn to relay transactions directly by sending the correct transaction.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

<Note>Messages are relayed automatically in the interop devnet.</Note>

## Overview

Learn to relay transactions directly by sending the correct transaction.

<Expandable title="About this tutorial">
  **Prerequisite technical knowledge**

  * Familiarity with blockchain concepts
  * Familiarity with [Foundry](https://book.getfoundry.sh/getting-started/installation), especially `cast`

  **What you'll learn**

  * How to use `cast` to relay transactions when autorelay does not work
  * How to relay transactions using JavaScript

  **Development environment requirements**

  * Unix-like operating system (Linux, macOS, or WSL for Windows)
  * Node.js version 16 or higher
  * Git for version control
  * Supersim environment configured and running
  * Foundry tools installed (forge, cast, anvil)
</Expandable>

### What you'll build

* A program to relay messages using [the JavaScript library](https://www.npmjs.com/package/@eth-optimism/viem)
* A shell script to relay messages using [`cast`](https://book.getfoundry.sh/cast/)

## Setup

These steps are necessary to run the tutorial, regardless of whether you are using `cast` or the JavaScript API.

<Steps>
  <Step title="Run Supersim">
    This exercise needs to be done on Supersim.\
    You cannot use the devnets because you cannot disable autorelay on them.

    1. Follow [Install Supersim](/app-developers/tutorials/development/supersim/installation).
    2. Run Supersim *without* `--interop.relay`.

    ```sh theme={null}
    ./supersim
    ```
  </Step>

  <Step title="Create the state for relaying messages">
    The results of this step are similar to what the [message passing tutorial](/app-developers/tutorials/interoperability/message-passing) would produce if you did not have autorelay on.

    Execute this script:

    ```sh theme={null}
    #! /bin/sh
    # full shell script preserved here...
    # (Greeter.sol, GreetingSender.sol, sendAndRelay.sh setup)
    # ...
    ```

    This script installs `Greeter.sol` on chain B and `GreetingSender.sol` on chain A.\
    These smart contracts let us send a message from chain A that needs to be relayed to chain B.

    Then, the script creates `./manual-relay/sendAndRelay.sh` to manually relay a message from chain A to chain B.\
    That script is [explained below](#manual-relay-using-cast).

    Finally, this script writes out some parameter setting lines that should be executed on the main shell before you continue.\
    With a fresh Supersim running, these should be:

    ```sh theme={null}
    GREETER_A_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
    GREETER_B_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
    PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
    ```
  </Step>
</Steps>

## Manual relay using the API

<Steps>
  <Step title="Setup">
    Use a [Node](https://nodejs.org/en) project.

    1. Initialize a new Node project.

    ```sh theme={null}
    mkdir -p manual-relay/offchain
    cd manual-relay/offchain
    npm init -y
    npm install --save-dev viem @eth-optimism/viem
    mkdir src
    ```

    2. Export environment variables:

    ```sh theme={null}
    export GREETER_A_ADDRESS GREETER_B_ADDRESS PRIVATE_KEY
    ```
  </Step>

  <Step title="Manual relaying app">
    Create a file `manual-relay.mjs` with:

    ```javascript theme={null}
        import {
        createWalletClient,
        http,
        publicActions,
        getContract,
    } from 'viem'
    import { privateKeyToAccount } from 'viem/accounts'
    import { supersimL2A, supersimL2B } from '@eth-optimism/viem/chains' 
    import { walletActionsL2, publicActionsL2 } from '@eth-optimism/viem'

    import { readFileSync } from 'fs';

    const greeterData = JSON.parse(readFileSync('../onchain/out/Greeter.sol/Greeter.json'))
    const greetingSenderData = JSON.parse(readFileSync('../onchain/out/Greeter.sol/Greeter.json'))

    const account = privateKeyToAccount(process.env.PRIVATE_KEY)

    const walletA = createWalletClient({
        chain: supersimL2A,
        transport: http(),
        account
    }).extend(publicActions)
        .extend(publicActionsL2())
    //    .extend(walletActionsL2())

    const walletB = createWalletClient({
        chain: supersimL2B,
        transport: http(),
        account
    }).extend(publicActions)
    //    .extend(publicActionsL2())
        .extend(walletActionsL2())

    const greeter = getContract({
        address: process.env.GREETER_B_ADDRESS,
        abi: greeterData.abi,
        client: walletB
    })

    const greetingSender = getContract({
        address: process.env.GREETER_A_ADDRESS,
        abi: greetingSenderData.abi,
        client: walletA
    })

    const txnBHash = await greeter.write.setGreeting(
        ["Greeting directly to chain B"])
    await walletB.waitForTransactionReceipt({hash: txnBHash})

    const greeting1 = await greeter.read.greet()
    console.log(`Chain B Greeting: ${greeting1}`)

    const txnAHash = await greetingSender.write.setGreeting(
        ["Greeting through chain A"])
    const receiptA = await walletA.waitForTransactionReceipt({hash: txnAHash})

    const greeting2 = await greeter.read.greet()
    console.log(`Greeting before the relay transaction: ${greeting2}`)

    const sentMessages = await walletA.interop.getCrossDomainMessages({
      logs: receiptA.logs,
    })
    const sentMessage = sentMessages[0] // We only sent 1 message
    const relayMessageParams = await walletA.interop.buildExecutingMessage({
      log: sentMessage.log,
    })
    const relayMsgTxnHash = await walletB.interop.relayCrossDomainMessage(relayMessageParams)

    const receiptRelay = await walletB.waitForTransactionReceipt({
      hash: relayMsgTxnHash,
    })

    const greeting3 = await greeter.read.greet()
    console.log(`Greeting after the relay transaction: ${greeting3}`)
    ```

    <Expandable title="Explanation">
      ```javascript theme={null}
      import { supersimL2A, supersimL2B } from '@eth-optimism/viem/chains' 
      import { walletActionsL2, publicActionsL2 } from '@eth-optimism/viem'
      ```
    </Expandable>

    Run JavaScript program:

    ```sh theme={null}
    node manual-relay.mjs
    ```
  </Step>

  <Step title="Debugging">
    To see what messages were relayed by a specific transaction:

    ```javascript theme={null}
    import { decodeRelayedL2ToL2Messages } from '@eth-optimism/viem'

    const decodedRelays = decodeRelayedL2ToL2Messages({ receipt: receiptRelay })

    console.log(decodedRelays)
    console.log(decodedRelays.successfulMessages[0].log)
    ```
  </Step>
</Steps>

## Manual relay using `cast`

You can see an example of how to manually relay using `cast` in `manual-relay/sendAndRelay.sh`.\
It is somewhat complicated, so the setup creates one that is tailored to your environment.

Run the script:

```sh theme={null}
./manual-relay/sendAndRelay.sh
```

Here is the detailed explanation:

1. Configuration parameters

   ```sh theme={null}
   #! /bin/sh
   PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
   USER_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
   URL_CHAIN_A=http://localhost:9545
   URL_CHAIN_B=http://localhost:9546
   GREETER_A_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
   GREETER_B_ADDRESS=0x5FbDB2315678afecb367f032d93F642f64180aa3
   CHAIN_ID_B=902
   ```

   This is the configuration.
   The greeter addresses are identical because the nonce for the user address has an identical nonce on both chains.

2. Send a message that needs to be relayed

   ```sh theme={null}
   cast send -q --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_A $GREETER_A_ADDRESS "setGreeting(string)" "Hello from chain A $$"
   ```

   Send a message from chain A to chain B. The `$$` is the process ID, so if you rerun the script you'll see that the information changes.

3. Find the log entry to relay

   ```sh theme={null}
   cast logs "SentMessage(uint256,address,uint256,address,bytes)" --rpc-url $URL_CHAIN_A | tail -14 > log-entry
   ```

   Whenever `L2ToL2CrossDomainMessenger` sends a message to a different blockchain, it emits a [`SendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L83-L91) event.
   Extract only the latest `SendMessage` event from the logs.

   <Expandable title="Example `log-entry`">
     ```yaml theme={null}
     - address: 0x4200000000000000000000000000000000000023
       blockHash: 0xcd0be97ffb41694faf3a172ac612a23f224afc1bfecd7cb737a7a464cf5d133e
       blockNumber: 426
       data: 0x0000000000000000000000005fbdb2315678afecb367f032d93f642f64180aa300000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000064a41368620000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000000000000000001948656c6c6f2066726f6d20636861696e2041203131333030370000000000000000000000000000000000000000000000000000000000000000000000
       logIndex: 0
       removed: false
       topics: [
               0x382409ac69001e11931a28435afef442cbfd20d9891907e8fa373ba7d351f320
               0x0000000000000000000000000000000000000000000000000000000000000386
               0x0000000000000000000000005fbdb2315678afecb367f032d93f642f64180aa3
               0x0000000000000000000000000000000000000000000000000000000000000000
       ]
       transactionHash: 0x1d6f2e5e2c8f3eb055e95741380ca36492f784b9782848b66b66c65c5937ff3a
       transactionIndex: 0
     ```
   </Expandable>

4. Manipulate the log entry to obtain information

   ```sh theme={null}
   TOPICS=`cat log-entry | grep -A4 topics | awk '{print $1}' | tail -4 | sed 's/0x//'`
   TOPICS=`echo $TOPICS | sed 's/ //g'`
   ```

   Consolidate the log topics into a single hex string.

   ```sh theme={null}
   ORIGIN=0x4200000000000000000000000000000000000023
   BLOCK_NUMBER=`cat log-entry | awk '/blockNumber/ {print $2}'`
   LOG_INDEX=`cat log-entry | awk '/logIndex/ {print $2}'`
   TIMESTAMP=`cast block $BLOCK_NUMBER --rpc-url $URL_CHAIN_A | awk '/timestamp/ {print $2}'`
   CHAIN_ID_A=`cast chain-id --rpc-url $URL_CHAIN_A`
   SENT_MESSAGE=`cat log-entry | awk '/data/ {print $2}'`
   ```

   Read additional fields from the log entry.

   ```sh theme={null}
   LOG_ENTRY=0x`echo $TOPICS$SENT_MESSAGE | sed 's/0x//'`
   ```

   Consolidate the entire log entry.

5. Create the access list for the executing message

```sh theme={null}
RPC_PARAMS=$(cat <<INNER_END_OF_FILE
{
    "origin": "$ORIGIN",
    "blockNumber": "$BLOCK_NUMBER",
    "logIndex": "$LOG_INDEX",
    "timestamp": "$TIMESTAMP",
    "chainId": "$CHAIN_ID_A",
    "payload": "$LOG_ENTRY"
}
INNER_END_OF_FILE
)

ACCESS_LIST=`cast rpc admin_getAccessListForIdentifier --rpc-url http://localhost:8420 "$RPC_PARAMS" | jq .accessList`

```

To secure cross-chain messaging and prevent potential [denial-of-service attacks](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/interop-access-list.md), relay transactions require properly formatted access lists that include a checksum derived from the message data.
This lets sequencers know what executing messages to expect in a transaction, which makes it easy not to include transactions that are invalid because they rely on messages that were never sent.

The [algorithm to calculate the access list](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L87-L115) is a bit complicated, but you dont need to worry about it.
Supersim exposes [RPC calls](https://supersim.pages.dev/guides/interop/cast?highlight=manuall#7-construct-the-access-list-for-the-message) that calculates it for you on port 8420.
The code above will calculate the correct access list even if you're using a different interop cluster where autorelay is not functioning.
This is because the code implements a [pure function](https://en.wikipedia.org/wiki/Pure_function), which produces consistent results regardless of external state.
In contrast, the `admin_getAccessListByMsgHash` RPC call is not a pure function, it is dependent on system state and therefore less flexible in these situations.

6. Show that the manual relay is necessary

   ```sh theme={null}
   echo Old greeting
   cast call $GREETER_B_ADDRESS "greet()(string)" --rpc-url $URL_CHAIN_B
   ```

   Show the current greeting.
   The message has not been relayed yet, so it's still the old greeting.

7. Actually relay the message

   ```sh theme={null}
   cast send -q $ORIGIN "relayMessage((address,uint256,uint256,uint256,uint256),bytes)" "($ORIGIN,$BLOCK_NUMBER,$LOG_INDEX,$TIMESTAMP,$CHAIN_ID_A)" $LOG_ENTRY --access-list "$ACCESS_LIST" --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY
   ```

   Call [`relayMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L197-L256) to relay the message.

8. Show the relay results

   ```sh theme={null}
   echo New greeting
   cast call $GREETER_B_ADDRESS "greet()(string)" --rpc-url $URL_CHAIN_B
   ```

   Again, show the current greeting.
   Now it's the new one.

## Next steps

* Review the [OP Stack interop explainer](/op-stack/interop/explainer) for answers to common questions about interoperability.
* Read the [message passing explainer](/app-developers/guides/interoperability/message-passing) to understand what happens "under the hood".
* Write a revolutionary app that uses multiple blockchains within the OP Stack ecosystem.


# Interop message passing tutorial
Source: https://docs.optimism.io/app-developers/tutorials/interoperability/message-passing

Learn to implement cross-chain communication on OP Stack chains by building a message passing system using the L2ToL2CrossDomainMessenger contract.

<Info>
  OP Stack interop is in active development. Some features may be experimental.
</Info>

## Overview

This tutorial demonstrates how to implement cross-chain communication within the OP Stack ecosystem. You'll build a complete
message passing system that enables different chains to interact with each other using the `L2ToL2CrossDomainMessenger` contract.

<Expandable title="About this tutorial">
  **Prerequisite technical knowledge**

  * Intermediate Solidity programming
  * Basic TypeScript knowledge
  * Understanding of smart contract development
  * Familiarity with blockchain concepts

  **What you'll learn**

  * How to deploy contracts across different chains
  * How to implement cross-chain message passing
  * How to handle sender verification across chains
  * How to relay messages manually between chains

  **Development environment**

  * Unix-like operating system (Linux, macOS, or WSL for Windows)
  * Node.js version 16 or higher
  * Git for version control

  **Required tools**

  The tutorial uses these primary tools:

  * Foundry: For smart contract development
  * Supersim: For local blockchain simulation (optional)
  * TypeScript: For offchain code (for relaying messages manually)
  * Viem: For interactions with the chain from the offchain app
</Expandable>

### What You'll Build

* A `Greeter` contract that stores and updates a greeting
* A `GreetingSender` contract that sends cross-chain messages to update the greeting
* A TypeScript application to relay messages between chains

<Info>
  This tutorial provides step-by-step instructions for implementing cross-chain messaging.
  For a conceptual overview,
  see the [Message Passing Explainer](/app-developers/guides/interoperability/message-passing).
</Info>

In this tutorial, you will learn how to use the [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol) contract to pass messages between interoperable blockchains.

## Setting up your development environment

<Steps>
  <Step title="Follow [Install Supersim](/app-developers/tutorials/development/supersim/installation) to set up:">
    * Foundry for smart contract development (required in all cases)
    * Supersim for local blockchain simulation (optional)
  </Step>

  <Step title="Verify your installation:">
    ```sh theme={null}
    forge --version
    ./supersim --version
    ```
  </Step>
</Steps>

## Implementing onchain message passing (in Solidity)

The implementation consists of three main components:

1. **Greeter Contract**: Deployed on `Chain B`, receives and stores messages.
2. **GreetingSender Contract**: Deployed on `Chain A`, initiates cross-chain messages.

<Steps>
  <Step title="Setting up test networks">
    1) If you are using [Supersim](/app-developers/tools-sdks/supersim), go to the directory where Supersim is installed and start it with autorelay.

       ```sh theme={null}
       ./supersim --interop.autorelay
       ```

       If you are using [the devnets](/app-developers/guides/building-apps), just skip this step.

       <Tabs>
         <Tab title="Supersim">
           Supersim creates three `anvil` blockchains:

           | Role     | ChainID | RPC URL                                        |
           | -------- | ------: | ---------------------------------------------- |
           | L1       |     900 | [http://127.0.0.1:8545](http://127.0.0.1:8545) |
           | OPChainA |     901 | [http://127.0.0.1:9545](http://127.0.0.1:9545) |
           | OPChainB |     902 | [http://127.0.0.1:9546](http://127.0.0.1:9546) |
         </Tab>

         <Tab title="Devnets">
           These are the three networks involved in the devnet:

           | Role         |   ChainID | RPC URL                                                                          |
           | ------------ | --------: | -------------------------------------------------------------------------------- |
           | L1 (Sepolia) |  11155111 | [https://eth-sepolia.public.blastapi.io](https://eth-sepolia.public.blastapi.io) |
           | ChainA       | 420120000 | [https://interop-alpha-0.optimism.io](https://interop-alpha-0.optimism.io)       |
           | ChainB       | 420120001 | [https://interop-alpha-1.optimism.io](https://interop-alpha-1.optimism.io)       |
         </Tab>
       </Tabs>

    2) In a separate shell, store the configuration in environment variables.

       <Tabs>
         <Tab title="Supersim">
           Set these parameters for Supersim.

           ```sh theme={null}
           PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80
           USER_ADDRESS=0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
           URL_CHAIN_A=http://127.0.0.1:9545
           URL_CHAIN_B=http://127.0.0.1:9546
           INTEROP_BRIDGE=0x4200000000000000000000000000000000000028
           ```
         </Tab>

         <Tab title="Devnets">
           For Devnet, specify in `PRIVATE_KEY` the private key you used for the setup script and then these parameters.

           ```sh theme={null}
           USER_ADDRESS=`cast wallet address --private-key $PRIVATE_KEY`
           URL_CHAIN_A=https://interop-alpha-0.optimism.io
           URL_CHAIN_B=https://interop-alpha-1.optimism.io
           INTEROP_BRIDGE=0x4200000000000000000000000000000000000028
           ```
         </Tab>
       </Tabs>

    <Expandable title="Sanity check">
      To verify that the chains are running, check the balance of `$USER_ADDRESS`.

      ```sh theme={null}
      cast balance --ether $USER_ADDRESS --rpc-url $URL_CHAIN_A
      cast balance --ether $USER_ADDRESS --rpc-url $URL_CHAIN_B
      ```
    </Expandable>
  </Step>

  <Step title="Create the contracts">
    1. Create a new Foundry project.

       ```sh theme={null}
       mkdir onchain-code
       cd onchain-code
       forge init
       ```

    2. In `src/Greeter.sol` put this file.
       This is a variation on [Hardhat's Greeter contract](https://github.com/matter-labs/hardhat-zksync/blob/main/examples/upgradable-example/contracts/Greeter.sol).

       ```solidity theme={null}
           //SPDX-License-Identifier: MIT
           pragma solidity ^0.8.0;

           contract Greeter {
               string greeting;

               event SetGreeting(
                   address indexed sender,     // msg.sender
                   string greeting
               );

               function greet() public view returns (string memory) {
                   return greeting;
               }

               function setGreeting(string memory _greeting) public {
                   greeting = _greeting;
                   emit SetGreeting(msg.sender, _greeting);
               }
           }
       ```

    3. Deploy the `Greeter` contract to Chain B and store the resulting contract address in the `GREETER_B_ADDRESS` environment variable.

       ```sh theme={null}
       GREETER_B_ADDRESS=`forge create --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY Greeter --broadcast | awk '/Deployed to:/ {print $3}'`
       ```

       <Expandable title="Explanation">
         The command that deploys the contract is:

         ```sh theme={null}
         forge create --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY Greeter --broadcast
         ```

         The command output gives us the deployer address, the address of the new contract, and the transaction hash:

         ```
         Deployer: 0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266
         Deployed to: 0x5FC8d32690cc91D4c39d9d3abcBD16989F875707
         Transaction hash: 0xf155d360ec70ee10fe0e02d99c16fa5d6dc2a0e79b005fec6cbf7925ff547dbf
         ```

         The [`awk`](https://www.tutorialspoint.com/awk/index.htm) command looks for the line that has `Deployed to:` and writes the third word in that line, which is the address.

         ```sh theme={null}
         awk '/Deployed to:/ {print $3}'
         ```

         Finally, in UNIX (including Linux and macOS) when the command line includes backticks, the shell executes the code between the backticks and puts the output, in this case the contract address, in the command.
         So we get.

         ```sh theme={null}
         GREETER_B_ADDRESS=<the address>
         ```
       </Expandable>

    <Expandable title="Sanity check">
      Run these commands to verify the contract works.
      The first and third commands retrieve the current greeting, while the second command updates it.

      ```sh theme={null}
      cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
      cast send --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "setGreeting(string)" Hello$$
      cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
      ```
    </Expandable>

    4. Install the Optimism Solidity libraries into the project.

       ```sh theme={null}
       cd lib
       npm install @eth-optimism/contracts-bedrock
       cd ..
       echo @eth-optimism/=lib/node_modules/@eth-optimism/ >> remappings.txt
       ```

    5. Create `src/GreetingSender.sol`.

       ```solidity theme={null}
           //SPDX-License-Identifier: MIT
           pragma solidity ^0.8.0;

           import { Predeploys } from "@eth-optimism/contracts-bedrock/src/libraries/Predeploys.sol";
           import { IL2ToL2CrossDomainMessenger } from "@eth-optimism/contracts-bedrock/src/L2/IL2ToL2CrossDomainMessenger.sol";

           import { Greeter } from "src/Greeter.sol";

           contract GreetingSender {
               IL2ToL2CrossDomainMessenger public immutable messenger =
                   IL2ToL2CrossDomainMessenger(Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER);

               address immutable greeterAddress;
               uint256 immutable greeterChainId;

               constructor(address _greeterAddress, uint256 _greeterChainId) {
                   greeterAddress = _greeterAddress;
                   greeterChainId = _greeterChainId;
               }

               function setGreeting(string calldata greeting) public {
                   bytes memory message = abi.encodeCall(
                       Greeter.setGreeting,
                       (greeting)
                   );
                   messenger.sendMessage(greeterChainId, greeterAddress, message);
               }
           }
       ```

       <Expandable title="Explanation">
         ```solidity theme={null}
              function setGreeting(string calldata greeting) public {
                  bytes memory message = abi.encodeCall(
                      Greeter.setGreeting,
                      (greeting)
                  );
                  messenger.sendMessage(greeterChainId, greeterAddress, message);
              }
         ```

         This function encodes a call to `setGreeting` and sends it to a contract on another chain.
         `abi.encodeCall(Greeter.setGreeting, (greeting))` constructs the [calldata](https://docs.soliditylang.org/en/latest/internals/layout_in_calldata.html) by encoding the function selector and parameters.
         The encoded message is then passed to `messenger.sendMessage`, which forwards it to the destination contract (`greeterAddress`) on the specified chain (`greeterChainId`).

         This ensures that `setGreeting` is executed remotely with the provided `greeting` value (as long as there is an executing message to relay it).
       </Expandable>

    6. Deploy `GreetingSender` to chain A.

       ```sh theme={null}
       CHAIN_ID_B=`cast chain-id --rpc-url $URL_CHAIN_B`
       GREETER_A_ADDRESS=`forge create --rpc-url $URL_CHAIN_A --private-key $PRIVATE_KEY --broadcast GreetingSender --constructor-args $GREETER_B_ADDRESS $CHAIN_ID_B | awk '/Deployed to:/ {print $3}'`
       ```
  </Step>

  <Step title="Send a message">
    Send a greeting from chain A to chain B.

    ```sh theme={null}
    cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
    cast send --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_A $GREETER_A_ADDRESS "setGreeting(string)" "Hello from chain A"
    sleep 4
    cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
    ```

    The `sleep` call is because it can take up to two seconds until the transaction is included in chain A, and then up to two seconds until the relay transaction is included in chain B.
  </Step>
</Steps>

## Sender information

Run this command to view the events to see who called `setGreeting`.

```sh theme={null}
cast logs --rpc-url $URL_CHAIN_B 'SetGreeting(address,string)'
```

The sender information is stored in the second event topic.
However, for cross-chain messages, this value corresponds to the local `L2ToL2CrossDomainMessenger` contract address (`4200000000000000000000000000000000000023`), making it ineffective for identifying the original sender.

In this section we change `Greeter.sol` to emit a separate event in it receives a cross domain message, with the sender's identity (address and chain ID).

<Steps>
  <Step title="Modify the Greeter contract">
    1. Modify `src/Greeter.sol` to this code.

       ```solidity theme={null}
           //SPDX-License-Identifier: MIT
           pragma solidity ^0.8.0;

           import { Predeploys } from "@eth-optimism/contracts-bedrock/src/libraries/Predeploys.sol";

           interface IL2ToL2CrossDomainMessenger {
               function crossDomainMessageContext() external view returns (address sender_, uint256 source_);
           }

           contract Greeter {

               IL2ToL2CrossDomainMessenger public immutable messenger =
                   IL2ToL2CrossDomainMessenger(Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER);

               string greeting;

               event SetGreeting(
                   address indexed sender,     // msg.sender
                   string greeting
               );

               event CrossDomainSetGreeting(
                   address indexed sender,   // Sender on the other side
                   uint256 indexed chainId,  // ChainID of the other side
                   string greeting
               );

               function greet() public view returns (string memory) {
                   return greeting;
               }

               function setGreeting(string memory _greeting) public {
                   greeting = _greeting;
                   emit SetGreeting(msg.sender, _greeting);

                   if (msg.sender == Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER) {
                       (address sender, uint256 chainId) =
                           messenger.crossDomainMessageContext();
                       emit CrossDomainSetGreeting(sender, chainId, _greeting);
                   }
               }
           }
       ```

       <Expandable title="Explanation">
         ```solidity theme={null}
         interface IL2ToL2CrossDomainMessenger {
           function crossDomainMessageContext() external view returns (address sender_, uint256 source_);
         }
         ```

         This definition isn't part of the [npmjs package](https://www.npmjs.com/package/@eth-optimism/contracts-bedrock) at writing, so we just add it here.

         ```solidity theme={null}
                 if (msg.sender == Predeploys.L2_TO_L2_CROSS_DOMAIN_MESSENGER) {
                     (address sender, uint256 chainId) =
                         messenger.crossDomainMessageContext();
                     emit CrossDomainSetGreeting(sender, chainId, _greeting);
                 }
         ```

         If we see that we got a message from `L2ToL2CrossDomainMessenger`, we call [`L2ToL2CrossDomainMessenger.crossDomainMessageContext`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol#L118-L126).
       </Expandable>

    2. Redeploy the contracts.
       Because the address of `Greeter` is immutable in `GreetingSender`, we need to redeploy both contracts.

       ```sh theme={null}
       GREETER_B_ADDRESS=`forge create --rpc-url $URL_CHAIN_B --private-key $PRIVATE_KEY Greeter --broadcast | awk '/Deployed to:/ {print $3}'`
       GREETER_A_ADDRESS=`forge create --rpc-url $URL_CHAIN_A --private-key $PRIVATE_KEY --broadcast GreetingSender --constructor-args $GREETER_B_ADDRESS $CHAIN_ID_B | awk '/Deployed to:/ {print $3}'`
       ```
  </Step>

  <Step title="Verify you can see cross chain sender information">
    1. Set the greeting through `GreetingSender`.

       ```sh theme={null}
       cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
       cast send --private-key $PRIVATE_KEY --rpc-url $URL_CHAIN_A $GREETER_A_ADDRESS "setGreeting(string)" "Hello from chain A, with a CrossDomainSetGreeting event"
       sleep 4
       cast call --rpc-url $URL_CHAIN_B $GREETER_B_ADDRESS "greet()" | cast --to-ascii
       ```

    2. Read the log entries.

       ```sh theme={null}
       cast logs --rpc-url $URL_CHAIN_B 'CrossDomainSetGreeting(address,uint256,string)'
       echo $GREETER_A_ADDRESS
       echo 0x385=`echo 0x385 | cast --to-dec`
       echo 0x190a85c0=`echo 0x190a85c0 | cast --to-dec`
       ```

       See that the second topic (the first indexed log parameter) is the same as `$GREETER_A_ADDRESS`.
       The third topic can be either `0x385=901`, which is the chain ID for supersim chain A, or `0x190a85c0=420120000`, which is the chain ID for devnet alpha 0.
  </Step>
</Steps>

## Next steps

* Review the [OP Stack Interop Explainer](/op-stack/interop/explainer) for answers to common questions about interoperability.
* Read the [Message Passing Explainer](/app-developers/guides/interoperability/message-passing) to understand what happens "under the hood".
* Write a revolutionary app that uses multiple blockchains within the OP Stack ecosystem.


# Estimating transaction costs on OP Stack
Source: https://docs.optimism.io/app-developers/tutorials/transactions/sdk-estimate-costs

Learn how to use viem to estimate the cost of a transaction on OP Stack.

In this tutorial, you'll learn how to use [viem](https://viem.sh/op-stack/) to estimate the cost of a transaction on OP Mainnet.
You'll learn how to estimate the [execution gas fee](/app-developers/transactions/fees#execution-gas-fee) and the [L1 data fee](/app-developers/transactions/fees#l1-data-fee) independently.
You'll also learn how to estimate the total cost of the transaction all at once.

<Info>
  Check out the full explainer on [OP Stack transaction fees](/app-developers/guides/transactions/fees) for more information on how OP Mainnet charges fees under the hood.
</Info>

## Supported networks

Viem supports any of the [OP Stack networks](/op-mainnet/network-information/connecting-to-op).
The OP Stack networks are included in Viem by default.
If you want to use a network that isn't included by default, you can add it to Viem's chain configurations.

## Dependencies

* [node](https://nodejs.org/en/)
* [pnpm](https://pnpm.io/installation)

## Create a demo project

You're going to use the  library for this tutorial.
Since  is a [Node.js](https://nodejs.org/en/) library, you'll need to create a Node.js project to use it.

<Steps>
  <Step title="Make a project folder">
    ```bash theme={null}
    mkdir op-est-cost-tutorial
    cd op-est-cost-tutorial
    ```
  </Step>

  <Step title="Initialize the project">
    ```bash theme={null}
    pnpm init
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm add viem
    ```
  </Step>
</Steps>

## Get ETH on OP Sepolia

This tutorial explains how to estimate transaction costs on OP Sepolia.
You will need to get some ETH on OP Sepolia in order to run the code in this tutorial.

<TutorialFaucets />

## Add a private key to your environment

You need a private key in order to sign transactions.
Set your private key as an environment variable with the `export` command.
Make sure this private key corresponds to an address that has ETH on .

<Info>
  Want to create a new wallet for this tutorial?
  If you have [`cast`](https://book.getfoundry.sh/getting-started/installation) installed you can run `cast wallet new` in your terminal to create a new wallet and get the private key.
</Info>

```bash theme={null}
export TUTORIAL_PRIVATE_KEY=0x...
```

## Start the Node REPL

You're going to use the Node REPL to interact with .
To start the Node REPL, run the following command in your terminal:

```bash theme={null}
node
```

This will bring up a Node REPL prompt that allows you to run JavaScript code.

## Set session variables

You'll need a few variables throughout this tutorial.
Let's set those up now.

<Steps>
  <Step title="Import viem and other necessary modules">
    ```js theme={null}
    const { createPublicClient, createWalletClient, http, parseEther, parseGwei, formatEther } = require('viem');
    const { privateKeyToAccount } = require('viem/accounts');
    const { optimismSepolia } = require('viem/chains');
    const { publicActionsL2, walletActionsL2 } = require('viem/op-stack');
    ```
  </Step>

  <Step title="Set up the account">
    ```js theme={null}
    const privateKey = process.env.TUTORIAL_PRIVATE_KEY
    const account = privateKeyToAccount(privateKey)
    ```
  </Step>

  <Step title="Create the public client">
    ```js theme={null}
    const publicClient = createPublicClient({
      chain: optimismSepolia,
      transport: http("https://sepolia.optimism.io"),
    }).extend(publicActionsL2())
    ```
  </Step>

  <Step title="Create the wallet client">
    ```js theme={null}
    const walletClientL2 = createWalletClient({
      chain: optimismSepolia,
      transport: http("https://sepolia.optimism.io"),
    }).extend(walletActionsL2())
    ```
  </Step>
</Steps>

## Estimate transaction costs

You're now going to use the Viem to estimate the cost of a transaction on OP Mainnet.
Here you'll estimate the cost of a simple transaction that sends a small amount of ETH from your address to the address `0x1000000000000000000000000000000000000000`.

<Steps>
  <Step title="Create the unsigned transaction">
    Viem makes it easy to create unsigned transactions so you can estimate the cost of a transaction before asking a user to sign it.
    Here you'll create an unsigned transaction that sends a small amount of ETH from your address to the address `0x1000000000000000000000000000000000000000`.

    ```js theme={null}
      const transaction = {
      account,
      to: '0x1000000000000000000000000000000000000000',
      value: parseEther('0.00069420'),
      gasPrice: await publicClient.getGasPrice() 
      }
    ```
  </Step>

  <Step title="Estimate the total cost">
    With Viem you can estimate the total cost of a transaction using the [estimateTotalFee](https://viem.sh/op-stack/actions/estimateTotalFee) method.

    ```js theme={null}
      const totalEstimate = await publicClient.estimateTotalFee(transaction)
      console.log(`Estimated Total Cost: ${formatEther(totalEstimate)} ETH`)
    ```
  </Step>

  <Step title="Send the transaction">
    Now that you've estimated the total cost of the transaction, go ahead and send it to the network.
    This will make it possible to see the actual cost of the transaction to compare to your estimate.

    ```js theme={null}
      const txHash = await walletClientL2.sendTransaction(transaction)
      console.log(`Transaction Hash: ${txHash}`)

      const receipt = await publicClient.waitForTransactionReceipt({ hash: txHash })
      console.log('receipt', receipt);
    ```
  </Step>

  <Step title="Check the actual execution gas fee">
    Once you get back the transaction receipt, check the actual execution gas fee.
    You can do so by accessing the `gasUsed` and `effectiveGasPrice` from the transaction receipt.
    You can then multiply these values to get the actual L2 cost of the transaction

    ```js theme={null}
      const l2CostActual = receipt.gasUsed * receipt.effectiveGasPrice
      console.log(`Actual Execution Gas Fee: ${formatEther(l2CostActual)} ETH`)
    ```
  </Step>

  <Step title="Check the actual L1 data fee">
    You can also check the actual L1 data fee.

    ```js theme={null}
      const l1CostActual = receipt.l1Fee
      console.log(`Actual L1 Data Fee: ${formatEther(l1CostActual)} ETH`)
    ```
  </Step>

  <Step title="Check the actual total cost">
    Sum these two together to get the actual total cost of the transaction.

    ```js theme={null}
      const totalActual = l2CostActual + l1CostActual
      console.log(`Actual Total Cost: ${formatEther(totalActual)} ETH`)
    ```
  </Step>

  <Step title="Check the difference">
    Finally, check the difference between the estimated total cost and the actual total cost.
    This will give you a sense of how accurate your estimate was.
    Estimates will never be entirely accurate, but they should be close!

    ```js theme={null}
      const difference = totalEstimate >= totalActual ? totalEstimate - totalActual : totalActual - totalEstimate
      console.log(`Estimation Difference: ${formatEther(difference)} ETH`)
    ```
  </Step>
</Steps>

<Info>
  Estimates will never be entirely accurate due to network conditions and gas price fluctuation, but they should be close to the actual costs.
</Info>

## Next steps

* Always estimate before sending: Estimating costs before sending a transaction helps prevent unexpected fees and failed transactions.
* Account for gas price volatility: Gas prices can change rapidly. Consider adding a buffer to your estimates or implementing a gas price oracle for more accurate pricing.
* Optimize transaction data: Minimize the amount of data in your transactions to reduce L1 data fees.
* Monitor network conditions: Keep an eye on network congestion and adjust your estimates accordingly.
* Use appropriate gas limits: Setting too low a gas limit can cause transactions to fail, while setting it too high can result in unnecessary costs.
* Implement retry mechanisms: If a transaction fails due to underestimated gas, implement a retry mechanism with adjusted gas parameters.


# Tracing deposits and withdrawals
Source: https://docs.optimism.io/app-developers/tutorials/transactions/sdk-trace-txns

Learn how to use the viem library to trace deposits and withdrawals between L1 and L2.

In this tutorial, you'll learn how to use the [viem](https://viem.sh) library to trace a [Standard Bridge](/app-developers/guides/bridging/standard-bridge) deposit or withdrawal between L1 and L2.
You'll specifically learn how to determine the status of a deposit or withdrawal and how to retrieve the transaction receipt for the executed transaction on L1 (for withdrawals) or L2 (for deposits).

## Dependencies

* [node](https://nodejs.org/en/)
* [pnpm](https://pnpm.io/installation)

## Create a demo project

You're going to use the  library for this tutorial.
Since  is a [Node.js](https://nodejs.org/en/) library, you'll need to create a Node.js project to use it.

<Steps>
  <Step title="Make a project folder">
    ```bash theme={null}
    mkdir trace-trx
    cd trace-trx
    ```
  </Step>

  <Step title="Initialize the project">
    ```bash theme={null}
    pnpm init
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm add viem
    ```
  </Step>
</Steps>

## Add RPC URLs to your environment

You'll be using the `getTransactionReceipt` function from the viem library during this tutorial. This function uses event queries to retrieve the receipt for a deposit or withdrawal.
Since this function uses large event queries, you'll need to use an RPC provider like [Alchemy](https://alchemy.com) that supports indexed event queries.
Grab an L1 and L2 RPC URL for Sepolia and OP Sepolia, respectively.

```bash theme={null}
export L1_RPC_URL="https://YOUR_L1_ SEPOLIA_RPC_URL_HERE"
export L2_RPC_URL="https://YOUR_L2_OP_SEPOLIA_RPC_URL_HERE"
```

## Start the Node REPL

You're going to use the Node REPL to interact with .
To start the Node REPL, run the following command in your terminal:

```bash theme={null}
node
```

This will bring up a Node REPL prompt that allows you to run JavaScript code.

## Import dependencies

You need to import some dependencies into your Node REPL session.

### Import viem

```js theme={null}
const { createPublicClient, http } = require('viem');
const { optimismSepolia, sepolia } = require('viem/chains');
```

## Set session variables

You'll need a few variables throughout this tutorial. Let's set those up now.

<Steps>
  <Step title="Import RPC URLs">
    ```js theme={null}
    const l1RpcUrl = process.env.L1_RPC_URL;
    const l2RpcUrl = process.env.L2_RPC_URL;
    ```
  </Step>

  <Step title="Set the deposit to trace">
    You'll be tracing a specific deposit in this tutorial. Deposit tracing is generally based on the transaction hash of the transaction that triggered the deposit. You can replace this transaction hash with your own if you'd like.

    ```js theme={null}
    const depositHash = '0x5896d6e4a47b465e0d925723bab838c62ef53468139a5e9ba501efd70f90cccb'
    ```
  </Step>

  <Step title="Set the withdrawal to trace">
    You'll also be tracing a specific withdrawal in this tutorial. Like with deposits, withdrawal tracing is generally based on the transaction hash of the transaction that triggered the withdrawal. You can replace this transaction hash with your own if you'd like.

    ```js theme={null}
    const withdrawalHash = '0x18b8b4022b8d9e380fd89417a2e897adadf31e4f41ca17442870bf89ad024f42'
    ```
  </Step>

  <Step title="Create the RPC providers">
    ```js theme={null}
    const l1Client = createPublicClient({
      chain: sepolia,
      transport: http(l1RpcUrl),
    });

    const l2Client = createPublicClient({
      chain: optimismSepolia,
      transport: http(l2RpcUrl),
    });
    ```
  </Step>
</Steps>

## Trace a Deposit

You can use viem to trace a deposit.

<Steps>
  <Step title="Get the deposit status">
    You can query for the deposit status using the transaction hash of the deposit.

    ```js theme={null}
    console.log('Grabbing deposit status...')
    const depositStatus = await l2Client.getTransactionReceipt({ hash: depositHash });
    console.log(depositStatus);
    ```
  </Step>

  <Step title="Get the deposit transaction receipt">
    Retrieve the transaction receipt for the deposit using the viem client.

    ```js theme={null}
    console.log('Grabbing deposit receipt...')
    const depositReceipt = await l2Client.getTransaction({ hash: depositHash });
    console.log(depositReceipt);
    ```
  </Step>

  <Step title="Get the deposit transaction">
    You can directly query for the L2 transaction that executed the deposit.

    ```js theme={null}
    console.log('Grabbing deposit txn...')
    const depositTransaction = await l2Client.getTransaction({ hash: depositHash });
    console.log(depositTransaction);
    ```
  </Step>
</Steps>

## Trace a withdrawal

You can use viem's functions to trace a withdrawal.

<Steps>
  <Step title="Get the withdrawal status">
    Like deposits, withdrawals can have multiple statuses depending on where they are in the process.

    ```js theme={null}
    console.log('Grabbing withdrawal status...')
    const withdrawalStatus = await l1Client.getTransactionReceipt({ hash: withdrawalHash });
    console.log(withdrawalStatus);
    ```
  </Step>

  <Step title="Get the withdrawal transaction receipt">
    Retrieve the L1 transaction receipt for the withdrawal.

    ```js theme={null}
    console.log('Grabbing withdrawal receipt...')
    const withdrawalReceipt = await l1Client.getTransaction({ hash: withdrawalHash });
    console.log(withdrawalReceipt);
    ```
  </Step>

  <Step title="Get the withdrawal transaction">
    Directly query for the L1 transaction that executed the withdrawal.

    ```js theme={null}
    console.log('Grabbing withdrawal txn...')
    const withdrawalTransaction = await l1Client.getTransaction({ hash: withdrawalHash });
    console.log(withdrawalTransaction);
    ```
  </Step>
</Steps>

## Next steps

* Check out the tutorial on [bridging ERC-20 tokens with the @eth-optimism/viem package](/app-developers/tutorials/bridging/cross-dom-bridge-erc20) to learn how to create deposits and withdrawals.


# Triggering OP Stack transactions from Ethereum
Source: https://docs.optimism.io/app-developers/tutorials/transactions/send-tx-from-eth

Learn how to force transaction inclusion without the OP Stack Sequencer using Viem.

OP Stack currently uses a single-Sequencer block production model.
This means that there is only one Sequencer active on the network at any given time. Single-Sequencer models are simpler than their highly decentralized counterparts but they are also more vulnerable to potential downtime.

Sequencer downtime must not be able to prevent users from transacting on the network. As a result, OP Stack includes a mechanism for "forcing" transactions to be included in the blockchain. This mechanism involves triggering a transaction on OP Stack by sending a transaction on Ethereum.
In this tutorial you'll learn how to trigger a transaction on OP Stack from Ethereum using Viem. You'll use the OP Sepolia testnet, but the same logic will apply to OP Stack.

## Dependencies

* [node](https://nodejs.org/en/)
* [pnpm](https://pnpm.io/installation)

## Create a demo project

You're going to use the  library for this tutorial.
Since  is a [Node.js](https://nodejs.org/en/) library, you'll need to create a Node.js project to use it.

<Steps>
  <Step title="Make a project folder">
    ```bash theme={null}
    mkdir trigger-transaction
    cd trigger-transaction
    ```
  </Step>

  <Step title="Initialize the project">
    ```bash theme={null}
    pnpm init
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm add viem
    ```
  </Step>
</Steps>

## Get ETH on Sepolia and OP Sepolia

This tutorial explains how to bridge tokens from Sepolia to OP Sepolia. You will need to get some ETH on both of these testnets.

<TutorialFaucets />

## Add a private key to your environment

You need a private key in order to sign transactions.
Set your private key as an environment variable with the `export` command.
Make sure this private key corresponds to an address that has ETH on .

<Info>
  Want to create a new wallet for this tutorial?
  If you have [`cast`](https://book.getfoundry.sh/getting-started/installation) installed you can run `cast wallet new` in your terminal to create a new wallet and get the private key.
</Info>

```bash theme={null}
export TUTORIAL_PRIVATE_KEY=0x...
```

## Start the Node REPL

You're going to use the Node REPL to interact with .
To start the Node REPL, run the following command in your terminal:

```bash theme={null}
node
```

This will bring up a Node REPL prompt that allows you to run JavaScript code.

## Import dependencies

You need to import some dependencies into your Node REPL session.

<Steps>
  <Step title="Import Viem">
    ```js theme={null}
    const { createPublicClient, createWalletClient, http, parseEther, formatEther } = require('viem');
    const { optimismSepolia, sepolia } = require('viem/chains');
    const { privateKeyToAccount } = require('viem/accounts');
    const { publicActionsL2, publicActionsL1, walletActionsL2, walletActionsL1, getL2TransactionHashes } = require ('viem/op-stack')
    ```
  </Step>
</Steps>

## Set session variables

You'll need a few variables throughout this tutorial. Let's set those up now.

<Steps>
  <Step title="Load your private key">
    ```js theme={null}
    const privateKey = process.env.TUTORIAL_PRIVATE_KEY;
    const account = privateKeyToAccount(privateKey);
    ```
  </Step>

  <Step title="Create the RPC providers and wallets">
    ```js theme={null}
    const l1PublicClient = createPublicClient({ chain: sepolia, transport: http("https://rpc.ankr.com/eth_sepolia") }).extend(publicActionsL1())
    const l2PublicClient = createPublicClient({ chain: optimismSepolia, transport: http("https://sepolia.optimism.io") }).extend(publicActionsL2());
    const l1WalletClient = createWalletClient({ chain: sepolia, transport: http("https://rpc.ankr.com/eth_sepolia") }).extend(walletActionsL1());
    ```
  </Step>
</Steps>

## Check your initial balance

You'll be sending a small amount of ETH as part of this tutorial. Quickly check your balance on OP Sepolia so that you know how much you had at the start of the tutorial.

```js theme={null}
  const initialBalance = await l2PublicClient.getBalance({ address });
  console.log(`Initial balance: ${formatEther(initialBalance)} ETH`);
```

## Trigger the transaction

Now you'll use the `OptimismPortal` contract to trigger a transaction on OP Sepolia by sending a transaction on Sepolia.

<Steps>
  <Step title="Create the OptimismPortal object">
    ```js theme={null}
    const optimismPortalAbi = [
        {
        inputs: [
            { internalType: 'uint256', name: '_gasLimit', type: 'uint256' },
            { internalType: 'bytes', name: '_data', type: 'bytes' },
        ],
        name: 'depositTransaction',
        outputs: [],
        stateMutability: 'payable',
        type: 'function',
        },
    ];
    ```
  </Step>

  <Step title="Estimate the required gas">
    When sending transactions via the `OptimismPortal` contract it's important to always include a gas buffer. This is because the `OptimismPortal` charges a variable amount of gas depending on the current demand for L2 transactions triggered via L1. If you do not include a gas buffer, your transactions may fail.

    ```js theme={null}
    const optimismPortalAddress = '0x5b47E1A08Ea6d985D6649300584e6722Ec4B1383';
    const gasLimit = 100000n;
    const data = '0x';
    const value = parseEther('0.000069420');

    const gasEstimate = await l1PublicClient.estimateContractGas({
        address: optimismPortalAddress,
        abi: optimismPortalAbi,
        functionName: 'depositTransaction',
        args: [gasLimit, data],
        value,
        account: account.address,
    });
    ```
  </Step>

  <Step title="Send the transaction">
    Now you'll send the transaction. Note that you are including a buffer of 20% on top of the gas estimate.

    ```js theme={null}
    const { request } = await l1PublicClient.simulateContract({
        account,
        address: optimismPortalAddress,
        abi: optimismPortalAbi,
        functionName: 'depositTransaction',
        args: [gasLimit, data],
        value,
        gas: gasEstimate * 120n / 100n, // 20% buffer
      })

    const l1TxHash = await l1WalletClient.writeContract(request)
    console.log(`L1 transaction hash: ${l1TxHash}`)
    ```
  </Step>

  <Step title="Wait for the L1 transaction">
    First you'll need to wait for the L1 transaction to be mined.

    ```js theme={null}
    const l1TxHash = await l1WalletClient.writeContract(request)
    ```
  </Step>

  <Step title="Wait for the L2 transaction">
    Now you'll need to wait for the corresponding L2 transaction to be included in a block. This transaction is automatically created as a result of your L1 transaction. Here you'll determine the hash of the L2 transaction and then wait for that transaction to be included in the L2 blockchain.

    ```js theme={null}
    const [l2Hash] = getL2TransactionHashes(l1TxHash) 
    console.log(`Corresponding L2 transaction hash: ${l2Hash}`);

    const l2Receipt = await l2PublicClient.waitForTransactionReceipt({
        hash: l2Hash,
    }); 
    console.log('L2 transaction confirmed:', l2Receipt);
    ```
  </Step>
</Steps>

## Check your updated balance

You should have a little less ETH on OP Sepolia now. Check your balance to confirm.

```js theme={null}
  const finalBalance = await l2Wallet.getBalance()
  console.log(`Final balance: ${formatEther(finalBalance)} ETH`);
```

Make sure that the difference is equal to the amount you were expecting to send.

```js theme={null}
  const difference = initialBalance - finalBalance
  console.log(`Difference in balance: ${formatEther(difference)} ETH`);
```

## Next steps

You've successfully triggered a transaction on OP Sepolia by sending a transaction on Sepolia using Viem. Although this tutorial demonstrated the simple example of sending a basic ETH transfer from your L2 address via the OptimismPortal contract, you can use this same technique to trigger any transaction you want. You can trigger smart contracts, send ERC-20 tokens, and more.


# Configure the batcher
Source: https://docs.optimism.io/chain-operators/guides/configuration/batcher

Learn how to configure the op-batcher for your chain, covering the batcher policy, cost tuning, multi-blob transactions, and sequencer throttling.

The op-batcher posts L2 sequencer data to the L1, to make it available for
verifiers. This guide walks through the policy constraints every OP Stack chain
must respect and the settings with the biggest impact on cost and stability.
For a catalogue of every CLI flag and environment variable, see the
[batcher configuration reference](/chain-operators/reference/batcher-configuration).

## Batcher policy

The batcher policy defines high-level constraints and responsibilities regarding how L2 data is posted to L1. Below are the [standard guidelines](/op-stack/protocol/superchain-registry#what-is-a-standard-chain) for configuring the batcher within the OP Stack.

| Parameter                  | Description                                                                                                    | Administrator           | Requirement                                                                                | Notes                                                                                                                                                                                                                                    |
| -------------------------- | -------------------------------------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Data Availability Type     | Specifies whether the batcher uses **blobs**, **calldata**, or **auto** to post transaction data to L1.        | Batch submitter address | Ethereum (Blobs or Calldata)                                                               | - Alternative data availability (Alt-DA) is not yet supported in the standard configuration.<br />- The sequencer can switch at will between blob transactions and calldata, with no restrictions, because both are fully secured by L1. |
| Batch Submission Frequency | Determines how frequently the batcher submits aggregated transaction data to L1 (via the batcher transaction). | Batch submitter address | Must target **1,800 L1 blocks** (6 hours on Ethereum, assuming 12s L1 block time) or lower | - Batches must be posted before the sequencing window closes (commonly 12 hours by default).<br />- Leave a buffer for L1 network congestion and data size to ensure that each batch is fully committed in a timely manner.              |

* **Data Availability Types**:
  * **Calldata** is generally simpler but can be more expensive on mainnet Ethereum, depending on gas prices.
  * **Blobs** are typically lower cost when your chain has enough transaction volume to fill large chunks of data.
  * The `op-batcher` can toggle between these approaches by setting the `--data-availability-type=<blobs|calldata|auto>` flag or with the `OP_BATCHER_DATA_AVAILABILITY_TYPE` env variable. Setting this flag to `auto` will allow the batcher to automatically switch between `calldata` and `blobs` based on the current L1 gas price.

* **Batch Submission Frequency** (`OP_BATCHER_MAX_CHANNEL_DURATION` and related flags):
  * Standard OP Chains frequently target a maximum channel duration between 1–6 hours.
  * Your chain should never exceed your L2's sequencing window (commonly 12 hours).
  * If targeting a longer submission window (e.g., 5 or 6 hours), be aware that the [safe head](https://specs.optimism.io/glossary.html#safe-l2-head) can stall up to that duration.

Include these high-level "policy" requirements when you set up or modify your `op-batcher` configuration. See the [batcher configuration reference](/chain-operators/reference/batcher-configuration), which explains each CLI flag and environment variable in depth.

## Recommendations

### Set your  `OP_BATCHER_MAX_CHANNEL_DURATION`

<Info>
  The default value inside `op-batcher`, if not specified, is still `0`, which means channel duration tracking is disabled.
  For very low throughput chains, this would mean to fill channels until close to the sequencing window and post the channel to `L1 SUB_SAFETY_MARGIN` L1 blocks before the sequencing window expires.
</Info>

To minimize costs, we recommend setting your  `OP_BATCHER_MAX_CHANNEL_DURATION` to target 5 hours, with a value of `1500` L1 blocks. When non-zero, this parameter is the max time (in L1 blocks, which are 12 seconds each) between which batches will be submitted to the L1. If you have this set to 5 for example, then your batcher will send a batch to the L1 every 5\*12=60 seconds. When using blobs, because 130kb blobs need to be purchased in full, if your chain doesn't generate at least \~130kb of data in those 60 seconds, then you'll be posting only partially full blobs and wasting storage.

* We do not recommend setting any values higher than targeting 5 hours, as batches have to be submitted within the sequencing window which defaults to 12 hours for OP chains, otherwise your chain may experience a 12 hour long chain reorg. 5 hours is the longest length of time we recommend that still sits snugly within that 12 hour window to avoid affecting stability.
* If your chain fills up full blobs of data before the `OP_BATCHER_MAX_CHANNEL_DURATION` elapses, a batch will be submitted anyways - (e.g. even if the OP Mainnet batcher sets an `OP_BATCHER_MAX_CHANNEL_DURATION` of 5 hours, it will still be submitting batches every few minutes)

<Info>
  While setting an`OP_BATCHER_MAX_CHANNEL_DURATION` of `1500` results in the cheapest fees, it also means that your [safe head](https://specs.optimism.io/glossary.html#safe-l2-head) can stall for up to 5 hours.

  * This will negatively impact apps on your chain that rely on the safe head for operation. While many apps can likely operate simply by following the unsafe head, often Centralized Exchanges or third party bridges wait until transactions are marked safe before processing deposits and withdrawal.
  * Thus a larger gap between posting batches can result in significant delays in the operation of certain types of high-security applications.
</Info>

### Configure your batcher to use multiple blobs

<Info>
  When there's blob congestion, running with high blob counts can backfire, because you will have a harder time getting blobs included and then fees will bump, which always means a doubling of the priority fees.
</Info>

The `op-batcher` has the capabilities to send multiple blobs per single blob transaction. This is accomplished by the use of multi-frame channels, see the [specs](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#frame-format) for more technical details on channels and frames.

A minimal batcher configuration (with env vars) to enable 6-blob batcher transactions is:

```
  - OP_BATCHER_BATCH_TYPE=1 # span batches, optional
  - OP_BATCHER_DATA_AVAILABILITY_TYPE=blobs
  - OP_BATCHER_TARGET_NUM_FRAMES=6 # 6 blobs per tx
  - OP_BATCHER_TXMGR_MIN_BASEFEE=2.0 # 2 gwei, might need to tweak, depending on gas market
  - OP_BATCHER_TXMGR_MIN_TIP_CAP=2.0 # 2 gwei, might need to tweak, depending on gas market
  - OP_BATCHER_RESUBMISSION_TIMEOUT=240s # wait 4 min before bumping fees
```

This enables blob transactions and sets the target number of frames to 6, which translates to 6 blobs per transaction.
The minimum tip cap and base fee are also lifted to 2 gwei because it is uncertain how easy it will be to get 6-blob transactions included and slightly higher priority fees should help.
The resubmission timeout is increased to a few minutes to give more time for inclusion before bumping the fees because current transaction pool implementations require a doubling of fees for blob transaction replacements.

Multi-blob transactions are particularly useful for medium to high-throughput chains, where enough transaction volume exists to fill up 6 blobs in a reasonable amount of time.
To determine what number of blobs is right for your chain, estimate the compressed batch data your chain produces per channel duration and divide by blob capacity (about 130 KB); [Size your channels](/use-cases/tune-batcher-costs#step-4-size-your-channels) in the Tune batcher costs guide walks through this estimate and the matching fee scalar configuration. Please also refer to the [Post batch data as blobs](/chain-operators/guides/features/blobs) guide for chain operators.

### Set your `--batch-type=1` to use span batches

Span batches reduce the overhead of OP Stack chains, introduced in the Delta network upgrade. This is beneficial for sparse and low-throughput OP Stack chains.

The overhead is reduced by representing a span of consecutive L2 blocks in a more efficient manner, while preserving the same consistency checks as regular batch data.

For step-by-step instructions, including how to confirm Delta is active first, see [Enable span batches](/chain-operators/guides/features/enable-span-batches).

## Batcher sequencer throttling

This feature is a batcher-driven sequencer-throttling control loop. This is to avoid sudden spikes in L1 DA-usage consuming too much available gas and causing a backlog in batcher transactions. The batcher can throttle the sequencer's data throughput instantly when it sees too much batcher data built up.

There are two throttling knobs:

1. Transaction throttling, which skips individual transactions whose estimated compressed L1 DA usage goes over a certain threshold, and
2. Block throttling, which caps a block's estimated total L1 DA usage and leads to not including transactions during block building that would move the block's L1 DA usage past a certain threshold.

**Feature requirements**

* This feature is enabled by default and requires the sequencer's `op-reth` node to expose the `miner_setMaxDASize` RPC (enable the `miner` namespace, below). It can be disabled by setting `--throttle.unsafe-da-bytes-lower-threshold` (env var `OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_LOWER_THRESHOLD`) to 0, which is the only flag you need to change to turn throttling off. The sequencer's `op-reth` node has to be updated first, before updating the batcher, so that the required RPC is available at the time of the batcher restart.
* It is required to upgrade to `op-conductor/v0.2.0` if you are using conductor's leader-aware rpc proxy feature. This conductor release includes support for proxying the `miner_setMaxDASize` RPC.

**Configuration**

<Info>
  Note that this feature requires the batcher to correctly follow the sequencer at all times, or it would set throttling parameters on a non-sequencer EL client. That means, active sequencer follow mode has to be enabled correctly by listing all the possible sequencers in the L2 rollup and EL endpoint flags.
</Info>

The batcher is configured for throttling by default with the parameters described below (and corresponding flags which allow the defaults to be overridden):

* Backlog of pending block bytes beyond which the batcher will enable throttling on the sequencer via `--throttle.unsafe-da-bytes-lower/upper-threshold` (env var `OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_LOWER/UPPER_THRESHOLD`): 3\_200\_000 and 12\_800\_000 (batcher backlog of 3.2MB to 12.8MB of data to batch). Disable throttling by setting the lower threshold to `0`. The upper threshold sets the level where the maximum throttling intensity is reached.
* Individual tx size throttling via `--throttle.tx-size-lower/upper-limit` (env var `OP_BATCHER_THROTTLE_TX_SIZE_LOWER/UPPER_LIMIT`): 150 and 20\_000. This is the limit on the estimated compressed size of a transaction when throttling is at maximum/minimum intensity respectively.
* Block size throttling via `--throttle.block-size-lower/upper-limit` (env var `OP_BATCHER_THROTTLE_BLOCK_SIZE_LOWER/UPPER_LIMIT`): 2\_000 and 130\_000. This is the limit on the estimated compressed size of a block when throttling is at maximum/minimum intensity respectively.
* Throttler controller type via `--throttle.controller-type` (env var `OP_BATCHER_THROTTLE_CONTROLLER_TYPE`): `quadratic` by default. This determines how transaction and block size limits are interpolated when throttling is at intermediate intensity.

For full details, see the [readme](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/readme.md).

If the batcher at startup has throttling enabled and the sequencer's `op-reth` node to which it's talking doesn't have the `miner_setMaxDASize` RPC enabled, it will fail with an error message like:

```
lvl=warn msg="Served miner_setMaxDASize" reqid=1 duration=11.22µs err="the method miner_setMaxDASize does not exist/is not available"
In this case, make sure the miner API namespace is enabled for the correct transport protocol (HTTP or WS), see next paragraph.
```

The `miner_setMaxDASize` RPC has to be enabled by adding the `miner` namespace to `op-reth`'s API flags:

```
--http.api=web3,debug,eth,txpool,net,miner
--ws.api=web3,debug,eth,txpool,net,miner
```

It is recommended to add it to both HTTP and WS.

## Example configuration

This is a basic example of a batcher configuration. Optimal batcher configuration is going to differ for each chain,
however you can see some of the most important variables configured below:

```
  OP_BATCHER_WAIT_NODE_SYNC: true
  OP_BATCHER_CHECK_RECENT_TXS_DEPTH: 5
  OP_BATCHER_POLL_INTERVAL: "5s"
  OP_BATCHER_BATCH_TYPE: "1" # span
  OP_BATCHER_COMPRESSION_ALGO: brotli-10
  OP_BATCHER_DATA_AVAILABILITY_TYPE: auto
  OP_BATCHER_MAX_CHANNEL_DURATION: "150" # up to 30 min to fill blobs
  OP_BATCHER_TARGET_NUM_FRAMES: "5" # 5 blobs, can go to 6 with Pectra activated on L1
  OP_BATCHER_SUB_SAFETY_MARGIN: "300" # 1h safety margin to prevent seq window elapse
  OP_BATCHER_NUM_CONFIRMATIONS: "4"
  OP_BATCHER_NETWORK_TIMEOUT: "10s"
  OP_BATCHER_TXMGR_MIN_BASEFEE: "2.0"
  OP_BATCHER_TXMGR_MIN_TIP_CAP: "2.0"
  OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER: 16 # allow up to 4 doublings
  OP_BATCHER_MAX_PENDING_TX: "10"
  OP_BATCHER_RESUBMISSION_TIMEOUT: "180s" # wait 3 min before bumping fees
  OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION: 5s
```

Lower throughput chains, which aren't filling up channels before the `MAX_CHANNEL_DURATION` is hit,
may save gas by increasing the `MAX_CHANNEL_DURATION`. See the [recommendations section](#set-your--op_batcher_max_channel_duration).


# Chain Operator Configurations
Source: https://docs.optimism.io/chain-operators/guides/configuration/getting-started

Learn how to configure an OP Stack chain.

OP Stack chains can be configured for the Chain Operator's needs.
Each component of the stack has its own considerations.
See the following for documentation for details on configuring each piece.

<Steps>
  <Step title="Rollup Configuration">
    Deploying your OP Stack contracts requires creating a deployment configuration
    JSON file. This defines the behavior of your network at its genesis.

    * **Important Notes:**
      * The Rollup Configuration sets parameters for the L1 smart contracts upon deployment. These parameters govern the behavior of your chain and are critical to its operation.
      * Be aware that many of these values cannot be changed after deployment or require a complex process to update.
        Carefully consider and validate all settings during configuration to avoid issues later.

    * [Rollup Deployment Configuration reference](/chain-operators/reference/rollup-deployment-configuration)
  </Step>

  <Step title="Batcher Configuration">
    The batcher is the service that submits the L2 Sequencer data to L1, to make
    it available for verifiers. These configurations determine the batcher's
    behavior.

    * [Batcher Configuration Documentation](/chain-operators/guides/configuration/batcher)
  </Step>

  <Step title="Proposer Configuration">
    The proposer is the service that submits the output roots to the L1. These
    configurations determine the proposer's behavior.

    * [Proposer Configuration Documentation](/chain-operators/guides/configuration/proposer)
  </Step>

  <Step title="Node Configuration">
    The rollup node has a wide array of configurations for both the consensus and
    execution clients.

    * [Consensus Client Configuration](/node-operators/guides/configuration/consensus-clients)
    * [Execution Client Configuration](/node-operators/guides/configuration/execution-clients)
  </Step>
</Steps>


# How to configure challenger for your chain
Source: https://docs.optimism.io/chain-operators/guides/configuration/op-challenger-config-guide

Learn how to configure challenger for your OP Stack chain.

This guide provides step-by-step instructions for setting up the configuration and monitoring options for `op-challenger`.

The challenger is a critical fault proofs component that monitors dispute games and challenges invalid claims to protect your OP Stack chain. See the [op-challenger explainer](/op-stack/fault-proofs/challenger) for a general overview of this fault proofs feature.

The challenger is responsible for:

* Monitoring dispute games created by the fault proof system
* Challenging invalid claims in dispute games
* Defending valid state transitions
* Resolving games when possible

For the complete catalog of flags, environment variables, and defaults, see the
[challenger configuration reference](/chain-operators/reference/challenger-configuration).

<Warning>
  **From the Karst upgrade, `cannon-kona` is the respected fault-proof game type, replacing op-program.** Configure `op-challenger` with the `cannon-kona` trace type and a kona-client absolute prestate. A challenger still running the `cannon` / op-program trace type past Karst will not defend your chain.
</Warning>

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

## Prerequisites

### Essential requirements

Before configuring your challenger, complete the following steps:

<Steps>
  <Step title="Deploy OP Stack chain with fault proofs enabled">
    * L1 contracts deployed with dispute game factory
    * Fault proof system active on your chain
    * Access to your chain's contract addresses
    * [Generate an absolute prestate](/chain-operators/tutorials/absolute-prestate#generating-the-absolute-prestate) for your network version - This is critical as the challenger will refuse to interact with games if it doesn't have the matching prestate
  </Step>

  <Step title="Set up required infrastructure access">
    * L1 RPC endpoint (Ethereum, Sepolia, etc.)
    * L1 Beacon node endpoint (for blob access)
    * L2 archive node with debug API enabled
    * Rollup node (op-node) with historical data
  </Step>

  <Step title="Prepare configuration files">
    * `rollup.json` - Rollup configuration file
    * `genesis-l2.json` - L2 genesis file
    * `prestate.json` - The absolute prestate file generated in step 1
  </Step>
</Steps>

### Software requirements

* Git (for cloning repositories)
* Go 1.21+ (if building from source)
* Docker and Docker Compose (optional but recommended)
* Access to a funded Ethereum account for challenger operations

### Finding the current stable releases

To ensure you're using the latest compatible versions of OP Stack components, always check the official releases page:

[OP Stack releases page](https://github.com/ethereum-optimism/optimism/releases)

This guide is verified against the following versions:

* **op-challenger** — `op-challenger/v1.9.4` (look for the latest `op-challenger/v*`).
* **op-reth** — `v2.2.5` (look for the latest [op-reth release](https://github.com/ethereum-optimism/optimism/releases?q=op-reth)). op-reth is both the sequencer's execution client and the archive node the challenger reads withdrawal proofs from.
* **kona-client** — the absolute prestate is built from a tagged `kona-client/v*` release (e.g. `kona-client/v1.6.0-rc.1`). Use the tag matching the prestate registered on your chain; for governance-approved upgrades the version is named in the upgrade notice. See the [kona-client prestate tutorial](/chain-operators/tutorials/kona-custom-prestate).

Always check the release notes to ensure you're using compatible versions with your chain's deployment. Using the op-challenger and kona-client versions named in the upgrade notice (or the latest matching releases) is the supported path.

## Software installation

For challenger deployment, you can either build from source (recommended for better control and debugging) or use Docker for a containerized setup.

<Tabs>
  <Tab title="Build from source">
    ### Build and configure

    Building from source gives you full control over the binaries and is the preferred approach for production deployments.

    **Clone and build op-challenger**

    ```bash theme={null}
    # Clone the optimism monorepo
    git clone https://github.com/ethereum-optimism/optimism.git
    cd optimism

    # Check out the latest release of op-challenger
    git checkout op-challenger/v1.9.4

    # Generate the embedded superchain config bundle (initializes the
    # superchain-registry submodule; op-challenger embeds this file at compile time)
    just build-superchain-go

    # Install dependencies and build
    just op-challenger

    # Build the Cannon VM binary used to run dispute traces
    just cannon

    # Binaries will be available at ./op-challenger/bin/op-challenger
    # and ./cannon/bin/cannon
    ```

    **Build kona-host**

    The challenger also needs `kona-host`, the pre-image oracle server for the `cannon-kona` game type. Build it from the kona-client release tag matching the absolute prestate registered on your chain (see [Finding the current stable releases](#finding-the-current-stable-releases)), so the server matches the `kona-client` build committed on chain:

    ```bash theme={null}
    # In a checkout of the tag your prestate was built from
    cd rust
    cargo build --release --bin kona-host

    # Binary will be available at ./rust/target/release/kona-host
    ```

    ### Verify installation

    Check that you have properly installed the challenger component:

    ```bash theme={null}
    # Make sure you're in the optimism directory
    ./op-challenger/bin/op-challenger --help

    # You should see the challenger help output with available commands and flags
    ```

    ## Configuration setup

    <Steps>
      <Step title="Organize your workspace">
        After building the binaries, create your challenger working directory:

        ```bash theme={null}
        # Create challenger directory (this should be at the same level as optimism directory)
        mkdir challenger-node
        cd challenger-node

        # Create necessary subdirectories
        mkdir scripts
        mkdir challenger-data

        # Verify the optimism directory is accessible
        # Directory structure should look like:
        # /optimism/                 (contains the built binaries)
        # /challenger-node/          (your working directory)
        ```
      </Step>

      <Step title="Copy configuration files">
        ```bash theme={null}
        # Copy configuration files to your challenger directory
        # Adjust paths based on your deployment setup
        cp /path/to/your/rollup.json .
        cp /path/to/your/genesis-l2.json .
        ```
      </Step>

      <Step title="Set up environment variables">
        You'll need to gather several pieces of information before creating your configuration. Here's where to get each value:

        **L1 network access:**

        * L1 RPC URL: Your L1 node endpoint (Infura, Alchemy, or self-hosted)
        * L1 Beacon URL: Beacon chain API endpoint for blob access

        **L2 network access:**

        * L2 RPC URL: Your op-reth archive node endpoint
        * Rollup RPC URL: Your op-node endpoint with historical data

        **Challenger wallet:**

        * Private key for challenger operations (must be funded)

        **Network configuration:**

        * Game factory address from your contract deployment
        * Network identifier (e.g., op-sepolia, op-mainnet, or custom)

        Copy and paste in your terminal, to create your env file.

        ```bash theme={null}
        # Create .env file with your actual values
        cat > .env << 'EOF'
        # L1 Configuration - Replace with your actual RPC URLs
        L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY

        # L2 Configuration - Replace with your actual node endpoints  
        L2_RPC_URL=http://localhost:8545
        ROLLUP_RPC_URL=http://localhost:8547
        L1_BEACON=http://sepolia-cl-1:5051

        # Wallet configuration - Choose either mnemonic + HD path OR private key
        MNEMONIC="test test test test test test test test test test test junk"
        HD_PATH="m/44'/60'/0'/0/0"
        # PRIVATE_KEY=0xYOUR_ACTUAL_PRIVATE_KEY  # Alternative to mnemonic

        # Network configuration
        NETWORK=op-sepolia
        GAME_FACTORY_ADDRESS=0xYOUR_GAME_FACTORY_ADDRESS

        # Trace configuration (cannon-kona is the respected game type from the Karst upgrade)
        TRACE_TYPE=permissioned,cannon-kona

        # Data directory
        DATADIR=./challenger-data

        # Cannon VM binary (shared by cannon and cannon-kona; built from the optimism repo)
        CANNON_BIN=<PATH_TO_OPTIMISM_REPO>/cannon/bin/cannon

        # Configuration files
        CANNON_ROLLUP_CONFIG=<PATH_TO_YOUR_ROLLUP_CONFIG>
        CANNON_L2_GENESIS=<PATH_TO_YOUR_L2_GENESIS>
        # kona executable used as the pre-image oracle server, and the kona-client absolute prestate
        CANNON_KONA_SERVER=<PATH_TO_KONA_EXECUTABLE>
        CANNON_KONA_PRESTATE=<PATH_TO_YOUR_KONA_PRESTATE_FILE>
        EOF
        ```

        **Important:** Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values.
      </Step>

      <Step title="Understanding key configuration flags">
        <Expandable title="--l1-eth-rpc">
          * This is the HTTP provider URL for a standard L1 node, can be a full node. `op-challenger` will be sending many requests, so chain operators need a node that is trusted and can easily handle many transactions.
          * Note: Challenger has a lot of money, and it will spend it if it needs to interact with games. That might risk not defending games or challenging games correctly, so chain operators should really trust the nodes being pointed at Challenger.
        </Expandable>

        <Expandable title="--l1-beacon">
          * This is needed just to get blobs from.
          * In some instances, chain operators might need a blob archiver or L1 consensus node configured not to prune blobs:
            * If the chain is proposing regularly, a blob archiver isn't needed. There's only a small window in the blob retention period that games can be played.
            * If the chain doesn't post a valid output root in 18 days, then a blob archiver running a challenge game is needed. If the actor gets pushed to the bottom of the game, it could lose if it's the only one protecting the chain.
        </Expandable>

        <Expandable title="--l2-eth-rpc">
          * This needs to be an `op-reth` archive node, with `debug` enabled.
          * Technically doesn't need to go to bedrock, but needs to have access to the start of any game that is still in progress.
          * The withdrawal-proof data the challenger reads via `eth_getProof` is served by op-reth's historical-proofs store. Enable it with `--proofs-history --proofs-history.storage-version v2`, set a persistent `--proofs-history.storage-path`, and size `--proofs-history.window` to cover the dispute game window (≥ 28 days). On permissioned chains, `--rpc.eth-proof-window` bounds how far back `eth_getProof` will serve. See [Running op-reth with historical proofs](/node-operators/tutorials/reth-historical-proofs).
          * **Seed the proofs storage once before starting the node with `--proofs-history`**, or op-reth refuses to start (the `proofs-history` ExEx panics with `Proofs storage not initialized`). With the node stopped, run `op-reth proofs init --chain <chain-or-genesis> --datadir <reth-datadir> --proofs-history.storage-path <proofs-db-path> --proofs-history.storage-version v2`. It snapshots the chain's current state to seed the sidecar; the ExEx then indexes forward as the node syncs. Initialize at (or near) genesis so the whole fault-proof window is covered — a node seeded at the current tip only serves proofs for blocks after that point.
        </Expandable>

        <Expandable title="--rollup-rpc">
          * This needs to be an `op-node` archive node because challenger needs access to output roots from back when the games start. See below for important configuration details:

          1. Safe Head Database (SafeDB) Configuration for op-node:

             * The `op-node` behind the `op-conductor` must have the SafeDB enabled to ensure it is not stateless.

             * To enable SafeDB, set the `--safedb.path` value in your configuration. This specifies the file path used to persist safe head update data.

             * Example Configuration:

               ```bash theme={null}
               --safedb.path <path-to-safe-head-db>   # Replace <path-to-safe-head-db> with your actual path
               ```

               <Info>
                 If this path is not set, the SafeDB feature will be disabled.
               </Info>

             <Warning>
               **Never restore the SafeDB from a snapshot.** The SafeDB records the safe head as derived from L1, and a snapshot may not reflect the actual on-chain derivation state. If the SafeDB is out of sync with L1, `op-challenger` will act on an incorrect safe head and may incorrectly attack valid outputs. `op-challenger` cannot detect this condition — the data it receives appears normal. If you suspect the SafeDB was restored from a snapshot or is otherwise corrupted, delete it and resync from a snapshot that is at least 30 days old — `op-node` does not backfill the SafeDB, so it will only populate it going forward from that point. A 30-day-old snapshot provides enough history to cover the 28-day dispute game window.
             </Warning>

          2. Ensuring Historical Data Availability:

             * Both `op-node` and `op-reth` must have data from the start of the games to maintain network consistency and allow nodes to reference historical state and transactions.
             * For `op-node`: Configure it to maintain a sufficient history of blockchain data locally or use an archive node.
             * For `op-reth`: Similarly, configure to store or access historical data.
             * Example Configuration:

               ```bash theme={null}
               op-node \
               --rollup-rpc <op-node-archive-node-url> \
               --safedb.path <path-to-safe-head-db>
               ```

             <Info>
               Replace `<op-node-archive-node-url>` with the URL of your archive node and `<path-to-safe-head-db>` with the desired path for storing SafeDB data.
             </Info>
        </Expandable>

        <Expandable title="--private-key">
          * Chain operators must specify a private key or use something else (like `op-signer`).
          * This uses the same transaction manager arguments as `op-node` , batcher, and proposer, so chain operators can choose one of the following options:
            * a mnemonic
            * a private key
            * `op-signer` endpoints
        </Expandable>

        <Expandable title="--network">
          * This identifies the L2 network `op-challenger` is running for, e.g., `op-sepolia` or `op-mainnet`.
          * When using the `--network` flag, the `--game-factory-address` will be automatically pulled from the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json).
          * When the trace is generated, challenger needs the rollup config and the L2 genesis file. Both files are automatically loaded when a registry `--network` is used, but custom networks must specify both the L2 genesis and rollup config.
          * For custom networks not in the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json), the `--game-factory-address` and rollup must be specified, as follows:

            ```bash theme={null}
            --cannon-kona-rollup-config rollup.json  \
            --cannon-kona-l2-genesis genesis-l2.json \
            # use this if running challenger outside of the docker image
            --cannon-kona-server ./kona \
            # version of kona-client deployed on chain
            # if you use the wrong one, you will lose the game
            # if you deploy your own contracts, you specify the hash, the root of the json file
            # OP Mainnet uses tagged versions of kona-client
            # build with: just reproducible-prestate-kona
            # challenger verifies that onchain
             --cannon-kona-prestate ./prestate.json \
            # load the game factory address from system config or superchain registry
            # point the game factory address at the dispute game factory proxy
             --game-factory-address
            ```

          <Info>
            These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the `--cannon-kona-server` whenever the docker image isn't being used.
          </Info>
        </Expandable>

        <Expandable title="--datadir">
          * This is a directory that `op-challenger` can write to and store whatever data it needs.  It will manage this directory to add or remove data as needed under that directory.
          * If running in docker, it should point to a docker volume or mount point, so the data isn't lost on every restart. The data can be recreated if needed but particularly if challenger has executed cannon as part of responding to a game it may mean a lot of extra processing.
        </Expandable>

        <Expandable title="--cannon-kona-prestate / --cannon-kona-prestates-url">
          The prestate is effectively the version of `kona-client` that is deployed on chain (run inside the Cannon VM as the `cannon-kona` game type). And chain operators must use the right version. `op-challenger` will refuse to interact with games that have a different absolute prestate hash to avoid making invalid claims. If deploying your own contracts, chain operators must specify an absolute prestate hash taken from the `just reproducible-prestate-kona` command during contract deployment, which will also build the required prestate file.

          All governance approved releases use a tagged version of `kona-client`. These can be rebuilt by checking out the version tag and running `just reproducible-prestate-kona`.

          * There are two ways to specify the prestate to use:
            * `--cannon-kona-prestate`: specifies a path to a single kona-client absolute-prestate file
            * `--cannon-kona-prestates-url`: specifies a URL to load prestates from. This enables participating in games that use different prestates, for example due to a network upgrade. The prestates are stored in this directory named by their hash.
          * Example final URL for a prestate:
            * [https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json](https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json)
            * This file contains the cannon memory state.

          <Info>
            Challenger will refuse to interact with any games if it doesn't have the matching prestate.
            Check this [guide](/chain-operators/tutorials/absolute-prestate#generating-the-absolute-prestate) on how to generate a absolute prestate.
          </Info>
        </Expandable>
      </Step>
    </Steps>

    ### Create challenger startup script

    Create `scripts/start-challenger.sh`:

    ```bash theme={null}
    #!/bin/bash
    source .env

    # Path to the challenger binary
    ../optimism/op-challenger/bin/op-challenger \
      --trace-type permissioned,cannon-kona \
      --l1-eth-rpc=$L1_RPC_URL \
      --l2-eth-rpc=$L2_RPC_URL \
      --l1-beacon=$L1_BEACON \
      --rollup-rpc=$ROLLUP_RPC_URL \
      --game-factory-address $GAME_FACTORY_ADDRESS \
      --datadir=$DATADIR \
      --cannon-bin=$CANNON_BIN \
      --cannon-kona-rollup-config=$CANNON_ROLLUP_CONFIG \
      --cannon-kona-l2-genesis=$CANNON_L2_GENESIS \
      --cannon-kona-server=$CANNON_KONA_SERVER \
      --cannon-kona-prestate=$CANNON_KONA_PRESTATE \
      --mnemonic "$MNEMONIC" \
      --hd-path "$HD_PATH"
    ```

    ## Initializing and starting the challenger

    ### Start the challenger

    ```bash theme={null}
    # Make sure you're in the challenger-node directory
    cd challenger-node

    # Make script executable
    chmod +x scripts/start-challenger.sh

    # Start challenger
    ./scripts/start-challenger.sh
    ```

    ### Verify challenger is running

    Monitor challenger logs to ensure it's operating correctly:

    ```bash theme={null}
    # Check challenger logs
    tail -f challenger-data/challenger.log

    # Or if running in foreground, monitor the output
    ```

    The challenger should show logs indicating:

    * Successful connection to L1 and L2 nodes
    * Loading of prestates and configuration
    * Monitoring of dispute games
  </Tab>

  <Tab title="Use docker">
    ### Docker setup

    The Docker setup provides a containerized environment for running the challenger. This method uses the official Docker image that includes the embedded `kona` server and Cannon executable.

    <Steps>
      <Step title="Create environment file">
        First, create a `.env` file with your configuration values. This file will be used by Docker Compose to set up the environment variables:

        ```bash theme={null}
        # Create .env file with your actual values
        cat > .env << 'EOF'
        # L1 Configuration - Replace with your actual RPC URLs
        L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY
        L1_BEACON=http://sepolia-cl-1:5051

        # L2 Configuration - Replace with your actual node endpoints  
        L2_RPC_URL=http://localhost:8545
        ROLLUP_RPC_URL=http://localhost:8547

        # Wallet configuration - Choose either mnemonic + HD path OR private key
        MNEMONIC="test test test test test test test test test test test junk"
        HD_PATH="m/44'/60'/0'/0/0"

        # Network configuration
        NETWORK=op-sepolia
        GAME_FACTORY_ADDRESS=0xYOUR_GAME_FACTORY_ADDRESS
        EOF
        ```

        **Important:** Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values.
      </Step>

      <Step title="Understanding configuration flags">
        Each environment variable maps to a specific challenger configuration flag. Here's what each one does:

        <Expandable title="--l1-eth-rpc">
          * This is the HTTP provider URL for a standard L1 node, can be a full node. `op-challenger` will be sending many requests, so chain operators need a node that is trusted and can easily handle many transactions.
          * Note: Challenger has a lot of money, and it will spend it if it needs to interact with games. That might risk not defending games or challenging games correctly, so chain operators should really trust the nodes being pointed at Challenger.
        </Expandable>

        <Expandable title="--l1-beacon">
          * This is needed just to get blobs from.
          * In some instances, chain operators might need a blob archiver or L1 consensus node configured not to prune blobs:
            * If the chain is proposing regularly, a blob archiver isn't needed. There's only a small window in the blob retention period that games can be played.
            * If the chain doesn't post a valid output root in 18 days, then a blob archiver running a challenge game is needed. If the actor gets pushed to the bottom of the game, it could lose if it's the only one protecting the chain.
        </Expandable>

        <Expandable title="--l2-eth-rpc">
          * This needs to be an `op-reth` archive node, with `debug` enabled.
          * Technically doesn't need to go to bedrock, but needs to have access to the start of any game that is still in progress.
          * The withdrawal-proof data the challenger reads via `eth_getProof` is served by op-reth's historical-proofs store. Enable it with `--proofs-history --proofs-history.storage-version v2`, set a persistent `--proofs-history.storage-path`, and size `--proofs-history.window` to cover the dispute game window (≥ 28 days). On permissioned chains, `--rpc.eth-proof-window` bounds how far back `eth_getProof` will serve. See [Running op-reth with historical proofs](/node-operators/tutorials/reth-historical-proofs).
          * **Seed the proofs storage once before starting the node with `--proofs-history`**, or op-reth refuses to start (the `proofs-history` ExEx panics with `Proofs storage not initialized`). With the node stopped, run `op-reth proofs init --chain <chain-or-genesis> --datadir <reth-datadir> --proofs-history.storage-path <proofs-db-path> --proofs-history.storage-version v2`. It snapshots the chain's current state to seed the sidecar; the ExEx then indexes forward as the node syncs. Initialize at (or near) genesis so the whole fault-proof window is covered — a node seeded at the current tip only serves proofs for blocks after that point.
        </Expandable>

        <Expandable title="--rollup-rpc">
          * This needs to be an `op-node` archive node because challenger needs access to output roots from back when the games start. See below for important configuration details:

          1. Safe Head Database (SafeDB) Configuration for op-node:

             * The `op-node` behind the `op-conductor` must have the SafeDB enabled to ensure it is not stateless.

             * To enable SafeDB, set the `--safedb.path` value in your configuration. This specifies the file path used to persist safe head update data.

             * Example Configuration:

               ```bash theme={null}
               --safedb.path <path-to-safe-head-db>   # Replace <path-to-safe-head-db> with your actual path
               ```

               <Info>
                 If this path is not set, the SafeDB feature will be disabled.
               </Info>

             <Warning>
               **Never restore the SafeDB from a snapshot.** The SafeDB records the safe head as derived from L1, and a snapshot may not reflect the actual on-chain derivation state. If the SafeDB is out of sync with L1, `op-challenger` will act on an incorrect safe head and may incorrectly attack valid outputs. `op-challenger` cannot detect this condition — the data it receives appears normal. If you suspect the SafeDB was restored from a snapshot or is otherwise corrupted, delete it and resync via consensus sync from a snapshot that is at least 30 days old — `op-node` does not backfill the SafeDB, so it will only populate it going forward from that point. A 30-day-old snapshot provides enough history to cover the 28-day dispute game window.
             </Warning>

          2. Ensuring Historical Data Availability:

             * Both `op-node` and `op-reth` must have data from the start of the games to maintain network consistency and allow nodes to reference historical state and transactions.
             * For `op-node`: Configure it to maintain a sufficient history of blockchain data locally or use an archive node.
             * For `op-reth`: Similarly, configure to store or access historical data.
             * Example Configuration:

               ```bash theme={null}
               op-node \
               --rollup-rpc <op-node-archive-node-url> \
               --safedb.path <path-to-safe-head-db>
               ```

             <Info>
               Replace `<op-node-archive-node-url>` with the URL of your archive node and `<path-to-safe-head-db>` with the desired path for storing SafeDB data.
             </Info>
        </Expandable>

        <Expandable title="--private-key">
          * Chain operators must specify a private key or use something else (like `op-signer`).
          * This uses the same transaction manager arguments as `op-node` , batcher, and proposer, so chain operators can choose one of the following options:
            * a mnemonic
            * a private key
            * `op-signer` endpoints
        </Expandable>

        <Expandable title="--network">
          * This identifies the L2 network `op-challenger` is running for, e.g., `op-sepolia` or `op-mainnet`.
          * When using the `--network` flag, the `--game-factory-address` will be automatically pulled from the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json).
          * When the trace is generated, challenger needs the rollup config and the L2 genesis file. Both files are automatically loaded when a registry `--network` is used, but custom networks must specify both the L2 genesis and rollup config.
          * For custom networks not in the [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json), the `--game-factory-address` and rollup must be specified, as follows:

            ```bash theme={null}
            --cannon-kona-rollup-config rollup.json  \
            --cannon-kona-l2-genesis genesis-l2.json \
            # use this if running challenger outside of the docker image
            --cannon-kona-server ./kona \
            # version of kona-client deployed on chain
            # if you use the wrong one, you will lose the game
            # if you deploy your own contracts, you specify the hash, the root of the json file
            # OP Mainnet uses tagged versions of kona-client
            # build with: just reproducible-prestate-kona
            # challenger verifies that onchain
             --cannon-kona-prestate ./prestate.json \
            # load the game factory address from system config or superchain registry
            # point the game factory address at the dispute game factory proxy
             --game-factory-address
            ```

          <Info>
            These options vary based on which `--network` is specified. Chain operators always need to specify a way to load prestates and must also specify the `--cannon-kona-server` whenever the docker image isn't being used.
          </Info>
        </Expandable>

        <Expandable title="--datadir">
          * This is a directory that `op-challenger` can write to and store whatever data it needs.  It will manage this directory to add or remove data as needed under that directory.
          * If running in docker, it should point to a docker volume or mount point, so the data isn't lost on every restart. The data can be recreated if needed but particularly if challenger has executed cannon as part of responding to a game it may mean a lot of extra processing.
        </Expandable>

        <Expandable title="--cannon-kona-prestate / --cannon-kona-prestates-url">
          The prestate is effectively the version of `kona-client` that is deployed on chain (run inside the Cannon VM as the `cannon-kona` game type). And chain operators must use the right version. `op-challenger` will refuse to interact with games that have a different absolute prestate hash to avoid making invalid claims. If deploying your own contracts, chain operators must specify an absolute prestate hash taken from the `just reproducible-prestate-kona` command during contract deployment, which will also build the required prestate file.

          All governance approved releases use a tagged version of `kona-client`. These can be rebuilt by checking out the version tag and running `just reproducible-prestate-kona`.

          * There are two ways to specify the prestate to use:
            * `--cannon-kona-prestate`: specifies a path to a single kona-client absolute-prestate file
            * `--cannon-kona-prestates-url`: specifies a URL to load prestates from. This enables participating in games that use different prestates, for example due to a network upgrade. The prestates are stored in this directory named by their hash.
          * Example final URL for a prestate:
            * [https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json](https://example.com/prestates/0x031e3b504740d0b1264e8cf72b6dde0d497184cfb3f98e451c6be8b33bd3f808.json)
            * This file contains the cannon memory state.

          <Info>
            Challenger will refuse to interact with any games if it doesn't have the matching prestate.
            Check this [guide](/chain-operators/tutorials/absolute-prestate#generating-the-absolute-prestate) on how to generate a absolute prestate.
          </Info>
        </Expandable>
      </Step>

      <Step title="Set up Docker Compose">
        Create a `docker-compose.yml` file that defines the challenger service:

        ```yaml theme={null}
        version: '3.8'

        services:
          challenger:
            image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v1.9.4
            user: "1000"
            volumes:
              - ./challenger-data:/data
              - ./rollup.json:/workspace/rollup.json:ro
              - ./genesis-l2.json:/workspace/genesis-l2.json:ro
            environment:
              - L1_RPC_URL=${L1_RPC_URL}
              - L1_BEACON=${L1_BEACON}
              - L2_RPC_URL=${L2_RPC_URL}
              - ROLLUP_RPC_URL=${ROLLUP_RPC_URL}
              - MNEMONIC=${MNEMONIC}
              - HD_PATH=${HD_PATH}
              - NETWORK=${NETWORK}
              - GAME_FACTORY_ADDRESS=${GAME_FACTORY_ADDRESS}
            command:
              - "op-challenger"
              - "--l1-eth-rpc=${L1_RPC_URL}"
              - "--l1-beacon=${L1_BEACON}"
              - "--l2-eth-rpc=${L2_RPC_URL}"
              - "--rollup-rpc=${ROLLUP_RPC_URL}"
              - "--selective-claim-resolution"
              - "--mnemonic=${MNEMONIC}"
              - "--hd-path=${HD_PATH}"
              - "--network=${NETWORK}"
              - "--game-factory-address=${GAME_FACTORY_ADDRESS}"
              - "--datadir=/data"
              - "--trace-type=cannon-kona"
              - "--cannon-kona-prestate=/workspace/prestate-proof.json"
            restart: unless-stopped
            ports:
              - "8548:8548"  # If challenger exposes metrics endpoint
        ```
      </Step>

      <Step title="Launch the challenger">
        Start the challenger service and monitor its logs:

        ```bash theme={null}
        # Start the challenger service
        docker-compose up -d

        # View logs
        docker-compose logs -f challenger
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Monitoring with op-dispute-mon

Consider running [`op-dispute-mon`](/chain-operators/tools/chain-monitoring#dispute-mon) for enhanced security monitoring:

* Provides visibility into all game statuses for the last 28 days
* Essential for production challenger deployments

## Next steps

* Read the [OP-Challenger Explainer](/op-stack/fault-proofs/challenger) for additional context and FAQ
* Review the detailed [challenger specifications](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html) for implementation details
* If you experience any problems, reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions)


# Proposer Configuration
Source: https://docs.optimism.io/chain-operators/guides/configuration/proposer

Reference for the op-proposer configuration options and the proposer policy constraints.

This page lists all configuration options for op-proposer. The op-proposer posts
output roots (proposals) to L1, making them available for verifiers. Withdrawals to L1 must reference an output root.
If the chain is running permissioned fault proofs, only the [designated proposer](/op-stack/protocol/privileged-roles) can submit output roots.
With [permissionless fault proofs](/op-stack/fault-proofs/explainer), anyone can make a proposal.

## Proposer policy

The proposer policy defines high-level constraints and responsibilities regarding how L2 output roots are posted to L1. Below are the [standard guidelines](/op-stack/protocol/superchain-registry#what-is-a-standard-chain) for configuring the proposer within the OP Stack.

| Parameter        | Description                                                                         | Administrator  | Requirement                                                | Notes                                                           |
| ---------------- | ----------------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------- | --------------------------------------------------------------- |
| Output Frequency | Defines how frequently L2 output roots are submitted to L1 (via the output oracle). | L1 Proxy Admin | **43,200 L2 blocks** (24 hours at 2s block times) or lower | It cannot be set to 0 (there must be some cadence for outputs). |

### Example configuration

```
OP_PROPOSER_L1_ETH_RPC: YOUR_L1_RPC_URL_HERE
OP_PROPOSER_ROLLUP_RPC: YOUR_CHAINS_RPC_URL_HERE
OP_PROPOSER_GAME_FACTORY_ADDRESS: YOUR_CHAINS_GAME_FACTORY_ADDRESS_HERE
OP_PROPOSER_PROPOSAL_INTERVAL: 5h
OP_PROPOSER_WAIT_NODE_SYNC: true
OP_PROPOSER_ALLOW_NON_FINALIZED: "false"
OP_PROPOSER_POLL_INTERVAL: "20s"
OP_PROPOSER_NUM_CONFIRMATIONS: "1"
OP_PROPOSER_SAFE_ABORT_NONCE_TOO_LOW_COUNT: "3"
OP_PROPOSER_RESUBMISSION_TIMEOUT: "30s"
OP_PROPOSER_METRICS_ENABLED: "true"
OP_PROPOSER_METRICS_ADDR: 0.0.0.0
OP_PROPOSER_METRICS_PORT: 7300
```

Higher throughput chains can decrease the `proposal-interval` to allow users submit withdrawals more often.

## Flags

<ConfigReferencePreamble />

Generated from [`op-proposer/v1.16.3`](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer%2Fv1.16.3)
flag definitions. 54 flags: 1 required, 53 optional.

### Required flags

| Flag           | Description              | Environment variable     |
| -------------- | ------------------------ | ------------------------ |
| `--l1-eth-rpc` | HTTP provider URL for L1 | `OP_PROPOSER_L1_ETH_RPC` |

### Optional flags

| Flag                                    | Description                                                                                                                                                                                                                 | Default                | Environment variable                              |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------------------------------- |
| `--active-sequencer-check-duration`     | The duration between checks to determine the active sequencer endpoint.                                                                                                                                                     | `2m0s`                 | `OP_PROPOSER_ACTIVE_SEQUENCER_CHECK_DURATION`     |
| `--allow-non-finalized`                 | Allow the proposer to submit proposals for L2 blocks derived from non-finalized L1 blocks.                                                                                                                                  | `false`                | `OP_PROPOSER_ALLOW_NON_FINALIZED`                 |
| `--fee-limit-multiplier`                | The multiplier applied to fee suggestions to put a hard limit on fee increases                                                                                                                                              | `5`                    | `OP_PROPOSER_TXMGR_FEE_LIMIT_MULTIPLIER`          |
| `--game-factory-address`                | Address of the DisputeGameFactory contract                                                                                                                                                                                  | —                      | `OP_PROPOSER_GAME_FACTORY_ADDRESS`                |
| `--game-type`                           | Dispute game type to create via the configured DisputeGameFactory                                                                                                                                                           | `0`                    | `OP_PROPOSER_GAME_TYPE`                           |
| `--hd-path`                             | The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic flag must also be set.                                                                                                                      | —                      | `OP_PROPOSER_HD_PATH`                             |
| `--l2-output-hd-path`                   | DEPRECATED:The HD path used to derive the l2output wallet from the mnemonic. The mnemonic flag must also be set.                                                                                                            | —                      | `OP_PROPOSER_L2_OUTPUT_HD_PATH`                   |
| `--log.color`                           | Color the log output if in terminal mode                                                                                                                                                                                    | `false`                | `OP_PROPOSER_LOG_COLOR`                           |
| `--log.format`                          | Format the log output. Supported formats: text, terminal, logfmt, logfmtms, json, jsonms                                                                                                                                    | `text`                 | `OP_PROPOSER_LOG_FORMAT`                          |
| `--log.level`                           | The lowest log level that will be output                                                                                                                                                                                    | `INFO`                 | `OP_PROPOSER_LOG_LEVEL`                           |
| `--log.pid`                             | Show pid in the log                                                                                                                                                                                                         | `false`                | `OP_PROPOSER_LOG_PID`                             |
| `--metrics.addr`                        | Metrics listening address                                                                                                                                                                                                   | `"0.0.0.0"`            | `OP_PROPOSER_METRICS_ADDR`                        |
| `--metrics.enabled`                     | Enable the metrics server                                                                                                                                                                                                   | `false`                | `OP_PROPOSER_METRICS_ENABLED`                     |
| `--metrics.port`                        | Metrics listening port                                                                                                                                                                                                      | `7300`                 | `OP_PROPOSER_METRICS_PORT`                        |
| `--mnemonic`                            | The mnemonic used to derive the wallets for either the service                                                                                                                                                              | —                      | `OP_PROPOSER_MNEMONIC`                            |
| `--network-timeout`                     | Timeout for all network operations                                                                                                                                                                                          | `10s`                  | `OP_PROPOSER_NETWORK_TIMEOUT`                     |
| `--num-confirmations`                   | Number of confirmations which we will wait after sending a transaction                                                                                                                                                      | `10`                   | `OP_PROPOSER_NUM_CONFIRMATIONS`                   |
| `--poll-interval`                       | Delay between periodic checks on whether it is time to load an output root and propose it.                                                                                                                                  | `12s`                  | `OP_PROPOSER_POLL_INTERVAL`                       |
| `--pprof.addr`                          | pprof listening address                                                                                                                                                                                                     | `"0.0.0.0"`            | `OP_PROPOSER_PPROF_ADDR`                          |
| `--pprof.enabled`                       | Enable the pprof server                                                                                                                                                                                                     | `false`                | `OP_PROPOSER_PPROF_ENABLED`                       |
| `--pprof.path`                          | pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof                                                                                                                                               | —                      | `OP_PROPOSER_PPROF_PATH`                          |
| `--pprof.port`                          | pprof listening port                                                                                                                                                                                                        | `6060`                 | `OP_PROPOSER_PPROF_PORT`                          |
| `--pprof.type`                          | pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs                                                                                                                                         | —                      | `OP_PROPOSER_PPROF_TYPE`                          |
| `--private-key`                         | The private key to use with the service. Must not be used with mnemonic.                                                                                                                                                    | —                      | `OP_PROPOSER_PRIVATE_KEY`                         |
| `--proposal-interval`                   | Interval between submitting L2 output proposals when the dispute game factory address is set                                                                                                                                | `0s`                   | `OP_PROPOSER_PROPOSAL_INTERVAL`                   |
| `--resubmission-timeout`                | Duration we will wait before resubmitting a transaction to L1                                                                                                                                                               | `48s`                  | `OP_PROPOSER_RESUBMISSION_TIMEOUT`                |
| `--rollup-rpc`                          | HTTP provider URL for the rollup node. A comma-separated list enables the active rollup provider.                                                                                                                           | —                      | `OP_PROPOSER_ROLLUP_RPC`                          |
| `--rpc.addr`                            | rpc listening address                                                                                                                                                                                                       | `"0.0.0.0"`            | `OP_PROPOSER_RPC_ADDR`                            |
| `--rpc.enable-admin`                    | Enable the admin API                                                                                                                                                                                                        | `false`                | `OP_PROPOSER_RPC_ENABLE_ADMIN`                    |
| `--rpc.port`                            | rpc listening port                                                                                                                                                                                                          | `8545`                 | `OP_PROPOSER_RPC_PORT`                            |
| `--safe-abort-nonce-too-low-count`      | Number of ErrNonceTooLow observations required to give up on a tx at a particular nonce without receiving confirmation                                                                                                      | `3`                    | `OP_PROPOSER_SAFE_ABORT_NONCE_TOO_LOW_COUNT`      |
| `--signer.address`                      | Address the signer is signing requests for                                                                                                                                                                                  | —                      | `OP_PROPOSER_SIGNER_ADDRESS`                      |
| `--signer.endpoint`                     | Signer endpoint the client will connect to                                                                                                                                                                                  | —                      | `OP_PROPOSER_SIGNER_ENDPOINT`                     |
| `--signer.header`                       | Headers to pass to the remote signer. Format `key=value`. Value can contain any character allowed in a HTTP header. When using env vars, split with commas. When using flags one key value pair per flag.                   | —                      | `OP_PROPOSER_SIGNER_HEADER`                       |
| `--signer.tls.ca`                       | tls ca cert path                                                                                                                                                                                                            | `"tls/ca.crt"`         | `OP_PROPOSER_SIGNER_TLS_CA`                       |
| `--signer.tls.cert`                     | tls cert path                                                                                                                                                                                                               | `"tls/tls.crt"`        | `OP_PROPOSER_SIGNER_TLS_CERT`                     |
| `--signer.tls.enabled`                  | Enable or disable TLS client authentication for the signer                                                                                                                                                                  | `true`                 | `OP_PROPOSER_SIGNER_TLS_ENABLED`                  |
| `--signer.tls.key`                      | tls key                                                                                                                                                                                                                     | `"tls/tls.key"`        | `OP_PROPOSER_SIGNER_TLS_KEY`                      |
| `--supernode-rpcs`                      | HTTP provider URLs for the supernode instances. Multiple URLs can be provided to automatically fail over.                                                                                                                   | —                      | `OP_PROPOSER_SUPERNODE_RPCS`                      |
| `--txmgr.already-published-custom-errs` | List of custom RPC error messages that indicate that a transaction has already been published.                                                                                                                              | —                      | `OP_PROPOSER_TXMGR_ALREADY_PUBLISHED_CUSTOM_ERRS` |
| `--txmgr.cell-proof-time`               | Enables cell proofs in blob transactions for Fusaka (EIP-7742) compatibility from the provided unix timestamp. Should be set to the L1 Fusaka time. May be left blank for Ethereum Mainnet, Sepolia, Holesky, or Hoodi L1s. | `18446744073709551615` | `OP_PROPOSER_TXMGR_CELL_PROOF_TIME`               |
| `--txmgr.fee-limit-threshold`           | The minimum threshold (in GWei) at which fee bumping starts to be capped. Allows arbitrary fee bumps below this threshold.                                                                                                  | `100`                  | `OP_PROPOSER_TXMGR_FEE_LIMIT_THRESHOLD`           |
| `--txmgr.max-basefee`                   | Enforces a maximum base fee (in GWei) to assume when determining tx fees, `TxMgr` returns an error when exceeded. Disabled by default.                                                                                      | `0`                    | `OP_PROPOSER_TXMGR_MAX_BASEFEE`                   |
| `--txmgr.max-retries`                   | Maximum number of times to resubmit a transaction to L1 on a transient error. Set to 0 to disable retries.                                                                                                                  | `10`                   | `OP_PROPOSER_TXMGR_MAX_RETRIES`                   |
| `--txmgr.max-tip-cap`                   | Enforces a maximum tip cap (in GWei) to use when determining tx fees, `TxMgr` returns an error when exceeded. Disabled by default.                                                                                          | `0`                    | `OP_PROPOSER_TXMGR_MAX_TIP_CAP`                   |
| `--txmgr.min-basefee`                   | Enforces a minimum base fee (in GWei) to assume when determining tx fees. 1 GWei by default.                                                                                                                                | `1`                    | `OP_PROPOSER_TXMGR_MIN_BASEFEE`                   |
| `--txmgr.min-tip-cap`                   | Enforces a minimum tip cap (in GWei) to use when determining tx fees. 1 GWei by default.                                                                                                                                    | `1`                    | `OP_PROPOSER_TXMGR_MIN_TIP_CAP`                   |
| `--txmgr.not-in-mempool-timeout`        | Timeout for aborting a tx send if the tx does not make it to the mempool.                                                                                                                                                   | `2m0s`                 | `OP_PROPOSER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT`     |
| `--txmgr.rebroadcast-interval`          | Interval at which a published transaction will be rebroadcasted if it has not yet been mined. Should be less than ResubmissionTimeout to have an effect.                                                                    | `12s`                  | `OP_PROPOSER_TXMGR_REBROADCAST_INTERVAL`          |
| `--txmgr.receipt-query-interval`        | Frequency to poll for receipts                                                                                                                                                                                              | `12s`                  | `OP_PROPOSER_TXMGR_RECEIPT_QUERY_INTERVAL`        |
| `--txmgr.retry-interval`                | Duration we will wait before resubmitting a transaction to L1 on a transient error. Values \<= 0 will result in retrying immediately. Should be less than ResubmissionTimeout to have an effect.                            | `1s`                   | `OP_PROPOSER_TXMGR_RETRY_INTERVAL`                |
| `--txmgr.send-timeout`                  | Timeout for sending transactions. If 0 it is disabled.                                                                                                                                                                      | `0s`                   | `OP_PROPOSER_TXMGR_TX_SEND_TIMEOUT`               |
| `--wait-node-sync`                      | Indicates if, during startup, the proposer should wait for the rollup node to sync to the current L1 tip before proceeding with its driver loop.                                                                            | `false`                | `OP_PROPOSER_WAIT_NODE_SYNC`                      |


# How to run an Alt-DA mode chain
Source: https://docs.optimism.io/chain-operators/guides/features/alt-da-mode-guide

Learn how to configure and run an Alt-DA mode chain within the OP Stack.

<Info>
  The Alt-DA Mode feature is currently in <strong>Beta</strong>  within the MIT-licensed OP Stack. Beta features are built and reviewed by core contributors, and provide developers with early access to highly requested configurations.
  These features may experience stability issues, and we encourage feedback from our early users.
</Info>

This guide provides a walkthrough for chain operators who want to run an Alt-DA Mode chain. See the [Alt-DA Mode Explainer](/op-stack/features/experimental/alt-da-mode) for a general overview of this OP Stack configuration.
An Alt-DA Mode OP Stack chain enables a chain operator to post and read data to any alternative data availability layer that has built a functioning OP Stack DA Server.

<Info>
  This page includes providers that meet specific [inclusion criteria](#inclusion-criteria), as outlined below.
</Info>

## Prerequisite

You should use at least the following compatible op\* versions when running your chain.

* op-node/v1.9.1
* op-proposer/v1.9.1
* op-batcher/v1.9.1
* Latest version of op-reth (see the [execution clients guide](/node-operators/guides/configuration/execution-clients))

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

<Steps>
  <Step title="Setup your DA server">
    <Info>
      DA Servers are not built or maintained by core contributors. DA servers are maintained by third parties and run at your own risk. Please reach out to the team who built the DA Server you are trying to run with any questions or issues.
    </Info>

    * Celestia's docs on how to run the [Celestia DA server](https://github.com/celestiaorg/op-plasma-celestia/blob/main/README.md)
    * EigenDA's docs on how to run the [EigenDA DA server](https://github.com/Layr-Labs/op-plasma-eigenda/blob/main/README.md)
    * Avail's docs on how to run the [AvailDA DA Server](https://docs.availproject.org/docs/build-with-avail/deploy-rollup-on-avail/Optimium)
    * 0gDA's docs on how to run the [0gDA DA Server](https://github.com/0glabs/0g-da-op-plasma)
    * Near DA's docs on how to run the [Near DA Server](https://github.com/Nuffle-Labs/data-availability/blob/84b484de98f58a91bf12c8abe8df27f5e753f63a/docs/OP-Alt-DA.md)
  </Step>

  <Step title="Configure your `op-node`">
    * Spin up your OP chain as usual but set `--altda.enabled=true` and point both `op-batcher` and `op-node` to the DA server.
    * No configuration changes are required for your execution client (`op-reth`) or `op-proposer`.

    ```
       Alt-DA (EXPERIMENTAL)

       
        --altda.da-server value                                               ($OP_NODE_ALTDA_DA_SERVER)
              HTTP address of a DA Server
       
        --altda.enabled                    (default: false)                   ($OP_NODE_ALTDA_ENABLED)
              Enable Alt-DA mode
       
        --altda.verify-on-read             (default: true)                    ($OP_NODE_ALTDA_VERIFY_ON_READ)
              Verify input data matches the commitments from the DA storage service

    ```
  </Step>

  <Step title="Configure your batcher">
    * Set `--altda.enabled=true` and `--altda.da-service=true`.
    * Provide the URL for `--altda.da-server=$DA_SERVER_HTTP_URL`.

    ```
        --altda.da-server value                                               ($OP_BATCHER_ALTDA_DA_SERVER)
              HTTP address of a DA Server
       
        --altda.da-service                 (default: false)                   ($OP_BATCHER_ALTDA_DA_SERVICE)
              Use DA service type where commitments are generated by the DA server
       
        --altda.enabled                    (default: false)                   ($OP_BATCHER_ALTDA_ENABLED)
              Enable Alt-DA mode
       
        --altda.verify-on-read             (default: true)                    ($OP_BATCHER_ALTDA_VERIFY_ON_READ)
              Verify input data matches the commitments from the DA storage service
    ```

    After completing steps 1-3 above, you will have an Alt-DA mode chain up and running.
  </Step>

  <Step title="Set your fee configuration">
    * Chain operators are not posting everything to Ethereum, just commitments, so chain operators will need to determine fee scalars values to charge users. The fee scalar values are network throughput dependent, so values will need to be adjusted by chain operators as needed.
    * Cost structure for Alt-DA Mode: The transaction data is split up into 128kb chunks and then submitted to your DA Layer. Then, 32 byte commitments are submitted (goes to batch inbox address) to L1 for each 128kb chunk. Then, figure out how much that costs relative to the number of transactions your chain is putting through.
    * Set scalar values inside the deploy config. The example below shows some possible fee scalar values, calculated assuming negligible DA Layer costs, but will need to be adjusted up or down based on network throughput - as a reminder of how to set your scalar values, see [this section](/chain-operators/guides/features/blobs#update-your-scalar-values-for-blobs) of the docs.

      ```
      // Set in Deploy Config
        "gasPriceOracleBaseFeeScalar": 7663, // Approximate commitment tx base cost
        "gasPriceOracleBlobBaseFeeScalar": 0, // blobs aren't used for submitting the small data commitments
      ```

    <Info>
      Some initial scalar values must be set early on in the deploy config in [Step 2](#configure-your-op-node). And then at a later point, chain operators can update the scalar values with an L1 transaction.
    </Info>
  </Step>
</Steps>

## For node operators (full and archive nodes)

* Run a DA server as laid out in [Step 1](#setup-your-da-server)
* Provide the same  `--altda.enabled=true, --altda.da-server...` on `op-node` as listed in [Step 2](#configure-your-op-node)

## Inclusion criteria

Alt DA teams who want to be featured on this page must meet the following criteria:

* Functional [DA Server](https://specs.optimism.io/experimental/alt-da.html?utm_source=op-docs\&utm_medium=docs#da-server), maintained in your own repo
* Supporting detailed documentation, to be referenced [here](#setup-your-da-server)
* Functioning OP Stack devnet using your DA server with linked configuration, contract addresses, and RPC address

## Breaking changes: renaming Plasma Mode to Alt-DA Mode

This feature has been renamed from Plasma Mode to Alt-DA Mode in the monorepo at: [0bb2ff5](https://github.com/ethereum-optimism/optimism/commit/0bb2ff57c8133f1e3983820c0bf238001eca119b). There are several breaking changes you should be aware of. These include changes to configuration file parameters, environment variables, and CLI commands.
Before proceeding with the migration, ensure you are using [OP Stack v1.9.1](https://github.com/ethereum-optimism/optimism/releases/tag/v1.9.1) or later.

### Modify `rollup.json` config

Update your `rollup.json` configuration file by replacing the old Plasma config with the new Alt-DA config.
There are two possible formats for the old Plasma config:

### Legacy plasma config

If your config looks like this:

```json theme={null}
"use_plasma": true,
"da_commitment_type": "GenericCommitment",
"da_challenge_contract_address": "0xAAA",
"da_challenge_window": 1000,
"da_resolve_window": 2000,
```

### Recent plasma config

Or if it looks like this:

```json theme={null}
"plasma_config": {
  "da_commitment_type": "GenericCommitment",
  "da_challenge_contract_address": "0xAAA",
  "da_challenge_window": 1000,
  "da_resolve_window": 2000
}
```

### New Alt-DA config

Replace either of the above configurations with:

```json theme={null}
"alt_da": {
  "da_commitment_type": "GenericCommitment",
  "da_challenge_contract_address": "0xAAA",
  "da_challenge_window": 1000,
  "da_resolve_window": 2000
}
```

<Info>
  Only include fields in the new config that were present in your old config.
</Info>

## Updating OP Stack runtime config parameters

### CLI parameters

Update the following CLI parameters for both `op-node` and `op-batcher`:

| Former CLI param          | Current CLI param        |
| ------------------------- | ------------------------ |
| `--plasma.enabled`        | `--altda.enabled`        |
| `--plasma.da-server`      | `--altda.da-server`      |
| `--plasma.verify-on-read` | `--altda.verify-on-read` |
| `--plasma.da-service`     | `--altda.da-service`     |

### Environment variables

#### op-node

| Former env var                  | Current env var                |
| ------------------------------- | ------------------------------ |
| `OP_NODE_PLASMA_ENABLED`        | `OP_NODE_ALTDA_ENABLED`        |
| `OP_NODE_PLASMA_DA_SERVER`      | `OP_NODE_ALTDA_DA_SERVER`      |
| `OP_NODE_PLASMA_VERIFY_ON_READ` | `OP_NODE_ALTDA_VERIFY_ON_READ` |
| `OP_NODE_PLASMA_DA_SERVICE`     | `OP_NODE_ALTDA_DA_SERVICE`     |

#### op-batcher

| Former env var                     | Current env var                   |
| ---------------------------------- | --------------------------------- |
| `OP_BATCHER_PLASMA_ENABLED`        | `OP_BATCHER_ALTDA_ENABLED`        |
| `OP_BATCHER_PLASMA_DA_SERVER`      | `OP_BATCHER_ALTDA_DA_SERVER`      |
| `OP_BATCHER_PLASMA_VERIFY_ON_READ` | `OP_BATCHER_ALTDA_VERIFY_ON_READ` |
| `OP_BATCHER_PLASMA_DA_SERVICE`     | `OP_BATCHER_ALTDA_DA_SERVICE`     |

#### op-alt-da (formerly op-plasma) daserver

| Former env var                             | Current env var                        |
| ------------------------------------------ | -------------------------------------- |
| `OP_PLASMA_DA_SERVER_ADDR`                 | `OP_ALTDA_SERVER_ADDR`                 |
| `OP_PLASMA_DA_SERVER_PORT`                 | `OP_ALTDA_SERVER_PORT`                 |
| `OP_PLASMA_DA_SERVER_FILESTORE_PATH`       | `OP_ALTDA_SERVER_FILESTORE_PATH`       |
| `OP_PLASMA_DA_SERVER_GENERIC_COMMITMENT`   | `OP_ALTDA_SERVER_GENERIC_COMMITMENT`   |
| `OP_PLASMA_DA_SERVER_S3_BUCKET`            | `OP_ALTDA_SERVER_S3_BUCKET`            |
| `OP_PLASMA_DA_SERVER_S3_ENDPOINT`          | `OP_ALTDA_SERVER_S3_ENDPOINT`          |
| `OP_PLASMA_DA_SERVER_S3_ACCESS_KEY_ID`     | `OP_ALTDA_SERVER_S3_ACCESS_KEY_ID`     |
| `OP_PLASMA_DA_SERVER_S3_ACCESS_KEY_SECRET` | `OP_ALTDA_SERVER_S3_ACCESS_KEY_SECRET` |

After making these changes, your system should be properly configured to use the new Alt-DA Mode.

<Info>
  Remember to thoroughly test your configuration in testnet before going mainnet.
</Info>

## Next steps

* Additional questions? See the FAQ section in the [Alt-DA Mode Explainer](/op-stack/features/experimental/alt-da-mode#faqs).
* For more detailed info on Alt-DA Mode, see the [specs](https://specs.optimism.io/experimental/alt-da.html?utm_source=op-docs\&utm_medium=docs).
* If you experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions).


# Post batch data as blobs
Source: https://docs.optimism.io/chain-operators/guides/features/blobs

Learn how to switch your chain's batcher to posting batch data as blobs.

This guide walks you through how to switch to using blobs for your chain.
This feature was introduced with the Ecotone network upgrade.

## Switch to using blobs

<Steps>
  <Step title="Determine scalar values for using blobs">
    The first step to switching to submit data with Blobs is to calculate the
    scalar values you wish to set for the formula to charge users fees.
    Your scalar values depend on the average transactions per day your chain is processing, the types of transactions that occur on your chain, the [`OP_BATCHER_MAX_CHANNEL_DURATION`](/chain-operators/guides/configuration/batcher#set-your--op_batcher_max_channel_duration) you have parameterized on your `op-batcher`, and the target margin you wish to charge users on top of your L1 costs.
    For a walkthrough of sizing the scalars against your measured batcher spend, see [Recover the spend with fee scalars](/use-cases/tune-batcher-costs#step-5-recover-the-spend-with-fee-scalars) in the Tune batcher costs guide.
    For more details on fee scalar, see [Transaction Fees, Ecotone section](/op-stack/transactions/fees#ecotone).

    #### Adjust fees to change margins

    As a chain operator, you may want to scale your scalar values up or down either because the throughput of your chain has changed and you are either filling significantly more or less of blobs, or because you wish to simply increase your margin to cover operational expenses.
    So, to increase or decrease your margin on L1 data costs, you would simply scale both the `l1baseFeeScalar` and the `l1blobBaseFeeScalar` by the same multiple.

    For example, if you wished to increase your margin on L1 data costs by \~10%, you would do:

    ```
    newBaseFeeScalar = prevBaseFeeScalar * 1.1
    newBlobBaseFeeScalar = prevBlobBaseFeeScalar * 1.1
    ```
  </Step>

  <Step title="Update your scalar values for blobs">
    Once you have determined your ideal `BaseFeeScalar` and `BlobBaseFeeScalar`, you will need to apply those values for your chain. The first step is to encode both values into a single value to be set in your L1 Config:

    You can set your Scalar Values to send transaction to the L1 SystemConfigProxy.setGasConfigEcotone

    ```bash theme={null}
    cast send \
    --private-key $GS_ADMIN_PRIVATE_KEY \
    --rpc-url $ETH_RPC_URL \
    <CONTRACT_ADDRESS> \
    "setGasConfigEcotone(uint32,uint32)" \
    <basefeeScalar> <blobbasefeeScalar> 
    ```

    Check that the gas price oracle on L2 returns the expected values for `baseFeeScalar` and `blobBaseFeeScalar` (wait \~1 minute):

    <Info>
      This is checked on L2, so ensure you are using an RPC URL for your chain. You'll also need to provide a `gas-price` to geth when making this call.
    </Info>

    <Tabs>
      <Tab title="baseFeeScalar">
        ```shell theme={null}
        cast call 0x420000000000000000000000000000000000000F 'baseFeeScalar()(uint256)' --rpc-url YOUR_L2_RPC_URL
        ```
      </Tab>

      <Tab title="blobBaseFeeScalar">
        ```shell theme={null}
        cast call 0x420000000000000000000000000000000000000F 'blobBaseFeeScalar()(uint256)' --rpc-url YOUR_L2_RPC_URL
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Update your batcher to post blobs">
    Now that the fee config has been updated, you should immediately configure your batcher!

    <Info>
      Your chain may be undercharging users during the time between updating the scalar values and updating the Batcher, so aim to do this immediately after.
    </Info>

    Steps to configure the batcher:

    * Configure `OP_BATCHER_DATA_AVAILABILITY_TYPE=blobs`. The batcher will have to be restarted for it to take effect.
    * Ensure your `OP_BATCHER_MAX_CHANNEL_DURATION` is properly set to maximize your fee savings. See [OP Batcher Max Channel Configuration](/chain-operators/guides/configuration/batcher#set-your--op_batcher_max_channel_duration) for more details.
    * Optionally, you can configure your batcher to support multi-blobs. See [Multi-Blob Batcher Configuration](/chain-operators/guides/configuration/batcher#configure-your-batcher-to-use-multiple-blobs) for more details.
  </Step>
</Steps>

## Switch back to using calldata

As a chain operator, if the `blobBaseFee` is expensive enough and your chain is
not processing enough transactions to meaningfully fill blobs within your
configured batcher `OP_BATCHER_MAX_CHANNEL_DURATION`, you may wish to switch
back to posting data to calldata. To judge whether your transactions will be cheaper as blobs or as calldata, compare the current blob base fee with the L1 base fee, or set `OP_BATCHER_DATA_AVAILABILITY_TYPE=auto` to let the batcher make the comparison automatically; see [Choose a data availability type](/use-cases/tune-batcher-costs#step-3-choose-a-data-availability-type) in the Tune batcher costs guide for the trade-offs. Chains can follow these steps to switch from
blobs back to using calldata.

<Steps>
  <Step title="Determine your scalar values for using calldata">
    If you are using calldata, then you can set your `BaseFeeScalar` similarly to
    how you would have set "scalar" prior to Ecotone, though with a 5-10% bump to
    compensate for the removal of the "overhead" component.
    For a walkthrough of sizing the scalars against your measured batcher spend, see [Recover the spend with fee scalars](/use-cases/tune-batcher-costs#step-5-recover-the-spend-with-fee-scalars) in the Tune batcher costs guide.

    <Info>
      Since the Pectra upgrade on L1, chains which exclusively use calldata DA need to scale up their BaseFeeScalar by 10/4. See [this notice](/notices/archive/pectra-changes).
    </Info>

    Chains can update their fees to increase or decrease their margin. If using calldata, then `BaseFeeScalar` should be scaled to achieve the desired margin.
    For example, to increase your L1 Fee margin by 10%:

    ```
    BaseFeeScalar = BaseFeeScalar * 1.1
    BlobBaseFeeScalar = 0
    ```
  </Step>

  <Step title="Update your scalar values for using calldata">
    To set your scalar values, follow the same process as laid out in [Update your Scalar values for Blobs](#update-your-scalar-values-for-blobs).
  </Step>

  <Step title="Update your batcher to post calldata">
    Now that the fee config has been updated, you will want to immediately configure your batcher.

    <Info>
      Reminder, that your chain may be undercharging users during the time between updating the scalar values and updating the Batcher, so aim to do this immediately after.
    </Info>

    * Configure `OP_BATCHER_DATA_AVAILABILITY_TYPE=calldata`. The batcher will have to be restarted for it to take effect.
    * Ensure your `OP_BATCHER_MAX_CHANNEL_DURATION` is properly set to maximize savings. **NOTE:** While setting a high value here will lower costs, it will be less meaningful than for low throughput chains using blobs. See [OP Batcher Max Channel Configuration](/chain-operators/guides/configuration/batcher#set-your--op_batcher_max_channel_duration) for more details.
  </Step>
</Steps>

## Use auto DA mode in your batcher

The batcher now supports automatically switching from blobs to calldata depending on which DA type is more affordable. This is an optimization which allows for a slightly better DA profit margin for your chain.
To enable this mode, set `OP_BATCHER_DATA_AVAILABILITY_TYPE=auto`.

## Other considerations

* For information on L1 Data Fee changes related to the Ecotone upgrade, visit the [Transaction Fees page](/op-stack/transactions/fees#ecotone).
* If you want to enable archive nodes, you will need to access a blob archiver service. You can use [Optimism's](/op-mainnet/network-information/snapshots) or [run your own](/chain-operators/tools/explorer#create-an-archive-node).


# Deploy a Custom Gas Token chain
Source: https://docs.optimism.io/chain-operators/guides/features/custom-gas-token-guide

Learn how to deploy a Custom Gas Token chain using OP Deployer.

This guide provides instructions for chain operators who want to deploy a Custom Gas Token (CGT) chain.
See the [Custom Gas Token overview](/op-stack/features/custom-gas-token) for a general understanding of this OP Stack feature.

A Custom Gas Token chain enables you to use any asset as the native fee currency instead of ETH.
This asset may be an existing L1 token, a representation of a token from another chain, or a newly defined asset (or new L2 token) created at genesis.

<Warning>
  Custom Gas Token v2 is a new implementation that is not compatible with legacy CGT chains.
  There is currently no migration path from legacy CGT to CGT v2, though one is planned to be put together.
</Warning>

## Prerequisites

Before deploying a CGT chain, ensure you have:

* **OP Deployer installed**: See [Install op-deployer](/chain-operators/tools/op-deployer/installation) for setup instructions
* **L1 RPC endpoint**: Access to an Ethereum L1 node for deployment
* **Funded deployer account**: ETH for L1 gas costs during deployment
* **Token design**: Clear plan for your native asset (supply, distribution, bridging mechanism)
* **Security audit**: Thorough review of any authorized minters or bridge contracts you plan to deploy

## Deployment steps

Deploying a CGT chain follows the standard OP Stack deployment process with additional configuration for Custom Gas Token specific parameters.

<Steps>
  <Step title="Initialize your intent file">
    Create a new intent file using OP Deployer's [init command](/chain-operators/tools/op-deployer/usage/init):

    ```bash theme={null}
    op-deployer init \
      --l1-chain-id <chain ID of your L1> \
      --l2-chain-ids <comma separated list of chain IDs for your L2s> \
      --intent-type custom
    ```

    This creates an `intent.toml` file.
  </Step>

  <Step title="Configure Custom Gas Token parameters">
    Open your `intent.toml` file and add the Custom Gas Token configuration. Below is an example with CGT-specific fields:

    ```toml theme={null}
    configType = "custom"
    l1ChainID = 11155111
    fundDevAccounts = false
    useInterop = false
    l1ContractsLocator = "tag://op-contracts/v6.0.0"
    l2ContractsLocator = "tag://op-contracts/v6.0.0"

    [superchainRoles]
      SuperchainProxyAdminOwner = "0xYourMultisigAddress"
      SuperchainGuardian = "0xYourMultisigAddress"
      Challenger = "0xYourMultisigAddress"

    [[chains]]
      id = "0x0000000000000000000000000000000000000000000000000000000000001234"
      baseFeeVaultRecipient = "0xYourFeeRecipientAddress"
      l1FeeVaultRecipient = "0xYourFeeRecipientAddress"
      sequencerFeeVaultRecipient = "0xYourFeeRecipientAddress"
      operatorFeeVaultRecipient = "0xYourFeeRecipientAddress"
      eip1559DenominatorCanyon = 0
      eip1559Denominator = 0
      eip1559Elasticity = 0
      gasLimit = 60000000
      operatorFeeScalar = 0
      operatorFeeConstant = 0
      minBaseFee = 0
      daFootprintGasScalar = 0

      [chains.roles]
        l1ProxyAdminOwner = "0xYourMultisigAddress"
        l2ProxyAdminOwner = "0xYourMultisigAddress"
        systemConfigOwner = "0xYourMultisigAddress"
        unsafeBlockSigner = "0xYourSequencerAddress"
        batcher = "0xYourBatcherAddress"
        proposer = "0xYourProposerAddress"
        challenger = "0xYourChallengerAddress"

      [chains.customGasToken]
        name = "My Custom Token"
        symbol = "MCT"
        initialLiquidity = "0x..."  # optional, default: type(uint248).max
        liquidityControllerOwner = "0x..."  # optional, default: L2ProxyAdminOwner
    ```

    ### Key CGT configuration fields

    | Field                      | Description                                              | Required                                        |
    | -------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
    | `name`                     | Name of the native asset (e.g., "My Custom Token")       | Yes                                             |
    | `symbol`                   | Symbol for the native asset (e.g., "MCT")                | Yes                                             |
    | `initialLiquiditySupply`   | Initial supply minted to NativeAssetLiquidity at genesis | No, default: type(uint248).max                  |
    | `liquidityControllerOwner` | Manages the asset supply                                 | No, `L2ProxyAdminOwner` will be used as default |

    <Warning>
      **Fee parameter calculation is critical**: Your `minBaseFee` and `operatorFee` must accurately account for L1 gas costs and DA fees denominated in your custom token. If set too low, your chain may not cover operational costs. If set too high, users will pay excessive fees.
    </Warning>

    <Info>
      **Decimal support**: CGT v2 currently supports only 18-decimal tokens. Support for other decimals may be added in future releases.
    </Info>
  </Step>

  <Step title="Deploy L1 contracts">
    Deploy your L1 contracts using OP Deployer's [apply command](/chain-operators/tools/op-deployer/usage/apply)

    ```bash theme={null}
    op-deployer apply \
      --l1-rpc-url <your L1 RPC URL> \
      --private-key <your deployer private key>
    ```

    This deploys all necessary L1 contracts including `SystemConfig` with the `isCustomGasToken` flag enabled, which instructs L1 contracts to reject ETH-value transactions.

    <Info>
      The deployment process will automatically deploy the CGT-specific predeploys (`NativeAssetLiquidity` and `LiquidityController`) during genesis initialization.
    </Info>
  </Step>

  <Step title="(Optional) Verify L1 contracts">
    Optionally you can use OP Deployer's [verify command](/chain-operators/tools/op-deployer/usage/verify) to verify your L1 contracts on Blockscout or Etherscan.
  </Step>

  <Step title="Create genesis file with CGT configuration">
    After L1 deployment completes, initialize your L2 genesis with OP Deployer's [apply command](/chain-operators/tools/op-deployer/usage/apply):

    ```bash theme={null}
    op-deployer apply \
      --deployment-target genesis
    ```

    The genesis configuration is applied based on your `intent.toml`.
  </Step>

  <Step title="Start your chain services">
    Start your OP Stack services to start sequencing your CGT chain:

    * Sequencer Execution Client
    * Sequencer Consensus Client
    * Batcher
    * Proposer
    * Challenger
  </Step>

  <Step title="Verify and test">
    Before going live, thoroughly test your CGT chain. The following are some key areas to check:

    **Verify flag alignment**

    * Check L1 SystemConfig.isCustomGasToken() returns true
    * Check L2 L1Block.isCustomGasToken() returns true
    * Verify both flags match

    **Test native asset operations**

    * Test minting native assets via authorized minter
    * Test burning native assets
    * Test fee payments in native token
    * Verify fee vault accumulation

    **Test ETH rejection**

    * Attempt ETH deposit via OptimismPortal (should fail)
    * Attempt ETH withdrawal via L2ToL1MessagePasser (should fail)
    * Verify ETH operations are properly blocked

    **Test bridge functionality**

    * Test deposits (L1 → L2 native asset minting)
    * Test withdrawals (L2 native → L1 token)
    * Verify proper locking/unlocking in liquidity contract
  </Step>
</Steps>

## Post-deployment considerations

### Supply management

After deployment, you can:

* **Withdraw excess liquidity**: If genesis created more supply than needed, withdraw and burn via `L2ToL1MessagePasser`
* **Add new minters**: Authorize additional contracts to mint native assets as your ecosystem grows
* **Revoke minters**: Remove authorization from compromised or deprecated contracts
* **Implement rate limits**: Add safeguards to control minting velocity

### Fee parameter adjustments

Monitor your chain's operational costs and adjust fee parameters as needed:

* **minBaseFee**: Adjust based on L1 gas costs and your token's value, using `SystemConfig.setMinBaseFee()`
* **operatorFee**: Adjust based on data availability costs, using `SystemConfig.setOperatorFeeScalars()`

### Developer documentation

Create clear documentation for your users covering:

* How to acquire native assets (bridge, DEX, faucet, etc.)
* Bridge contract addresses and interfaces
* Fee structure and token economics
* Wallet configuration (RPC endpoints, chain ID, token metadata)

## Troubleshooting

### Flag mismatch errors

**Symptom**: Transactions failing with "custom gas token mismatch" errors

**Solution**: Verify that `SystemConfig.isCustomGasToken()` on L1 and `L1Block.isCustomGasToken()` on L2 return the same value. If mismatched, this indicates a critical configuration error.

### Fee parameter issues

**Symptom**: Chain operator losing money on transaction costs or users complaining about excessive fees

**Solution**: Review and recalculate your `minBaseFee` and `operatorFee` parameters based on:

* Current L1 gas prices
* Your token's market value or peg
* Data availability costs
* Target fee structure for users

### Liquidity depletion

**Symptom**: Minting transactions failing due to insufficient liquidity

**Solution**:

* Check `NativeAssetLiquidity` balance
* If depleted, this indicates an imbalance between minting and burning
* Review bridge logic to ensure burns are occurring correctly
* Consider increasing initial liquidity supply in future deployments

### Unauthorized minting attempts

**Symptom**: Unauthorized addresses attempting to mint native assets

**Solution**:

* Review access control configuration on `LiquidityController`
* Ensure only audited and secured contracts are authorized
* Implement rate limiting if not already in place
* Consider revoking and re-authorizing with additional safeguards

## Resources

* [Custom Gas Token feature overview](/op-stack/features/custom-gas-token)
* [OP Deployer documentation](/chain-operators/tools/op-deployer/overview)


# Enable span batches
Source: https://docs.optimism.io/chain-operators/guides/features/enable-span-batches

Learn how to enable span batches on your OP Stack chain by confirming Delta activation and configuring the batch type on op-batcher.

Span batches encode a span of consecutive L2 blocks in a single batch, reducing the overhead of batch submission.
This is especially beneficial for sparse, low-throughput chains.
The format was introduced in the Delta network upgrade, and chains opt into it through the `op-batcher` configuration.
For background on what span batches are and why they exist, see [Span batches](/op-stack/features/span-batches).

## Before you begin

Span batches are only valid once the Delta upgrade is active on your chain.
The `op-node` derivation pipeline drops any span batch whose L1 origin predates Delta activation, logging `dropping span batch before Delta activation`.

<Warning>
  Do not enable span batches on the batcher before Delta is active on your chain.
  Verifier nodes will drop the span batches your batcher posts, so the data you pay to submit will not advance the safe chain.
</Warning>

## Enable span batches

<Steps>
  <Step title="Confirm Delta is active on your chain">
    Delta activation is recorded as `delta_time` in your chain's rollup configuration (the `rollup.json` file passed to `op-node`).
    Delta is active once `delta_time` is set and the L2 block timestamp has passed that value.

    You can read it from the rollup configuration file directly, or query a running `op-node`:

    ```bash theme={null}
    cast rpc --rpc-url <OP_NODE_RPC_URL> optimism_rollupConfig | jq .delta_time
    ```

    If the result is a timestamp in the past, Delta is active.
    If it is `null`, Delta is not scheduled on your chain and must be activated first.
    For new chains, the `l2GenesisDeltaTimeOffset` deploy configuration parameter schedules Delta relative to genesis (`0` activates it at genesis) — see the [rollup deployment configuration reference](/chain-operators/reference/rollup-deployment-configuration).
    For Delta activation times on OP Mainnet and OP Sepolia, see [Network upgrades](/op-stack/protocol/network-upgrades).
  </Step>

  <Step title="Set the batch type on op-batcher">
    The `op-batcher` `--batch-type` flag (environment variable `OP_BATCHER_BATCH_TYPE`) selects the batch format: `0` for singular batches (the default) and `1` for span batches.

    Set it to `1` and restart the batcher:

    ```bash theme={null}
    --batch-type=1
    ```

    or, as an environment variable:

    ```bash theme={null}
    OP_BATCHER_BATCH_TYPE=1
    ```

    Optionally, `--max-blocks-per-span-batch` (`OP_BATCHER_MAX_BLOCKS_PER_SPAN_BATCH`) caps the number of L2 blocks added to a single span batch.
    The default is `0`, which means no maximum.
    See the [batcher configuration reference](/chain-operators/reference/batcher-configuration) for details on both flags.
  </Step>

  <Step title="Verify the batcher configuration">
    On startup, the batcher logs its channel configuration.
    Check the `Initialized channel-config` log line and confirm it reports `batch_type=1`:

    ```text theme={null}
    INFO [...] Initialized channel-config ... batch_type=1 ...
    ```
  </Step>
</Steps>

## Revert to singular batches

Singular batches remain valid after Delta, so you can switch back at any time by setting `--batch-type=0` (or unsetting `OP_BATCHER_BATCH_TYPE`, since `0` is the default) and restarting the batcher.

## Next steps

* Learn what span batches are and how the format works in the [span batches explainer](/op-stack/features/span-batches).
* Review the other batcher settings that affect cost and stability in [Configure the batcher](/chain-operators/guides/configuration/batcher).
* Read the [span batches specification](https://specs.optimism.io/protocol/delta/span-batches.html?utm_source=op-docs\&utm_medium=docs) for the full format definition.


# Set the DA Footprint Gas Scalar
Source: https://docs.optimism.io/chain-operators/guides/features/setting-da-footprint

Learn how to set a Data Availability (DA) Footprint on your OP-Stack Chain

## Overview

| Parameter                                                                                                       | Type   | Default     | Recommended | Units        |
| --------------------------------------------------------------------------------------------------------------- | ------ | ----------- | ----------- | ------------ |
| <Tooltip href="https://specs.optimism.io/protocol/jovian/l1-attributes.html"> `daFootprintGasScalar` </Tooltip> | Number | `0` (`400`) | `400`       | gas per byte |

<Warning>
  The default value of `0` is the same as setting the scalar to `400`. In order to effectively disable this feature, set the scalar to a very low value such as `1`.
  See the [specs for more detail](https://specs.optimism.io/protocol/jovian/l1-attributes.html).
</Warning>

The `daFootprintGasScalar` controls the **Data Availability (DA) Footprint Block Limit** introduced in the [Jovian hardfork](https://docs.optimism.io/notices/upgrade-17), which caps the total amount of transaction data that can fit into a block based on a scaled estimate of its compressed size.
The effective limit of estimated DA usage per block is `gasLimit / daFootprintGasScalar` bytes, so *increasing* the scalar *decreases* the limit, and vice versa.

For how the DA footprint is calculated, why the limit exists, and how the default of `400` was chosen, see [How the DA footprint block limit works](/chain-operators/reference/da-footprint).

## Choose a value

<Warning>
  * If no limit is set, or the value 0 is set for the `daFootprintGasScalar` in the `SystemConfig`, the default value of `400` is used
  * In order to effectively disable this feature, set the scalar to a very low value such as `1`.
  * Setting the `daFootprintGasScalar` too high may exclude too many transactions from your blocks.
  * Setting the `daFootprintGasScalar` too low may prove ineffective at preventing batcher throttling or protecting against continuous DA heavy transactions.
  * When a chain's gas limit is changed, the DA footprint scales proportionally by design. However, if you want to retain the same absolute DA footprint limit, then you must also scale the `daFootprintGasScalar` accordingly.
</Warning>

## Update the `daFootprintGasScalar`

The steps below explain how to update the `daFootprintGasScalar` parameter on-chain using the `SystemConfig` contract.

<Steps>
  <Step title="Find your SystemConfig contract address">
    The [SystemConfig](https://specs.optimism.io/protocol/system-config.html) contract stores configurable protocol parameters such as gas limits and fee settings.\
    You can find its proxy address in the [state.json generated by op-deployer](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-deployer-setup#deploy-l1-contracts).
  </Step>

  <Step title="Call the setDAFootprintGasScalar() method">
    <Info>
      The [SystemConfig owner](/op-stack/protocol/privileged-roles) is the only address that can make these changes.
    </Info>

    To update the `daFootprintGasScalar`, call the following method on the `SystemConfig` contract:

    `setDAFootprintGasScalar(uint16 daFootprintGasScalar) external onlyOwner;`

    Example (using [cast](https://getfoundry.sh/cast/reference/cast/)) to double the scalar, so lower the effective DA usage limit by half:

    ```bash title="Cast" theme={null}
    cast send -r <L1_RPC_URL> <SYSTEM_CONFIG_PROXY_ADDRESS> "setDAFootprintGasScalar(uint16)" 800 
    ```
  </Step>

  <Step title="Verify the new value">
    After the transaction confirms, verify the current value by calling the following getter method on the `SystemConfig` contract:

    `function daFootprintGasScalar() external view returns (uint16);`

    Example (using [cast](https://getfoundry.sh/cast/reference/cast/)):

    ```bash title="cast" theme={null}
    cast call -r <L1_RPC_URL> <SYSTEM_CONFIG_PROXY_ADDRESS> "daFootprintGasScalar()"
    ```

    And on your L2 chain you can query the scalar at the [L1Block predeploy](https://specs.optimism.io/protocol/predeploys.html#l1block) to confirm the new scalar has been propagated to the chain:

    ```bash title="cast" theme={null}
    cast call -r <L2_RPC_URL> 0x4200000000000000000000000000000000000015 "daFootprintGasScalar()"
    ```
  </Step>
</Steps>

## Next steps

* [How the DA footprint block limit works](/chain-operators/reference/da-footprint) — the calculation, the scalar's semantics, and the rationale for the default value.
* [Fee parameters reference](/chain-operators/reference/fee-parameters) — the full set of fee-related `SystemConfig` parameters.

## References

* [DA Footprint Configuration Spec](https://specs.optimism.io/protocol/jovian/system-config.html#da-footprint-configuration)
* [Jovian Upgrade Spec](https://specs.optimism.io/protocol/jovian/overview.html)
* [SystemConfig Contract Spec](https://specs.optimism.io/protocol/system-config.html)
* [Design Doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md)


# Set the Minimum Base Fee
Source: https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee

Learn how to set a minimum base fee on your OP-Stack Chain

## Overview

| Parameter               | Type   | Default      | Recommended | Max Allowed for Standard Chains | Units |
| ----------------------- | ------ | ------------ | ----------- | ------------------------------- | ----- |
| <code>minBaseFee</code> | Number | 0 (disabled) | 100,000     | 10,000,000,000                  | wei   |

The <strong>Minimum Base Fee</strong> (`minBaseFee`) configuration was introduced in the <strong>[Jovian hardfork](https://docs.optimism.io/notices/upgrade-17)</strong>.
This feature allows chain operators to specify a minimum L2 base fee to which can help avoid excessively long priority fee auctions that can occur when the base fee falls too low.

When [batcher-sequencer throttling is active](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling) for long enough and the minBaseFee isn't enabled (or is zero), the base fee can drop all the way down to 1 wei. It can take a long time to recover back to a stable base fee.

The steps below explain how to update the `minBaseFee` parameter on-chain using the <code>SystemConfig</code> contract.

<Warning>
  Setting the `minBaseFee` too high may make transactions harder to include for users.
</Warning>

## How to Update the Minimum Base Fee

<Steps>
  <Step title="Find your SystemConfig contract address">
    The [SystemConfig](https://specs.optimism.io/protocol/system-config.html) contract stores configurable protocol parameters such as gas limits and fee settings.\
    You can find its proxy address in the [state.json generated by op-deployer](https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-deployer-setup#deploy-l1-contracts).
  </Step>

  <Step title="Call the setMinimumBaseFee() method">
    <Info>
      Note that the owner of the `SystemConfig` contract is the [System Config Owner address](/op-stack/protocol/privileged-roles), so this transaction must be sent from that address.
    </Info>

    To update the minimum base fee, call the following method on the `SystemConfig` contract:

    `setMinBaseFee(uint64 minBaseFee) external onlyOwner;`

    Example (using [cast](https://getfoundry.sh/cast/reference/cast/)):

    ```bash title="cast" theme={null}
    cast send <SYSTEM_CONFIG_PROXY_ADDRESS> "setMinBaseFee(uint64)" 100000 
    ```
  </Step>

  <Step title="Verify the new value">
    After the transaction confirms, verify the current value by calling the following getter method on the `SystemConfig` contract:

    `function minBaseFee() external view returns (uint64);`

    Example (using [cast](https://getfoundry.sh/cast/reference/cast/)):

    ```bash title="cast" theme={null}
    cast call <SYSTEM_CONFIG_PROXY_ADDRESS> "minBaseFee()"
    ```
  </Step>
</Steps>

***

## References

* [Minimum Base Fee Configuration Spec](https://specs.optimism.io/protocol/jovian/system-config.html#minimum-base-fee-configuration)
* [Jovian Upgrade Spec](https://specs.optimism.io/protocol/jovian/overview.html)
* [SystemConfig Contract Spec](https://specs.optimism.io/protocol/system-config.html)
* [Design Doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/minimum-base-fee.md)


# Set the Operator Fee
Source: https://docs.optimism.io/chain-operators/guides/features/setting-operator-fee

Learn how to configure the operator fee on your OP Stack Chain

## Overview

| Parameter             | Default | Recommended    | Type                          |
| :-------------------- | :-----: | :------------- | :---------------------------- |
| `operatorFeeScalar`   |    0    | Chain-specific | uint32 scalar (scaled by 1e6) |
| `operatorFeeConstant` |    0    | Chain-specific | uint64 scalar (wei)           |

The **Operator Fee** was introduced in the **[Isthmus upgrade](https://docs.optimism.io/notices/upgrade-14#operator-fee)** and modified in the **[Jovian upgrade](https://docs.optimism.io/notices/upgrade-17#breaking-changes)**.\
It allows OP Stack chain operators to charge an additional fee on transactions, on top of the **execution gas fee** (base fee + priority fee) and the **L1 data fee**.

This mechanism gives operators two levers:

* a **gas-proportional component** (`operatorFeeScalar`) that scales with gas used
* a **flat component** (`operatorFeeConstant`)

<Info>
  The operator fee is only applied on chains that have enabled the Isthmus upgrade.
</Info>

<Info>
  **Deposit transactions do not get charged operator fees.**\
  For all deposit transactions, regardless of the operator fee configuration, the operator fee is always zero.
</Info>

***

## Operator Fee Formula

The operator fee is calculated using the following formula, depending on the active fork.

**After Isthmus:**

```text theme={null}
operatorFee = operatorFeeConstant + (operatorFeeScalar * gasUsed / 1e6)
```

**After Jovian:**

```text theme={null}
operatorFee = operatorFeeConstant + (operatorFeeScalar × gasUsed × 100)
```

<Warning>
  Setting operator fee values too high can significantly increase transaction costs and reduce user adoption.
  The operator fee directly impacts UX and competitiveness and should be adjusted conservatively.
  The default value for standard chains is 0, any other value is considered non-standard.
</Warning>

***

## How to Update the Operator Fee

To update the operator fee parameters, call the following method on the `SystemConfig` contract from the `SystemConfigOwner`:

`setOperatorFeeScalars(uint32 _operatorFeeScalar, uint64 _operatorFeeConstant) external onlyOwner;`

Example using cast:

```bash title="cast" theme={null}
cast send  --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> \
  <SYSTEM_CONFIG_PROXY_ADDRESS> \
  "setOperatorFeeScalars(uint32,uint64)" \
  500000 1000000000000
```

After the transaction confirms, verify the current configuration by calling the following:

`function operatorFeeScalar() view returns (uint32);`\
`function operatorFeeConstant() view returns (uint64);`

Example using cast:

```bash title="cast" theme={null}
cast call --rpc-url <RPC_URL> <SYSTEM_CONFIG_PROXY_ADDRESS> "operatorFeeScalar()"
cast call --rpc-url <RPC_URL> <SYSTEM_CONFIG_PROXY_ADDRESS> "operatorFeeConstant()"
```

***

## References

* [Operator Fee Overview – OP Stack Fee Docs](https://docs.optimism.io/op-stack/transactions/fees#operator-fee-component)
* [SystemConfig Operator Fee Parameter Configuration – OP Stack Specs](https://specs.optimism.io/protocol/isthmus/system-config.html#operator-fee-parameter-configuration)
* [Isthmus Operator Fee Details – OP Stack Specs](https://specs.optimism.io/protocol/isthmus/exec-engine.html#operator-fee)


# Using snap sync for chain operators
Source: https://docs.optimism.io/chain-operators/guides/features/snap-sync

Learn how to enable snap sync on your OP Stack chain.

Snap sync significantly improves the experience of syncing an OP Stack node. On the consensus layer, `op-node` enables it with the `--syncmode=execution-layer` flag.
Rather than re-executing every block from genesis, the execution client downloads chain and state data from other nodes on the network over P2P and begins executing from the completed state.
This means that performing a snap sync is significantly faster than performing a full sync.

* Snap sync enables node operators on your network to sync faster.
* Snap sync removes the need for nodes on your post Ecotone network to run a [blob archiver](/node-operators/guides/management/blobs).

## Enable snap sync for chains

To enable snap sync, chain operators need to spin up a node which is exposed to the network and has transaction gossip disabled.
This node will serve snap sync requests on the execution layer from other nodes on the network.

<Info>
  For snap sync, all nodes should expose port `30303` TCP and `30303` UDP to easily find other nodes to sync from. These are op-reth's defaults for `--port` (TCP) and `--discovery.port` (UDP).

  * If you set the port with [`--discovery.port`](/node-operators/op-reth/cli/op-reth/node), then you must open the port specified for UDP.
  * If you set [`--port`](/node-operators/op-reth/cli/op-reth/node), then you must open the port specified for TCP.
  * The only exception is for sequencers and transaction ingress nodes.
</Info>

<Steps>
  <Step title="Setup a snap sync node">
    * Expose port `30303` (op-reth's default listening and discovery port) to the internet on TCP and UDP.
    * Disable transaction gossip with the [`--rollup.disable-tx-pool-gossip`](/node-operators/op-reth/cli/op-reth/node) flag
  </Step>

  <Step title="Enable snap sync on your network">
    * See the [sync modes reference](/node-operators/reference/consensus-layer-sync) for how node operators enable snap sync (execution-layer sync) on your chain network.
  </Step>
</Steps>


# Enabling Subblocks
Source: https://docs.optimism.io/chain-operators/guides/features/subblocks-guide

Learn about enabling Subblocks on an OP Stack chain.

<Warning>
  Subblocks replace Flashblocks. Flashblocks are no longer officially supported on OP Stack chains.
</Warning>

Subblocks are a private feature available only to OP Enterprise customers. If you are interested in becoming an OP Enterprise customer, [contact the OP Enterprise team](https://optimism.io/learn-more). See [this explainer on Subblocks](/op-stack/features/subblocks) for more details.


# Switch to Kona Proofs
Source: https://docs.optimism.io/chain-operators/guides/features/switching-to-kona-proofs

Learn how to switch your OP Stack chain to use Kona-based fault proofs as the respected game type.

<Info>
  [Upgrade 18](/notices/archive/upgrade-18) (approved by Optimism Governance) introduced `CANNON_KONA` (8) as an available game type alongside `CANNON` (0). [Upgrade 19](/notices/archive/upgrade-19) promotes `CANNON_KONA` to the **respected game type** for chains managed by the Optimism Security Council — meaning it is applied automatically as part of the onchain upgrade. Non-managed chains that want to switch must follow this guide.
</Info>

## Overview

| Parameter               | Type    | Current (typical) | Target when switching | Notes                                               |
| ----------------------- | ------- | ----------------- | --------------------- | --------------------------------------------------- |
| Respected game type     | Enum    | `CANNON` (0)      | `CANNON_KONA` (8)     | Determines which game type is used for withdrawals  |
| `OP_PROPOSER_GAME_TYPE` | Number  | 0                 | 8                     | Proposer game type (must match respected game type) |
| `cannonPrestate`        | Bytes32 | Set               | Set                   | Must be a valid `cannon64` prestate hash            |
| `cannonKonaPrestate`    | Bytes32 | Set               | Set                   | Must be a valid `cannon64-kona` prestate hash       |

Kona proofs use the `kona-client` fault proof program, which is a combination of `kona-node` and `op-reth`. It replaces `op-program` (a combination of `op-node` and `op-geth`), which has reached end-of-support and does not support the Karst hardfork. See [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation). Both programs:

* Use Cannon as the FPVM, and
* Are used by the same dispute game implementation (`FaultDisputeGame.sol`).

After the cannon+kona upgrade is deployed, both game types are available:

* `CANNON` (0): `op-program` (end-of-support)
* `CANNON_KONA` (8): `kona-client`

Until you switch, the respected game type remains `CANNON` (0), meaning only those games are used for withdrawals. Because `op-program` does not support Karst, complete this switch before activating the Karst hardfork on your chain. This guide explains how to switch your chain so that Kona proofs (`CANNON_KONA`, 8) become the respected game type.

<Warning>
  This guide assumes you have already completed the cannon+kona upgrade, including setting both `cannonPrestate` and `cannonKonaPrestate` in `OpChainConfig`, and that your fault proof infrastructure is healthy.
</Warning>

The high-level flow is:

* Verify that cannon+kona support is correctly deployed on-chain.
* Confirm that your off-chain infra (especially `op-challenger`) is Kona-ready.
* Switch the respected game type to `CANNON_KONA` (8).
* Update `op-proposer` to post Kona games.
* Monitor the system.

***

## How to Switch to Kona Proofs

<Steps>
  <Step title="Confirm cannon+kona support is deployed">
    Before changing the respected game type, verify that your chain has been upgraded to support both `CANNON` and `CANNON_KONA` games.

    <Info>
      The required upgrade is performed via `OPCM.upgrade` with an `OpChainConfig` that sets both `cannonPrestate` and `cannonKonaPrestate`.
    </Info>

    1. **Check `OpChainConfig` prestates**

       Ensure that the `OpChainConfig` used in your most recent upgrade included:

       * `cannonPrestate` pointing to a valid `cannon64` prestate.
       * `cannonKonaPrestate` pointing to a valid `cannon64-kona` prestate.

       Both hashes must come from the standard prestates in the superchain registry and must embed an up-to-date chain config for your chain.

    2. **Verify `DisputeGameFactory` implementations**

       After the cannon+kona upgrade, the `DisputeGameFactory` should have:

       * A non-zero implementation for `CANNON` (0), and
       * A non-zero implementation for `CANNON_KONA` (8).

       Example (using [cast](https://getfoundry.sh/cast/reference/cast/)):

       ```bash title="cast" theme={null}
       # CANNON (0) implementation
       cast call <DISPUTE_GAME_FACTORY_ADDRESS> "gameImpl(uint8)" 0

       # CANNON_KONA (8) implementation
       cast call <DISPUTE_GAME_FACTORY_ADDRESS> "gameImpl(uint8)" 8
       ```

       Both calls should return non-zero addresses.
  </Step>

  <Step title="Ensure op-challenger is Kona-ready">
    Your challengers must be able to play both cannon and kona games before you change the respected game type.

    1. **Trace types**

       If you explicitly configure trace types, ensure that `cannon-kona` is included. A typical setting is:

       ```bash theme={null}
       OP_CHALLENGER_TRACE_TYPE="cannon,cannon-kona,permissioned"
       # or
       --trace-type=cannon,cannon-kona,permissioned
       ```

    2. **Prestate URLs**

       Make sure `op-challenger` can fetch both cannon and cannon-kona prestates:

       * If they are at the same URL, use:

         ```bash theme={null}
         --prestates-url=<PRESTATES_URL>
         ```

       * If they are at different locations, use:

         ```bash theme={null}
         --cannon-prestates-url=<CANNON_PRESTATES_URL>
         --cannon-kona-prestates-url=<CANNON_KONA_PRESTATES_URL>
         ```

    3. **Kona host binary**

       For operators not using the standard OP Labs `op-challenger` Docker images, you must also provide:

       ```bash theme={null}
       --cannon-kona-server=/path/to/kona-host
       # or
       OP_CHALLENGER_CANNON_KONA_SERVER=/path/to/kona-host
       ```

       The `kona-host` binary is available from the Kona repository (for example under `bin/host`). Build it from the same release as the `cannon-kona` prestate you configured.
  </Step>

  <Step title="Switch the respected game type to CANNON_KONA">
    Once both on-chain and off-chain pieces are ready, you can switch the respected game type so that Kona proofs become the canonical path for withdrawals.

    <Warning>
      Changing the respected game type affects which games can be used to prove withdrawals. Only perform this step once you are confident in your Kona setup.
    </Warning>

    The respected game type is configured in the `AnchorStateRegistry` contract.

    1. **Encode the calldata**

       Use `cast calldata` to encode a call to `setRespectedGameType(uint32)` with game type `8` (which corresponds to `CANNON_KONA`):

       ```bash title="cast" theme={null}
       CALLDATA=$(cast calldata "setRespectedGameType(uint32)" 8)
       ```

    2. **Send the transaction**

       Send the transaction from the Guardian to the `AnchorStateRegistry`:

       ```bash title="cast" theme={null}
       cast send \
         --rpc-url <L1_RPC_URL> \
         --private-key <GUARDIAN_PRIVATE_KEY> \
         <ANCHOR_STATE_REGISTRY_ADDRESS> \
         "$CALLDATA"
       ```

    3. **Verify the new respected game type**

       After the transaction confirms, verify that the respected game type is now `8`:

       ```bash title="cast" theme={null}
       cast call \
         --rpc-url <L1_RPC_URL> \
         <ANCHOR_STATE_REGISTRY_ADDRESS> \
         "respectedGameType()(uint32)"
       ```

       The returned value should be `8`, indicating that `CANNON_KONA` is now the respected game type.
  </Step>

  <Step title="Update op-proposer to use game type 8">
    With `CANNON_KONA` set as the respected game type, your proposers must create Kona games.

    1. **Update the proposer game type**

       Change your `op-proposer` configuration from game type 0 to 8:

       ```bash theme={null}
       # Before
       OP_PROPOSER_GAME_TYPE=0
       # or
       --game-type=0

       # After switching to Kona
       OP_PROPOSER_GAME_TYPE=8
       # or
       --game-type=8
       ```

       This change is not required as part of the initial cannon+kona upgrade; it is only required when you actually switch the respected game type to `CANNON_KONA`.

    2. **Restart proposers**

       Restart your proposer processes so they pick up the new configuration. Verify in logs and metrics that they are now using game type 8.
  </Step>

  <Step title="Monitor, and validate">
    After switching to Kona proofs, closely monitor your chain to ensure everything is functioning as expected.

    1. **Run test withdrawals**

       * Perform a few small test withdrawals and ensure that:
         * New fault dispute games are created with game type `CANNON_KONA` (8).
         * Your challengers are responding correctly using `kona-host`.

    2. **Observe metrics and logs**

       * Monitor `op-proposer` and `op-challenger` logs for errors.
       * Watch dispute game metrics (for example, game counts and step timings) for anomalies.
  </Step>
</Steps>

***

## References

* [OP Stack Fault Proofs Explainer](https://docs.optimism.io/op-stack/fault-proofs/explainer)
* [Fault Proof Specs](https://specs.optimism.io/fault-proof/index.html)


# Join the Superchain Registry
Source: https://docs.optimism.io/chain-operators/guides/join-superchain-registry

How to add your OP Stack chain to the Superchain Registry — prerequisites, config generation, and the pull-request process.

The [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry)
is the source-of-truth index of who is in the OP Stack Ecosystem and how each
chain is configured. This guide walks you through adding your chain. The
registry repo's
[operations documentation](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md)
is the canonical reference for every step below — each step links the matching
section, and if this page and that document ever disagree, the registry repo
wins.

Joining gets you more than a listing: once your chain is in the registry, its
config is embedded in downstream releases of `op-node` and `op-geth`, so nodes
can join your network with the `--network` / `--op-network` flags and can
inherit Superchain-wide hardfork activations automatically. See the
[superchain-registry explainer](/op-stack/protocol/superchain-registry) for how
that works.

## Before You Start

* **Chat with the Optimism Foundation.**
* **Your chain ID must be registered at
  [ethereum-lists/chains](https://github.com/ethereum-lists/chains).** The
  registry's validation suite checks against it; this is a mandatory
  prerequisite
  ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#adding-a-chain)).
* **Standard chains must be deployed with
  [op-deployer](/chain-operators/tools/op-deployer/overview).** A chain is
  only considered standard in the registry if it was deployed with
  op-deployer, which also produces the `state.json` file the registry
  tooling consumes
  ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#0-standard-chains-deploy-your-chain-with-op-deployer)).
  Chains deployed another way follow the [custom-chain path](#custom-chains)
  below.
* **Install the tooling dependencies:** `git` (`^2`), `go` (`^1.21`), and
  [`just`](https://github.com/casey/just) (`^1.28.0`)
  ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#1-install-dependencies)).

## Add Your Chain

<Steps>
  <Step title="Fork the Registry Repository">
    You will raise a pull request from your fork to the upstream repo. Start
    from a fresh, non-protected branch (not your fork's `main`), and add one
    chain per branch and PR.
    ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#2-fork-this-repository))
  </Step>

  <Step title="Generate a Config From Your State File">
    From the root of the registry repo, run:

    ```bash theme={null}
    just create-config <shortname> <path to your state file>
    ```

    where `<shortname>` is your chain's short name (for example `op`) and the
    state file is the `state.json` produced by op-deployer. This writes two
    files to the `.staging` directory: `<shortname>.toml` and
    `<shortname>.json.zst`. If you deployed with custom contracts, pass your
    op-deployer version as a third argument — supported values live in the
    registry's `versions.json`.
    ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#3-generate-a-config-from-your-state-file))
  </Step>

  <Step title="Fill In the Generated Config">
    Most of `<shortname>.toml` is populated from your deployer state, but you
    must fill in the rest yourself: `name`, `superchain` (`mainnet` or
    `sepolia`), `public_rpc`, `sequencer_rpc`, `explorer`, and
    `deployment_tx_hash`. Double-check the generated values while you are in
    the file.
    ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#4-update-generated-config))
  </Step>

  <Step title="Open the Pull Request">
    Commit to your fork and open one PR per chain. Check the box to
    [allow edits from maintainers](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork)
    so reviewers can push to your branch. Automated checks will validate your
    chain and generate a report on its compliance with the standard
    blockchain charter.
    ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#5-commit))
  </Step>

  <Step title="Await Review">
    A registry maintainer reviews your PR. When it is ready, the team
    generates code from your PR and pushes to your fork — do not run codegen
    yourself; it slows down review.
    ([ops.md](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#6-await-review))
  </Step>
</Steps>

## Custom Chains

If your chain was not deployed with op-deployer (for example, a heavily
modified deployment), you must write the config file by hand instead of
generating it: copy the example config into `.staging`, substitute every field
for your chain (custom chains set `superchain_level = 0` and
`governed_by_optimism = false`), and ZST-encode your genesis file with the
registry's dictionary. The full field-by-field walkthrough lives in
[Adding a custom chain](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#adding-a-custom-chain).

## After You Are In

To receive Superchain-wide coordinated hardfork activations automatically, set
`superchain_time` in your chain's config (use `0` if your chain has activated
all Superchain forks up to its genesis time) and run your nodes with the
network flags. Details in the
[explainer](/op-stack/protocol/superchain-registry#hard-fork-activation-inheritance-behavior)
and the registry's
[hardfork activation inheritance spec](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/hardfork-activation-inheritance.md).

## Next Steps

* [The superchain-registry explainer](/op-stack/protocol/superchain-registry)
* [Deploy your chain with op-deployer](/chain-operators/tools/op-deployer/overview)
* [Registry operations documentation](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md) (canonical)


# Chain operator best practices
Source: https://docs.optimism.io/chain-operators/guides/management/best-practices

Learn some best practices for managing the OP Stack's off-chain components.

The following information has some best practices around running the OP Stack's
off-chain components.

## Correct release versions

Chain and node operators should always run the latest production releases of the OP Stack's off-chain components. The latest notes and changelogs can be found on GitHub:

* [OP monorepo releases](https://github.com/ethereum-optimism/optimism/releases) (includes `op-node` and other Go-based OP components)
* [op-geth releases](https://github.com/ethereum-optimism/op-geth/releases) (standalone repository)
* [op-contracts releases](https://github.com/ethereum-optimism/optimism/releases) (look for tags starting with `op-contracts/`)

Some guidelines when picking versions:

* **Production releases** are always tagged with `<component-name>/v<semver>` for a specific OP component, for example:
  * `op-node/v1.7.5` for the `op-node`
  * `op-challenger/v1.0.0` for the `op-challenger`

* **Monorepo releases** typically use a simple `v<semver>` format (e.g. `v1.7.7`) to indicate that all Go-based OP Stack components (in `op-*`) have been updated together. These do **not** include new L1 contract releases.

* **Contracts releases** are tagged under `op-contracts/v<semver>` (e.g. `op-contracts/v1.6.0`) and contain updates to the Bedrock L1 contracts.

* **`op-geth` versioning** includes upstream geth's version within its semver. For example, if upstream geth is at `v1.12.0`, an `op-geth` release might be `v1.101200.0`. The geth major version is used as our minor version (left-padded if needed), and the patch version is appended.

Always consult release notes for additional details or upgrade instructions.

## Keep deployment artifacts

After deploying your contracts on Ethereum, you should keep a record of all the deployment artifacts.
This is will be all the [op-deployer](/chain-operators/tools/op-deployer/overview.mdx) artifacts, as well as the release tag and commit hash of `op-deployer` and `op-contracts`.
You will need these artifacts to add your chain to the [Superchain Registry](/op-stack/protocol/superchain-registry).

## Incremental upgrade rollouts

When upgrading your nodes, take a staggered approach. This means deploying the
upgrade gradually across your infrastructure and ensuring things work as
expected before making changes to every node.

## Isolate your sequencer

You can isolate your sequencer node, by not connecting it directly to the
internet. Instead, you could handle your ingress traffic behind a proxy. Have
the proxy forward traffic to replicas and have them gossip the transactions
internally.

## Improve reliability of peer-to-peer transactions

These flags can improve the reliability of peer-to-peer transactions from internal replica nodes and the sequencer node.

For sequencer nodes:

```
GETH_TXPOOL_JOURNAL: ""
GETH_TXPOOL_JOURNALREMOTES: "false"
GETH_TXPOOL_NOLOCALS: "true"
```

For replica nodes:

```
GETH_TXPOOL_JOURNALREMOTES: "true"
GETH_TXPOOL_LIFETIME: "1h"
GETH_TXPOOL_NOLOCALS: "true"
```

For additional information about these flags, check out our [Execution Layer Configuration Options](/node-operators/reference/op-reth-config) doc.

## Write your own runbooks

Create custom runbooks to prepare for operating an OP Stack chain.
You'll want to setup metrics endpoints and monitoring on your key components of the system and create runbooks to execute when something is not behaving as expected.

## Assumptions

### op-proposer assumes archive mode

The `op-proposer` currently assumes that `op-geth` is being run in archive
mode. This will likely be updated in a future network upgrade, but it is
necessary for L2 withdrawals at the moment.

<Info>
  **Running this in production**

  <OpEnterpriseCalloutBody />
</Info>


# Fee vault operations
Source: https://docs.optimism.io/chain-operators/guides/management/fee-vaults

How to configure, monitor, and withdraw from fee vaults on your OP Stack chain.

This guide covers the operational aspects of managing fee vaults on your OP Stack chain. For a conceptual overview of how fee vaults work, see [Fee vaults](/op-stack/transactions/fee-vaults).

## Prerequisites

* Access to the **ProxyAdminOwner** account (required for configuration changes)
* An RPC endpoint for your L2 chain
* `cast` CLI tool installed ([Foundry](https://book.getfoundry.sh/getting-started/installation))

## Fee vault addresses

| Vault               | Address                                      | Collects                     | Introduced |
| ------------------- | -------------------------------------------- | ---------------------------- | ---------- |
| `SequencerFeeVault` | `0x4200000000000000000000000000000000000011` | Priority fees (tips)         | Legacy     |
| `BaseFeeVault`      | `0x4200000000000000000000000000000000000019` | Base fees (not burned on L2) | Bedrock    |
| `L1FeeVault`        | `0x420000000000000000000000000000000000001A` | L1 data fees                 | Bedrock    |
| `OperatorFeeVault`  | `0x420000000000000000000000000000000000001B` | Operator fees                | Isthmus    |

## Checking vault state

### View current balance

```bash theme={null}
export L2_RPC=<L2_RPC>
export VAULT=<VAULT_ADDRESS>

cast balance $VAULT --rpc-url $L2_RPC
```

### View configuration

```bash theme={null}
# Recipient address
cast call $VAULT "recipient()" --rpc-url $L2_RPC

# Minimum withdrawal amount (in wei)
cast call $VAULT "minWithdrawalAmount()" --rpc-url $L2_RPC

# Withdrawal network (0 = L1, 1 = L2)
cast call $VAULT "withdrawalNetwork()" --rpc-url $L2_RPC

# Total ETH withdrawn historically
cast call $VAULT "totalProcessed()" --rpc-url $L2_RPC
```

## Updating configuration

<Warning>
  Configuration changes require the **ProxyAdminOwner** account. If your chain uses a multisig as the ProxyAdminOwner, these calls must be executed through the multisig.
</Warning>

### Set recipient

```bash theme={null}
export L2_RPC=<L2_RPC>
export VAULT=<VAULT_ADDRESS>
export PK=<PROXY_ADMIN_OWNER_PRIVATE_KEY>

cast send --rpc-url $L2_RPC --private-key $PK \
  $VAULT "setRecipient(address)" <NEW_RECIPIENT_ADDRESS>
```

### Set minimum withdrawal amount

```bash theme={null}
cast send --rpc-url $L2_RPC --private-key $PK \
  $VAULT "setMinWithdrawalAmount(uint256)" <AMOUNT_IN_WEI>
```

### Set withdrawal network

```bash theme={null}
# 0 = L1, 1 = L2
cast send --rpc-url $L2_RPC --private-key $PK \
  $VAULT "setWithdrawalNetwork(uint8)" <0_OR_1>
```

## Withdrawing fees

Withdrawals are **permissionless** — anyone can trigger them once the vault balance meets the minimum threshold.

### Trigger a withdrawal

```bash theme={null}
cast send --rpc-url $L2_RPC --private-key $PK \
  $VAULT "withdraw()"
```

This withdraws the **entire vault balance** to the configured recipient.

### Withdrawal behavior by network

* **L2 withdrawal (`withdrawalNetwork = 1`)**: Funds are transferred immediately to the recipient on L2. The transaction completes in a single step.
* **L1 withdrawal (`withdrawalNetwork = 0`)**: An L2-to-L1 withdrawal is initiated via the `L2ToL1MessagePasser`. After calling `withdraw()`, you must still:

  1. Wait for the withdrawal to be included in an L2 output root
  2. Prove the withdrawal on L1
  3. Wait for the finalization period
  4. Finalize the withdrawal on L1

  For details on completing L1 withdrawals, see [Withdrawal flow](/op-stack/bridging/withdrawal-flow).

## Initial configuration during deployment

Fee vault recipients, minimum withdrawal amounts, and withdrawal networks are configured during chain deployment with `op-deployer`. For details on setting these parameters, see the [op-deployer setup guide](/chain-operators/tutorials/create-l2-rollup/op-deployer-setup).

## Monitoring

It's good practice to monitor your fee vaults regularly:

* **Vault balances**: Track balances to know when withdrawals can be triggered.
* **`totalProcessed`**: Monitor cumulative withdrawals over time to understand revenue trends.

## Next steps

* Read the [fee vaults explainer](/op-stack/transactions/fee-vaults) to understand how vaults work at the protocol level.
* See [Transaction Fees 101](/chain-operators/guides/management/transaction-fees-101) to learn how to tune fee parameters.
* Review [fee components and formulas](/op-stack/transactions/fees) for detailed fee calculations.


# Changing gas target/limit
Source: https://docs.optimism.io/chain-operators/guides/management/gas-target-limit

Learn how to change the gas target and limit on your OP Stack chain.

This guide covers how to optimize block processing performance at higher gas limits, test your infrastructure before activation, and safely change the gas target and/or limit on a live chain.
This guide assumes your OP Stack chain has the [Holocene features](/notices/archive/holocene-changes) activated.

## Recommended config for best performance

Some known ways to improve block processing performance:

* **Use NVMe for storage** instead of local SSDs or other persistent disks
* **Use full nodes where possible** over archive nodes

## Pre-activation testing

To ensure your chain and supporting infrastructure can consistently process blocks up to your gas limit, you should run some performance tests.
You'll want to run benchmarks and perform careful analysis of the results to ensure your execution clients can handle the increased gas usage.

## Changing the gas target/limit change

How to change the gas target/limit on a live chain.

### Relevant configuration parameters

The gas configuration on an OP Stack chain use the same EIP-1559 parameters as Ethereum.
Where the **gas target** = **gas limit** / **elasticity**.
These values can be found in the `SystemConfig` contract.

### Procedure

Holocene introduces the ability to change the EIP-1559 parameters `elasticity` and `denominator` via the `SystemConfig`. This will allow you to set proper values for the `elasticity` and block `gasLimit`.

**Example**: to double the *target* while keeping the block *limit* at 30Mgas/block:

<Steps>
  <Step title="Retrieve existing EIP-1559 values">
    Retrieve the existing `eip1559Elasticity` and `eip1559Denominator` values:

    ```solidity theme={null}
    elasticity = SystemConfig.eip1559Elasticity() // 6
    denominator = SystemConfig.eip1559Denominator() // 50
    limit = SystemConfig.gasLimit() // 30_000_000 gas, 30Mgas    
    ```

    Current target = `30Mgas / 6 = 5Mgas per block`
  </Step>

  <Step title="Set new EIP-1559 params">
    Use value from previous step as input to set new params and reduce the `elasticity` from `6` to `3`:

    ```solidity theme={null}
    SystemConfig.setEIP1559Params(denominator, 3)
    ```

    New target = `30Mgas / 3 = 10Mgas per block`
  </Step>
</Steps>

## Post-activation monitoring

What to monitor after executing the gas changes.

### SystemConfig contract values

* `SystemConfig.gasLimit()`
* `SystemConfig.eip1559Denominator()`
* `SystemConfig.eip1559Elasticity()`

### Block explorer

For example, on [OP Mainnet](https://optimistic.etherscan.io/blocks):

* Any block with `gasUsed > gasTarget` should cause the base fee to increase
* Any block with `gasUsed < gasTarget` should cause the base fee to decrease

### Node performance

* Verify nodes are processing blocks faster than the block period
* Monitor CPU/memory usage and p99 tail latency of block processing


# Key management
Source: https://docs.optimism.io/chain-operators/guides/management/key-management

Understand the key management considerations for a chain's privileged roles: which keys must stay online as hot wallets, which belong in cold wallets, and where HSMs and multisigs fit.

This page explains the key management considerations behind the privileged roles on your chain.
There are certain [privileged roles](/op-stack/protocol/privileged-roles) that
need careful consideration. The privileged roles are categorized as hot wallets
or cold wallets.

## Hot wallets

The addresses for the `Batcher` and the `Proposer` need to have their private
keys online somewhere for a component of the system to work. If these addresses
are compromised, the system can be exploited.

It is up to the chain operator to make the decision on how they want to manage
these keys. One suggestion is to use a Hardware Security Module (HSM) to provide
a safer environment for key management. Cloud providers oftentimes provide
Key Management Systems (KMS) that can work with your developer operations
configurations. This can be used in conjunction with the `eth_signTransaction`
RPC method.

<Info>
  You can take a look at the signer client [source code](https://github.com/ethereum-optimism/optimism/blob/develop/op-service/signer/client.go)
  if you're interested in what's happening under the hood.
</Info>

## Cold wallets

The addresses for the cold wallets cannot be used without human intervention.
These can be set up as multisig contracts, so they can be controlled by groups
of community members and avoid a single point of failure. The signers behind a
multisig should probably also use a hardware wallet.

<Info>
  Refer to the [privileged roles](/op-stack/protocol/privileged-roles) documentation
  for more information about these different addresses and their security concerns.
</Info>


# Network Design Example
Source: https://docs.optimism.io/chain-operators/guides/management/network-architecture

This document describes an example network configuration for an OP Stack chain deployment.

This document describes an example configuration for an OP Stack network deployment, focusing on the network architecture and node configuration required for production usage.

<img alt="OP Stack network design example (op-reth)" />

## Sequencers

Sequencers receive transactions from the Tx Ingress Nodes via execution-layer p2p gossip and work with the batcher and proposer to create new blocks.

### Node Configuration

* **Sequencer op-reth** can be either full or archive. op-reth runs as an archive node by default; pass `--full` to run a (pruned) full node. Full nodes offer better performance but can't recover from deep L1 reorgs, so run at least one archive sequencer as a backup.
* **Sequencer op-node** should have p2p discovery disabled and only be statically peered with other internal nodes (or use [peer-management-service](https://github.com/ethereum-optimism/infra/tree/main/peer-mgmt-service) to define peering network).
* The **op-conductor** RPC can act as a leader-aware RPC proxy for op-batcher (proxies the necessary op-reth / op-node RPC methods if the node is the leader).
* Sequencers should have local transaction backup (journalling) disabled.

### op-node Configuration

```yaml theme={null}
OP_NODE_P2P_NO_DISCOVERY: "true"
OP_NODE_P2P_PEER_BANNING: "false"
OP_NODE_P2P_STATIC: "<static peer list>"
```

### op-reth Configuration

op-reth is configured via CLI flags rather than `GETH_*` environment variables:

```sh theme={null}
# Leave --rollup.disable-tx-pool-gossip unset so transactions are gossiped to the internal network
--txpool.disable-transactions-backup   # disable local transaction backup/journalling
--txpool.lifetime 3600                  # 1h, in seconds
--txpool.nolocals
--netrestrict "10.0.0.0/8"              # ex: restrict p2p to internal ips
```

## Tx Ingress Nodes

These nodes receive `eth_sendRawTransaction` calls from the public and then gossip the transactions to the internal execution-layer network. This allows the Sequencer to focus on block creation while these nodes handle transaction ingress.

### Node Configuration

* These can be either full or archive nodes.
* They participate in the internal tx pool p2p network to forward transactions to sequencers.

### Configuration

```sh theme={null}
# Leave --rollup.disable-tx-pool-gossip unset so transactions are gossiped to sequencers
--txpool.disable-transactions-backup
--txpool.lifetime 3600                  # 1h, in seconds
--txpool.nolocals
--netrestrict "10.0.0.0/8"              # ex: restrict p2p to internal ips
```

## Archive RPC Nodes

We recommend setting up some archive nodes for internal RPC usage, primarily used by the challenger, proposer, and security monitoring tools like [monitorism](/chain-operators/tools/chain-monitoring#monitorism).

### Node Configuration

* Archive nodes are essential for accessing historical state data.
* You can also use these nodes for taking disk snapshots for disaster recovery.

### Configuration

op-reth runs as an archive node by default, so no extra flags are required — simply do **not** pass `--full` or `--minimal` (both enable pruning). op-reth stores state in MDBX plus static files, so the geth-specific `GETH_DB_ENGINE` and `GETH_STATE_SCHEME` options have no equivalent.

```sh theme={null}
# op-reth is archive by default; no pruning flags needed.
```

## Full Nodes

These nodes run as full (pruned) nodes. op-reth does not implement geth-style snap sync; it syncs using its own staged-sync pipeline, so the geth `GETH_SYNCMODE`, `GETH_DB_ENGINE`, and `GETH_STATE_SCHEME` options do not apply.

### Configuration

```sh theme={null}
--full        # run a pruned full node (or --minimal for maximum pruning)
```

## P2P Bootnodes (Execution Layer)

These bootnodes facilitate peer discovery for public op-reth nodes.

### Node Configuration

* The bootnode can be an op-reth instance or the [geth bootnode tool](https://etclabscore.github.io/core-geth/core/alltools/).
* You may want to make your Full Nodes serve as your bootnodes as well.

## P2P Bootnodes (Consensus Layer)

These are the op-node p2p network bootnodes. We recommend using the [geth bootnode tool](https://etclabscore.github.io/core-geth/core/alltools/) with discovery v5 enabled.

## Public RPC

Public RPC design is not listed in the above diagram but can be implemented very similarly to Tx Ingress Nodes, with the following differences:

### Configuration Differences

* Public RPC should **not** participate in the internal tx pool p2p network.
  * While it is possible to run Public RPC from the same nodes that serve Tx Ingress and participate in tx pool gossip, there have been execution-client bugs in the past that leaked tx pool details on read RPCs, so it is a possible risk to consider.
* Public RPC [proxyd](https://github.com/ethereum-optimism/infra/tree/main/proxyd) should be run in `consensus_aware` routing mode and whitelist any RPCs you want to serve from op-reth.
* Public RPC nodes should likely be archive nodes.

### About proxyd

Proxyd is an RPC request router and proxy that provides the following capabilities:

1. Whitelists RPC methods.
2. Routes RPC methods to groups of backend services.
3. Automatically retries failed backend requests.
4. Tracks backend consensus (latest, safe, finalized blocks), peer count and sync state.
5. Re-writes requests and responses to enforce consensus.
6. Load balances requests across backend services.
7. Caches immutable responses from backends.
8. Provides metrics to measure request latency, error rates, and the like.

## Next steps

* Learn more about using [proxyd](https://github.com/ethereum-optimism/infra/tree/main/proxyd) for your network.


# Rollup operations
Source: https://docs.optimism.io/chain-operators/guides/management/operations

Learn basics of rollup operations, such as how to start and stop your rollup, get your rollup config, and how to add nodes.

This guide reviews the basics of rollup operations, such as how to start your rollup, stop your rollup, get your rollup config, and add nodes.

## Stopping your rollup

An orderly shutdown is done in the reverse order to the order in which components were started:

<Steps>
  <Step title="To stop the batcher, use this command:">
    ```sh theme={null}
        curl -d '{"id":0,"jsonrpc":"2.0","method":"admin_stopBatcher","params":[]}' \
            -H "Content-Type: application/json" http://localhost:8548 | jq
    ```

    This way the batcher knows to save any data it has cached to L1.
    Wait until you see `Batch Submitter stopped` in batcher's output before you stop the process.
  </Step>

  <Step title="Stop `op-proposer`">
    To stop the proposer, terminate the process directly. This can be done by:

    * Pressing **Ctrl+C** in the terminal running the process
    * Using system commands like `kill -TERM <pid>` to stop the process gracefully

    Ensure that the proposer process has terminated completely before proceeding to stop other components.
  </Step>

  <Step title="Stop `op-node`">
    This component is stateless, so you can just stop the process.
  </Step>

  <Step title="Stop `op-reth`">
    Use **CTRL-C** (SIGINT) so the execution client shuts down gracefully and flushes its database. Killing the process abruptly can leave the database in an inconsistent state and cause problems on the next start.
  </Step>
</Steps>

## Starting your rollup

To restart the blockchain, use the same order of components you did when you initialized it.

<Steps>
  <Step title="Start `op-reth`" />

  <Step title="Start `op-node`" />

  <Step title="Start `op-batcher`">
    If `op-batcher` is still running and you just stopped it using RPC, you can start it with this command:

    ```sh theme={null}
    curl -d '{"id":0,"jsonrpc":"2.0","method":"admin_startBatcher","params":[]}' \
        -H "Content-Type: application/json" http://localhost:8548 | jq   
    ```
  </Step>

  <Step title="Start `op-proposer`">
    Start the proposer using the appropriate command. Here's an example:

    ```sh theme={null}
    ./bin/op-proposer \
      --poll-interval=12s \
      --rpc.port=8560 \
      --rollup-rpc=http://localhost:8547 \
      --l2oo-address=0xYourL2OutputOracleAddress \
      --private-key=$PROPOSER_PRIVATE_KEY \
      --l1-eth-rpc=$L1_RPC_URL
    ```

    | Parameter     | Description                                                    |
    | ------------- | -------------------------------------------------------------- |
    | poll-interval | How often to check for new output proposals (recommended: 12s) |
    | rpc.port      | Local RPC port for the proposer service                        |
    | l2oo-address  | The L2 Output Oracle contract address (0x-prefixed hex)        |
    | private-key   | Private key for signing proposals                              |
    | l1-eth-rpc    | L1 network RPC endpoint URL                                    |
  </Step>
</Steps>

<Info>
  Synchronization takes time

  `op-batcher` might have warning messages similar to:

  ```
  WARN [03-21|14:13:55.248] Error calculating L2 block range         err="failed to get sync status: Post \"http://localhost:8547\": context deadline exceeded"
  WARN [03-21|14:13:57.328] Error calculating L2 block range         err="failed to get sync status: Post \"http://localhost:8547\": context deadline exceeded"
  ```

  This means that `op-node` is not yet synchronized up to the present time.
  Just wait until it is.
</Info>

## Getting your rollup config

Use this tool to get your rollup config from `op-node`. This will only work if your chain is **already** in the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/chainList.json) and `op-node` has been updated to pull those changes in from the registry.

<Info>
  This script will NOT work for chain operators trying to generate this data in order to submit it to the registry.
</Info>

<Steps>
  <Step title="Get your rollup config from `op-node`">
    You'll need to run this tool:

    ```
    ./bin/op-node networks dump-rollup-config --network=op-sepolia   
    {
      "genesis": {
        "l1": {
          "hash": "0x48f520cf4ddaf34c8336e6e490632ea3cf1e5e93b0b2bc6e917557e31845371b",
          "number": 4071408
        },
        "l2": {
          "hash": "0x102de6ffb001480cc9b8b548fd05c34cd4f46ae4aa91759393db90ea0409887d",
          "number": 0
        },
        "l2_time": 1691802540,
        "system_config": {
          "batcherAddr": "0x8f23bb38f531600e5d8fddaaec41f13fab46e98c",
          "overhead": "0x00000000000000000000000000000000000000000000000000000000000000bc",
          "scalar": "0x00000000000000000000000000000000000000000000000000000000000a6fe0",
          "gasLimit": 30000000
        }
      },
      "block_time": 2,
      "max_sequencer_drift": 600,
      "seq_window_size": 3600,
      "channel_timeout": 300,
      "l1_chain_id": 11155111,
      "l2_chain_id": 11155420,
      "regolith_time": 0,
      "canyon_time": 1699981200,
      "delta_time": 1703203200,
      "ecotone_time": 1708534800,
      "batch_inbox_address": "0xff00000000000000000000000000000011155420",
      "deposit_contract_address": "0x16fc5058f25648194471939df75cf27a2fdc48bc",
      "l1_system_config_address": "0x034edd2a225f7f429a63e0f1d2084b9e0a93b538",
      "da_challenge_address": "0x0000000000000000000000000000000000000000",
      "da_challenge_window": 0,
      "da_resolve_window": 0,
      "use_plasma": false
    }
    ```
  </Step>

  <Step title="Check the flags">
    Ensure that you are using the appropriate flag.
    The `--network=op-sepolia` flag allows the tool to pick up the appropriate data from the registry, and uses the OPChains mapping under the hood.
  </Step>
</Steps>

## Adding nodes

To add nodes to the rollup, you need to initialize `op-node` and `op-reth`, similar to what you did for the first node.
You should *not* add an `op-batcher` because there should be only one.

<Steps>
  <Step title="Configure the OS and prerequisites as you did for the first node" />

  <Step title="Install `op-reth` and `op-node` as you did for the first node" />

  <Step title="Copy from the first node these files:">
    ```bash theme={null}
        ~/op-reth/genesis.json
        ~/optimism/op-node/rollup.json
    ```
  </Step>

  <Step title="Create a new `jwt.txt` file as a shared secret:">
    ```bash theme={null}
        cd ~/op-reth
        openssl rand -hex 32 > jwt.txt
        cp jwt.txt ~/optimism/op-node
    ```
  </Step>

  <Step title="Initialize the new op-reth:">
    ```bash theme={null}
        cd ~/op-reth
        op-reth init --chain=./genesis.json --datadir=./datadir
    ```
  </Step>

  <Step title="Turn on peer to peer synchronization to enable L2 nodes to synchronize directly">
    If you do it this way, you won't have to wait until the transactions are written to L1.
    If you already have peer to peer synchronization, add the new node to the `--p2p.static` list so it can synchronize.
  </Step>

  <Step title="Start `op-reth` (using the same command line you used on the initial node)">
    <Info>
      **Important:** Make sure to configure the `--rollup.sequencer` flag (alias `--rollup.sequencer-http`) to point to your sequencer node. This endpoint is crucial because `op-reth` will route `eth_sendRawTransaction` calls to this URL. The OP Stack does not currently have a public mempool, so configuring this is required if you want your node to support transaction submission.
    </Info>
  </Step>

  <Step title="Start `op-node` (using the same command line you used on the initial node)" />
</Steps>

## Next steps

* See the [Consensus Client Configuration](/node-operators/guides/configuration/consensus-clients) and [Execution Client Configuration](/node-operators/guides/configuration/execution-clients) guides for additional explanation or customization.
* If you experience difficulty at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions).


# Transaction Fees 101
Source: https://docs.optimism.io/chain-operators/guides/management/transaction-fees-101

How to check and tune the fee parameters on your OP Stack chain, with example scenarios for common situations.

This guide shows how to check and adjust the fee-related parameters on your chain's `SystemConfig` contract, and when each adjustment makes sense. It applies to the Jovian and following hardforks.

* For how each fee component is calculated, see [transaction fees on OP Mainnet](https://docs.optimism.io/op-stack/transactions/fees#transaction-fees-on-op-mainnet).
* For the full parameter catalogue — types, setters, and the OP Mainnet values — see the [fee parameters reference](/chain-operators/reference/fee-parameters).

On an OP Stack chain a transaction's **Total Fee** is made of three main components:

`Total Fee = L2 Fee + L1 Fee + Operator Fee`

Fees are gathered in dedicated contract [fee vaults](/op-stack/transactions/fee-vaults) that collect the different fee components (for example `BaseFeeVault`, `SequencerFeeVault`, etc.). See the [fee vault operations guide](/chain-operators/guides/management/fee-vaults) for how to manage and withdraw from these vaults.

## Before you start

<Info>
  Only the [SystemConfig owner](/op-stack/protocol/privileged-roles) can change these parameters.
</Info>

Export the values used by all the commands below:

```bash theme={null}
export L1_RPC=<L1_RPC>
export SYSTEM_CONFIG=<SYSTEM_CONFIG_ADDRESS>
export PK=<SYSTEM_CONFIG_OWNER_PRIVATE_KEY>
```

## Tune the L2 fee

The L2 fee is the EVM execution cost: `gasUsed * (baseFee + priorityFee)`. The `baseFee` is computed with the EIP-1559 mechanism and is **collected in the BaseFeeVault (not burned)** on OP Stack.

You can tune L2 fee dynamics on the SystemConfig via:

* `eip1559Denominator`: EIP-1559 max-change denominator, it appears in the denominator of the per-block base fee delta. Lower = faster response, so base fee adjusts faster but results in more volatility.
* `eip1559Elasticity`: elasticity multiplier, sets the target relative to gasLimit. As `gas_target = gasLimit / elasticity`, a **smaller gas target** (larger elasticity) means the base fee will start increasing at a lower block gas usage (i.e., base fee increases sooner under load).
* `gasLimit`: max gas per block. Lower `gasLimit` = less available gas per block (less supply), which makes base fees more sensitive to demand and can cause the base fee to move more easily.
* `minBaseFee`: minimum floor on base fee, in wei (it can be 0). See [setting the minimum base fee](/chain-operators/guides/features/setting-min-base-fee).

### Check current values

```bash theme={null}
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "eip1559Denominator()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "eip1559Elasticity()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "minBaseFee()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "gasLimit()"
```

### Set values

```bash theme={null}
cast send --rpc-url $L1_RPC --private-key $PK \
  $SYSTEM_CONFIG "setEIP1559Params(uint32,uint32)" <denominator> <elasticity>
cast send --rpc-url $L1_RPC --private-key $PK \
  $SYSTEM_CONFIG "setMinBaseFee(uint64)" <minBaseFeeWei>
cast send --rpc-url $L1_RPC --private-key $PK \
  $SYSTEM_CONFIG "setGasLimit(uint64)" <gasLimit>
```

## Tune the L1 fee

The L1 fee charges for posting L2 data to L1: the transaction's estimated compressed (FastLZ) size is multiplied by a scalar-weighted L1 price. See the [fee parameters reference](/chain-operators/reference/fee-parameters#fee-formulas) for the formula.

Reasons to tweak it:

* Modify margin charged on top of expected costs
* Adjust FastLZ estimates to reflect costs
* Differentiate charges for per-byte vs per-blob costs to reflect actual L1 pricing

The knobs:

* `basefeeScalar`: scales the `l1BaseFee` contribution to the L1 data fee (per-byte).
* `blobBaseFeeScalar`: scales the `l1BlobBaseFee` contribution (per-blob).

### Check current values

```bash theme={null}
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "basefeeScalar()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "blobbasefeeScalar()"
```

### Set values

```bash theme={null}
cast send --rpc-url $L1_RPC --private-key $PK \
  $SYSTEM_CONFIG "setGasConfigEcotone(uint32,uint32)" <basefeeScalar> <blobBaseFeeScalar>
```

## Tune the operator fee

The operator fee is a discretionary, non-standard fee charged per transaction: `(gasUsed * operatorFeeScalar * 100) + operatorFeeConstant`. See [setting the operator fee](/chain-operators/guides/features/setting-operator-fee) for a dedicated guide.

* `operatorFeeScalar`: per-gas operator margin.
* `operatorFeeConstant`: flat per-transaction operator fee, in wei.

<Warning>
  Any non-zero operator fee makes the chain configuration [non-standard](/op-stack/protocol/superchain-registry#what-is-a-standard-chain).
</Warning>

### Check current values

```bash theme={null}
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "operatorFeeScalar()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "operatorFeeConstant()"
```

### Set values

```bash theme={null}
cast send --rpc-url $L1_RPC --private-key $PK \
  $SYSTEM_CONFIG "setOperatorFeeScalars(uint32,uint64)" <operatorFeeScalar> <operatorFeeConstant>
```

## Tune the DA footprint limit

The `daFootprintGasScalar` is an in-protocol limit on estimated DA usage to prevent DA spam and priority fee auctions. See [how the DA footprint block limit works](/chain-operators/reference/da-footprint) for the concept and the [DA footprint setup guide](/chain-operators/guides/features/setting-da-footprint) for a dedicated walkthrough.

* Default value is **400**
* A value of **0** is treated as **400**
* Setting it to **1** effectively disables DA footprint limiting

### Check current value

```bash theme={null}
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "daFootprintGasScalar()"
```

### Set value

```bash theme={null}
cast send --rpc-url $L1_RPC --private-key $PK \
  $SYSTEM_CONFIG "setDAFootprintGasScalar(uint16)" <daFootprintGasScalar>
```

## Example scenarios

### Normal traffic / below EIP-1559 target

**What you'll see**

* If blocks stay below the EIP-1559 target, `baseFee` trends toward the `minBaseFee` floor.
* When L1 data usage is low, the L2 execution fee (`gasUsed * (baseFee + priorityFee)`) is typically the largest cost component.
* The L1 data fee remains low/steady if calldata per transaction is small.

**What to tweak**

* Usually nothing.
* If you need a revenue floor set/increase `minBaseFee`.

**Tradeoff**

* **Pros:** `minBaseFee` prevents prolonged low base fees and provides a predictable minimum (can be left at 0 to improve UX).
* **Cons:** If set too high, it raises inclusion cost for low-value transactions and can negatively impact UX/accessibility.

***

### Busy blocks / congestion

**What you'll see**

* `baseFee` rises when blocks exceed the target: `gas_target = gasLimit / eip1559Elasticity`
* Transactions with low priority tips may experience slower inclusion during congestion.

**What to tweak**

* `eip1559Elasticity` and `eip1559Denominator` :
  * To increase responsiveness: decrease `eip1559Denominator` and/or increase `eip1559Elasticity` (smaller target → baseFee increases sooner).
  * To decrease volatility: increase `eip1559Denominator` and/or reduce aggressiveness in `eip1559Elasticity`.

**Tradeoff**

* **Pros:** Faster base fee response better captures demand; elasticity provides direct control over the gas target.
* **Cons:** Smaller denominator and/or aggressive elasticity increases per-block swings and increases fee volatility.

***

### Calldata-heavy transactions

**What you'll see**

* L1 data fee becomes a larger share of total cost for calldata heavy transactions (the L1 fee scales with compressed calldata size).
* Increasing `basefeeScalar` increases the per-byte L1 charge, making calldata heavy transactions more expensive.

**What to tweak**

* `basefeeScalar` and `blobBaseFeeScalar`:
  * Increase them if you need to recover more L1/DA posting costs from data heavy transactions.
  * Decrease them if you want to reduce user cost for calldata/blob-heavy workloads.

**Tradeoff**

* **Pros:** Enables proportional recovery of L1/DA posting costs.
* **Cons:** Penalizes calldata/blob-heavy dapps/users. Aggressive values can impact UX and reduce activity.

***

### Predictable operator revenue

**What you'll see**

* Introducing or increasing `operatorFeeScalar` raises the per-gas operator charge and increases predictable revenue per transaction.
* `operatorFeeConstant` adds a flat per-transaction fee regardless of gas usage.

**What to tweak**

* `operatorFeeScalar` and `operatorFeeConstant`:
  * Use when you want direct, predictable operator revenue independent of congestion and L1 fee dynamics.

**Tradeoff**

* **Pros:** Direct and predictable revenue per transaction.
* **Cons:** May discourage low-value transactions and changes transaction economics; should be used carefully. Any non-zero operator fee makes the chain configuration non-standard.

***

### DA-heavy workloads / DA-spam resistance

**What you'll see**

* DA footprint can limit how much transaction data fits into a block through scaled accounting of compressed DA usage.
* Increasing `daFootprintGasScalar` raises the gas charged per DA-byte footprint, reducing DA capacity for the same byte footprint and deterring DA-heavy patterns.

**What to tweak**

* `daFootprintGasScalar`:
  * Default is **400**, and `0` is treated as the default.
  * Setting it to **1** disables the DA footprint limiting behavior.

**Tradeoff**

* **Pros:** Deters DA spam and makes DA costs explicit in block accounting.
* **Cons:** Increasing it reduces DA capacity and may throttle the batcher or exclude legitimate DA-heavy workloads if set too aggressively.

***

## Summary

1. Make sure to check your current hardfork, this doc applies to Jovian and following hardforks.
2. Check the current fee parameters on your SystemConfig contract (see the [fee parameters reference](/chain-operators/reference/fee-parameters) for the expected values on OP Mainnet).
3. Make small changes and observe: vault balances, inclusion times, dropped txs, DA throttling, etc.
4. Extensively test all changes on a staging/testnet.
5. Communicate changes to dapp/wallet teams (gas estimation will change).

***

## References

* [Fee parameters reference](/chain-operators/reference/fee-parameters)
* [Transaction fees on OP Mainnet](https://docs.optimism.io/op-stack/transactions/fees#transaction-fees-on-op-mainnet)
* [Operator fee](https://docs.optimism.io/op-stack/transactions/fees#operator-fee)
* [L1 data fee](https://docs.optimism.io/op-stack/transactions/fees#l1-data-fee)
* [SystemConfig interface](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L1/ISystemConfig.sol)
* [DA footprint](https://docs.optimism.io/notices/archive/upgrade-17#block-header-changes)
* [EIP-1559](https://docs.optimism.io/op-stack/protocol/differences#eip-1559-parameters)
* [OP Mainnet values](https://etherscan.io/address/0x229047fed2591dbec1eF1118d64F7aF3dB9EB290#readProxyContract)


# Troubleshooting chain operations
Source: https://docs.optimism.io/chain-operators/guides/management/troubleshooting

Learn solutions to common problems when troubleshooting chain operations.

This page lists common troubleshooting scenarios and solutions for chain operators.

## EvmError in contract deployment

L1 smart contract deployment fails with the following error:

```text theme={null}
EvmError: Revert
```

### Solution

The OP Stack uses deterministic smart contract deployments to guarantee that all contract addresses can be computed ahead of time based on a "salt" value that is provided at deployment time.
Each OP Stack chain must have a unique salt value to ensure that the contract addresses do not collide with other OP Stack chains.

You can avoid this error by changing the salt used when deploying the L1 smart contracts.
The salt value is set by the `IMPL_SALT` environment variable when deploying the contracts.
The `IMPL_SALT` value must be a 32 byte hex string.

You can generate a random salt value using the following command:

```bash theme={null}
export IMPL_SALT=$(openssl rand -hex 32)
```

## Failed to find the L2 Heads to start from

`op-node` fails to execute the derivation process with the following error:

```text theme={null}
WARN [02-16|21:22:02.868] Derivation process temporary error       attempts=14 err="stage 0 failed resetting: temp: failed to find the L2 Heads to start from: failed to fetch L2 block by hash 0x0000000000000000000000000000000000000000000000000000000000000000: failed to determine block-hash of hash 0x0000000000000000000000000000000000000000000000000000000000000000, could not get payload: not found"
```

### Solution

This error can occur when the data directory for `op-reth` becomes corrupted (for example, as a result of a computer crash).
You will need to reinitialize the data directory.

If you are following the tutorial for [Creating Your Own L2 Rollup](/chain-operators/tutorials/create-l2-rollup), make sure to rerun the commands within the [Spin up sequencer](/chain-operators/tutorials/create-l2-rollup/op-reth-setup) section.

If you are not following the tutorial, make sure to take the following steps:

1. Stop `op-node` and `op-reth`.
2. Delete the corresponding `op-reth` data directory.
3. Reinitialize `op-reth` with the `genesis.json` file: `op-reth init --chain=./genesis.json --datadir=./datadir`.
4. Restart `op-reth` and `op-node`.

## Batcher unable to publish transaction

`op-batcher` fails to publish transactions with the following error:

```text theme={null}
INFO [03-21|14:22:32.754] publishing transaction                   service=batcher txHash=2ace6d..7eb248 nonce=2516 gasTipCap=2,340,741 gasFeeCap=172,028,434,515
ERROR[03-21|14:22:32.844] unable to publish transaction            service=batcher txHash=2ace6d..7eb248 nonce=2516 gasTipCap=2,340,741 gasFeeCap=172,028,434,515 err="insufficient funds for gas * price + value"
```

### Solution

You will observe this error if the `op-batcher` runs out of ETH to publish transactions to L1.
This problem can be resolved by sending additional ETH to the `op-batcher` address.


# Chain operators
Source: https://docs.optimism.io/chain-operators/index

Routes chain operators to the quickstart, guides, tutorials, tools, and reference for launching and running an OP Stack chain.

You are launching or operating your own OP Stack chain. Deploy first, then
use the guides, tools, and reference material to run it in production.

<CardGroup>
  <Card title="Deploy a chain" href="/chain-operators/quickstart">
    Launch your first OP Stack chain with op-deployer.
  </Card>

  <Card title="Configure and manage your chain" href="/chain-operators/guides/configuration/getting-started">
    Set up the batcher, proposer, and challenger, enable features, and follow
    production best practices.
  </Card>

  <Card title="Work through a tutorial" href="/chain-operators/tutorials/create-l2-rollup">
    Build a rollup component by component, upgrade L1 contracts, and
    customize your chain step by step.
  </Card>

  <Card title="Run the supporting tools" href="/chain-operators/tools/op-deployer/overview">
    Operate op-deployer, op-conductor, chain monitoring, and the RPC
    frontends that keep a chain healthy.
  </Card>

  <Card title="Look up configuration reference" href="/chain-operators/reference/batcher-configuration">
    Check flag-level reference for the batcher, challenger, deployment
    configuration, and fee parameters.
  </Card>

  <Card title="Not running your own chain?" href="/">
    Route by role from the documentation home: app developers, node
    operators, and protocol learners each have their own section.
  </Card>
</CardGroup>


# Choose how to run your chain
Source: https://docs.optimism.io/chain-operators/launch-paths

The spectrum between running an OP Stack chain yourself and having it operated for you, and what your team owns at each point on it.

Every team launching an OP Stack chain lands somewhere on the same spectrum. At
one end, your team runs every service and holds every key. At the other end,
someone runs them for you. The choice is not about capability: it is about which
parts of a standing operation your team wants to own.

This page describes the spectrum and what falls to your team at each point on
it. It does not pick a point for you. The pages linked below document the whole
system regardless of who operates it.

## The spectrum

|                     | Run it yourself                | Run it with engineering support               | Have it operated for you                   |
| ------------------- | ------------------------------ | --------------------------------------------- | ------------------------------------------ |
| Sequencer cluster   | Your team                      | Your team, with OP Labs engineering behind it | OP Enterprise                              |
| Fault-proof defense | Your team                      | Your team, with OP Labs engineering behind it | OP Enterprise                              |
| Upgrade execution   | Your team                      | Your team, with OP Labs engineering behind it | OP Enterprise                              |
| Incident response   | Your team                      | Your team, with OP Labs engineering behind it | OP Enterprise                              |
| These docs          | The reference for what you run | The reference for what you run                | The reference for what runs on your behalf |

## Run it yourself

Your team runs every service, holds every key, and owns every incident. These
docs cover all of it, and every destination below is one click away.

What that ownership includes, stated the way the docs themselves state it:

### The services you run

* **The sequencer.** A single sequencer is a single point of failure for the
  whole chain: when it stops, no new unsafe blocks exist for anyone. The
  high-availability answer is a sequencer cluster managed by
  [op-conductor](/chain-operators/tools/op-conductor), with its nodes in
  separate failure domains. The design is not Byzantine fault tolerant: it
  assumes every node in the cluster is honest and operated by you, so it
  protects against crashes and partitions, not against a malicious cluster
  member. See
  [the launch guide's sequencer topology step](/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing#step-3-design-the-sequencer-topology).
* **The defense.** The defense is a service you run and a set of decisions
  your team staffs. The
  [`op-challenger`](/op-stack/fault-proofs/challenger) is a service that
  monitors every game, defends valid proposals, challenges invalid ones,
  resolves games, and claims bonds. Starting it is not the whole job. Every
  claim it posts carries a bond sent as transaction value; correct claims are
  refunded, incorrect ones pay the counter-claimer, and bonds from won games
  pay out only after a delay, so capital stays locked while games resolve.
  How much the challenger's account holds, how quickly you can top it up
  during an active dispute, and which absolute prestate it plays with are
  operational answers your team owns; the challenger refuses to interact with
  games whose prestate it does not have. See
  [Run a fault-proof challenger](/use-cases/run-a-fault-proof-challenger).
* **The monitoring.** Watching the chain is a separate set of services from
  running it. `op-dispute-mon` tracks the status of every dispute game and is
  how you learn that your challenger is acting; `monitorism` carries the
  onchain security monitors, whose security-integrity group exists to check
  that the bridges between L2 and L1 behave as expected, including the
  faultproof withdrawal monitor that watches `ProvenWithdrawals` events on
  the `OptimismPortal` and flags invariant violations. Your own components
  need their metrics endpoints scraped alongside that: `op-node`,
  `op-batcher`, `op-proposer`, and `op-challenger` each expose one. Peer
  count belongs on that list too, because an `op-node` without peers cannot
  sync unsafe blocks and falls behind the sequencer. See
  [Chain monitoring options](/chain-operators/tools/chain-monitoring) and
  [the important node metrics](/node-operators/guides/monitoring/metrics#important-metrics).
* **The RPC endpoints.** Every service in the stack depends on RPC, and not
  only on L1. Each sequencer's op-node derives the chain from an L1 RPC and
  an L1 beacon endpoint, and the batcher, proposer, and challenger read and
  transact against L1; `op-challenger` additionally needs an L2 archive node
  (`--l2-eth-rpc`) and a rollup node with SafeDB (`--rollup-rpc`), and
  `op-dispute-mon` takes a rollup RPC of its own. Redundant nodes behind a
  generic load balancer are the wrong shape for any of them. Two nodes can be
  at the same head, but nothing holds them there, and a service whose
  consecutive requests round-robin between them reads that divergence as
  blocks appearing and disappearing: reorgs that never happened. The
  challenger is the least tolerant consumer and needs one trusted endpoint
  that fails over deliberately rather than per request. See
  [the launch guide's section on a consistent view](/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing#give-every-service-a-consistent-view-of-l1).

### The keys and the decisions

* **The keys.** The batcher and proposer addresses need their private keys
  online somewhere for the system to work, and if those addresses are
  compromised, the system can be exploited. They are not the only privileged
  addresses your chain has. The Proxy Admins can upgrade most of the system
  contracts on L1 and L2, the System Config Owner can change the values in
  the `SystemConfig` contract, the Guardian can pause withdrawal logic and
  disable dispute game types from executing withdrawals, and the permissioned
  Challenger role is a distinct address from the `op-challenger` service.
  Which addresses hold which role, and how each key is held, whether through
  an HSM or a cloud key management system, are decisions the chain operator
  makes. See
  [Key management](/chain-operators/guides/management/key-management) and
  [Privileged roles in OP Stack chains](/op-stack/protocol/privileged-roles#privileged-roles-in-op-stack-chains)
  for what every role can do and what a compromise of it means.
* **The path to permissionless proofs.** Chains deployed with `op-deployer`
  start with the permissioned dispute game, in which the proposer and
  challenger are specific addresses holding privileged roles. Moving to
  permissionless fault proofs is a switch your team schedules after launch.
  See
  [the launch guide's permissionless-proofs step](/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing#step-7-schedule-the-switch-to-permissionless-proofs).

### The work that recurs

* **The protocol upgrade cadence.** The OP Stack is being continuously
  improved and it's your responsibility to keep it up to date. Network
  upgrades, deprecations, security patches, and operational changes arrive as
  time-bound action items in [Network Notices](/notices), with the permanent
  record of each hardfork in the
  [hardfork registry](/op-stack/protocol/network-upgrades), which records
  activation times, the governing spec, and minimum component versions.
  Tracking each notice, moving your components to the versions it names, and
  executing the change on your chain recurs for as long as the chain runs.
* **The standing work.** Running current production releases, keeping the
  deployment artifacts, staggering upgrade rollouts across your
  infrastructure, isolating the sequencer, and writing your own runbooks are
  continuous tasks rather than launch-day ones. Monitoring only helps if
  someone is on the other end of it. Metrics endpoints on your key
  components, and runbooks to execute when something is not behaving as
  expected, are the documented practice; the alerting path, the people
  reachable through it, and the incident response itself are yours to build
  and staff. See
  [Chain operator best practices](/chain-operators/guides/management/best-practices).

<CardGroup>
  <Card title="Deploy a chain, component by component" icon="rocket" href="/chain-operators/tutorials/create-l2-rollup">
    The full deployment tutorial: contracts, genesis, sequencer, batcher,
    proposer, and challenger on a testnet.
  </Card>

  <Card title="Take a chain to production" icon="shield-check" href="/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing">
    The launch guide: fault proofs from day one and a sequencer topology with no
    single point of failure, through failover drills.
  </Card>

  <Card title="Staff the defense" icon="gavel" href="/use-cases/run-a-fault-proof-challenger">
    Bond budgeting, prestate selection, the infrastructure the challenger
    depends on, and how to confirm it is defending your chain.
  </Card>

  <Card title="Run it day to day" icon="wrench" href="/chain-operators/guides/management/best-practices">
    Release selection, deployment artifacts, staggered rollouts, sequencer
    isolation, and runbooks.
  </Card>
</CardGroup>

## Run it with engineering support

Your team still runs the chain. The difference is who sits behind the decisions
above and behind the incidents when they happen: OP Labs engineering does,
alongside your operators. Everything linked in the previous section stays the
reference for what your team is running, because it is the same system.

One capability on this path is not something your team has to stand up itself:
OP Labs can optionally run a backup sequencer for your chain, alongside the
sequencer cluster your team operates. It is opt-in rather than part of the path
by default, and whether to take it is your team's decision.

## Have it operated for you

OP Enterprise runs the chain and your team consumes it. The pages above still
describe what is running on your behalf, which is why they are worth reading on
this path too: the properties you are buying are the ones those pages document.

## What OP Enterprise is

OP Enterprise is Optimism's managed offering. It covers fully managed and
supported self-managed options, backed by an uptime SLA, priority incident
response, direct engineering support, and managed public RPC.

The
[OP Enterprise](https://optimism.io/op-enterprise?utm_source=docs\&utm_medium=docs\&utm_campaign=op-enterprise)
page states what each option includes and is the source of truth for its terms.
This page does not restate them.

## Where to go from here

Whichever point on the spectrum you choose, the
[chain operator quickstart](/chain-operators/quickstart) and the pages it leads
to describe the same chain. Start there if you have not deployed one yet.


# Chain operator quickstart
Source: https://docs.optimism.io/chain-operators/quickstart

Launch a scalable and customizable Layer 2 Rollup blockchain with Ethereum-grade security - powered by Optimism.

Launch your own OP Stack chain: an open-source, modular, Ethereum Layer 2 rollup.
This page orients you on the key components and the sequence of steps, then hands you off to the [full deployment tutorial](/chain-operators/tutorials/create-l2-rollup).

There are two ways to have an OP Stack chain: run it yourself, which is what this page and the tutorial behind it cover, or have it run for you.
[Choose how to run your chain](/chain-operators/launch-paths) sets out the spectrum between them and what your team owns at each point on it.

## Components

Before you deploy, it is important to understand the key components and how they come together to create your blockchain.

* **L1 Smart contracts**: A set of smart contracts to be deployed on Ethereum to bridge between the L1 and L2 domains and manage aspects of the rollup.
* **Sequencer**: A single privileged node that accepts and derives user transactions on the network to construct the blockchain.
* **Batcher**: A sequencer service that publishes L2 transactions onto Ethereum.
  Using Ethereum as a data availability layer, the OP Stack inherits Ethereum's security properties by allowing any node to derive the state of the L2 blockchain from L1.
* **Proposer**: A service responsible for publishing the L2 state root to Ethereum which enables user withdrawals of assets.
* **Challenger**: The challenger enforces network security by disputing invalid state roots that have been posted to Ethereum.

## Deployment

The following section will walk you through the sequence of steps a chain operator will follow to begin sequencing a chain.

<Steps>
  <Step title="Smart contract deployment">
    Using a CLI tool called [op-deployer](/chain-operators/tools/op-deployer/overview) you will configure your chain and then deploy the smart contracts on Ethereum.
  </Step>

  <Step title="Chain genesis creation">
    After deploying the L1 smart contracts, you will use [op-deployer](/chain-operators/tools/op-deployer/overview) to generate two files necessary to run nodes on the L2 network:

    * **Genesis file** (`genesis.json`): Initializes the execution client (`op-reth`)
    * **Rollup configuration file** (`rollup.json`): Configures the consensus client (`op-node`)

    These files contain all the essential information your services need to interact with Ethereum and the system contracts you deployed.
  </Step>

  <Step title="Start sequencing">
    To begin sequencing transactions and building blocks, you will then run an **execution client** and **consensus client** that come together as your **sequencer node**.
  </Step>

  <Step title="Begin batching transactions">
    Next you will run `op-batcher` which will publish user transactions on Ethereum.
  </Step>

  <Step title="Start proposing state roots">
    Then you will run `op-proposer` to publish the L2 state root on Ethereum to enable withdrawals back to Ethereum.
  </Step>

  <Step title="Protect your chain">
    Finally you will run `op-challenger` to monitor and dispute any invalid L2 state roots that have been posted.
  </Step>
</Steps>

<Card title="Start the deployment tutorial" icon="rocket" href="/chain-operators/tutorials/create-l2-rollup">
  Deploy a complete OP Stack testnet, component by component, with a working automated example alongside.
</Card>

## Next Steps

Take a look at some of the [chain operator best practices](/chain-operators/guides/management/best-practices) to get an idea of some of the things you'll need to keep in mind.

<Info>
  **Running this in production**

  <OpEnterpriseCalloutBody />
</Info>


# Batcher configuration reference
Source: https://docs.optimism.io/chain-operators/reference/batcher-configuration

Reference for all op-batcher configuration options, covering CLI flags, environment variables, and default values.

This page catalogues every configuration option for the op-batcher, the service
that posts L2 sequencer data to L1 to make it available for verifiers.

<ConfigReferencePreamble />

For guidance on choosing values — the batcher policy, cost tuning, multi-blob
transactions, and sequencer throttling — see the
[batcher configuration guide](/chain-operators/guides/configuration/batcher).

## Flags

Generated from [`op-batcher/v1.16.11`](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher%2Fv1.16.11)
flag definitions. 87 flags: 3 required, 84 optional.

### Required flags

| Flag           | Description                                                                                                                                                               | Environment variable    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `--l1-eth-rpc` | HTTP provider URL for L1                                                                                                                                                  | `OP_BATCHER_L1_ETH_RPC` |
| `--l2-eth-rpc` | HTTP provider URL for L2 execution engine. A comma-separated list enables the active L2 endpoint provider. Such a list needs to match the number of rollup-rpcs provided. | `OP_BATCHER_L2_ETH_RPC` |
| `--rollup-rpc` | HTTP provider URL for Rollup node. A comma-separated list enables the active L2 endpoint provider. Such a list needs to match the number of l2-eth-rpcs provided.         | `OP_BATCHER_ROLLUP_RPC` |

### Optional flags

| Flag                                         | Description                                                                                                                                                                                                                 | Default                | Environment variable                                  |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ----------------------------------------------------- |
| `--active-sequencer-check-duration`          | The duration between checks to determine the active sequencer endpoint.                                                                                                                                                     | `5s`                   | `OP_BATCHER_ACTIVE_SEQUENCER_CHECK_DURATION`          |
| `--altda.da-server`                          | HTTP address of a DA Server                                                                                                                                                                                                 | —                      | `OP_BATCHER_ALTDA_DA_SERVER`                          |
| `--altda.da-service`                         | Use DA service type where commitments are generated by Alt-DA server                                                                                                                                                        | `false`                | `OP_BATCHER_ALTDA_DA_SERVICE`                         |
| `--altda.enabled`                            | Enable Alt-DA mode Alt-DA Mode is a Beta feature of the MIT licensed OP Stack. While it has received initial review from core contributors, it is still undergoing testing, and may have bugs or other issues.              | `false`                | `OP_BATCHER_ALTDA_ENABLED`                            |
| `--altda.get-timeout`                        | Timeout for get requests. 0 means no timeout.                                                                                                                                                                               | `0s`                   | `OP_BATCHER_ALTDA_GET_TIMEOUT`                        |
| `--altda.max-concurrent-da-requests`         | Maximum number of concurrent requests to the DA server                                                                                                                                                                      | `1`                    | `OP_BATCHER_ALTDA_MAX_CONCURRENT_DA_REQUESTS`         |
| `--altda.put-timeout`                        | Timeout for put requests. 0 means no timeout.                                                                                                                                                                               | `0s`                   | `OP_BATCHER_ALTDA_PUT_TIMEOUT`                        |
| `--altda.verify-on-read`                     | Verify input data matches the commitments from the DA storage service                                                                                                                                                       | `true`                 | `OP_BATCHER_ALTDA_VERIFY_ON_READ`                     |
| `--approx-compr-ratio`                       | The approximate compression ratio (\<= 1.0). Only relevant for ratio compressor.                                                                                                                                            | `0.6`                  | `OP_BATCHER_APPROX_COMPR_RATIO`                       |
| `--batch-type`                               | The batch type. 0 for SingularBatch and 1 for SpanBatch.                                                                                                                                                                    | `singular`             | `OP_BATCHER_BATCH_TYPE`                               |
| `--check-recent-txs-depth`                   | Indicates how many blocks back the batcher should look during startup for a recent batch tx on L1. This can speed up waiting for node sync. It should be set to the verifier confirmation depth of the sequencer (e.g. 4).  | `0`                    | `OP_BATCHER_CHECK_RECENT_TXS_DEPTH`                   |
| `--compression-algo`                         | The compression algorithm to use. Valid options: zlib, brotli, brotli-9, brotli-10, brotli-11                                                                                                                               | `zlib`                 | `OP_BATCHER_COMPRESSION_ALGO`                         |
| `--compressor`                               | The type of compressor. Valid options: none, ratio, shadow                                                                                                                                                                  | `"shadow"`             | `OP_BATCHER_COMPRESSOR`                               |
| `--data-availability-type`                   | The data availability type to use for submitting batches to the L1. Valid options: calldata, blobs, auto                                                                                                                    | `calldata`             | `OP_BATCHER_DATA_AVAILABILITY_TYPE`                   |
| `--fee-limit-multiplier`                     | The multiplier applied to fee suggestions to put a hard limit on fee increases                                                                                                                                              | `5`                    | `OP_BATCHER_TXMGR_FEE_LIMIT_MULTIPLIER`               |
| `--hd-path`                                  | The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic flag must also be set.                                                                                                                      | —                      | `OP_BATCHER_HD_PATH`                                  |
| `--log.color`                                | Color the log output if in terminal mode                                                                                                                                                                                    | `false`                | `OP_BATCHER_LOG_COLOR`                                |
| `--log.format`                               | Format the log output. Supported formats: text, terminal, logfmt, logfmtms, json, jsonms                                                                                                                                    | `text`                 | `OP_BATCHER_LOG_FORMAT`                               |
| `--log.level`                                | The lowest log level that will be output                                                                                                                                                                                    | `INFO`                 | `OP_BATCHER_LOG_LEVEL`                                |
| `--log.pid`                                  | Show pid in the log                                                                                                                                                                                                         | `false`                | `OP_BATCHER_LOG_PID`                                  |
| `--max-blocks-per-span-batch`                | Maximum number of blocks to add to a span batch. Default is 0 - no maximum.                                                                                                                                                 | `0`                    | `OP_BATCHER_MAX_BLOCKS_PER_SPAN_BATCH`                |
| `--max-channel-duration`                     | The maximum duration of L1-blocks to keep a channel open. 0 to disable.                                                                                                                                                     | `0`                    | `OP_BATCHER_MAX_CHANNEL_DURATION`                     |
| `--max-l1-tx-size-bytes`                     | The maximum size of a batch tx submitted to L1. Ignored for blobs, where max blob size will be used.                                                                                                                        | `120000`               | `OP_BATCHER_MAX_L1_TX_SIZE_BYTES`                     |
| `--max-pending-tx`                           | The maximum number of pending transactions. 0 for no limit.                                                                                                                                                                 | `1`                    | `OP_BATCHER_MAX_PENDING_TX`                           |
| `--metrics.addr`                             | Metrics listening address                                                                                                                                                                                                   | `"0.0.0.0"`            | `OP_BATCHER_METRICS_ADDR`                             |
| `--metrics.enabled`                          | Enable the metrics server                                                                                                                                                                                                   | `false`                | `OP_BATCHER_METRICS_ENABLED`                          |
| `--metrics.port`                             | Metrics listening port                                                                                                                                                                                                      | `7300`                 | `OP_BATCHER_METRICS_PORT`                             |
| `--mnemonic`                                 | The mnemonic used to derive the wallets for either the service                                                                                                                                                              | —                      | `OP_BATCHER_MNEMONIC`                                 |
| `--network-timeout`                          | Timeout for all network operations                                                                                                                                                                                          | `10s`                  | `OP_BATCHER_NETWORK_TIMEOUT`                          |
| `--num-confirmations`                        | Number of confirmations which we will wait after sending a transaction                                                                                                                                                      | `10`                   | `OP_BATCHER_NUM_CONFIRMATIONS`                        |
| `--poll-interval`                            | How frequently to poll L2 for new blocks                                                                                                                                                                                    | `6s`                   | `OP_BATCHER_POLL_INTERVAL`                            |
| `--pprof.addr`                               | pprof listening address                                                                                                                                                                                                     | `"0.0.0.0"`            | `OP_BATCHER_PPROF_ADDR`                               |
| `--pprof.enabled`                            | Enable the pprof server                                                                                                                                                                                                     | `false`                | `OP_BATCHER_PPROF_ENABLED`                            |
| `--pprof.path`                               | pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof                                                                                                                                               | —                      | `OP_BATCHER_PPROF_PATH`                               |
| `--pprof.port`                               | pprof listening port                                                                                                                                                                                                        | `6060`                 | `OP_BATCHER_PPROF_PORT`                               |
| `--pprof.type`                               | pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs                                                                                                                                         | —                      | `OP_BATCHER_PPROF_TYPE`                               |
| `--private-key`                              | The private key to use with the service. Must not be used with mnemonic.                                                                                                                                                    | —                      | `OP_BATCHER_PRIVATE_KEY`                              |
| `--resubmission-timeout`                     | Duration we will wait before resubmitting a transaction to L1                                                                                                                                                               | `48s`                  | `OP_BATCHER_RESUBMISSION_TIMEOUT`                     |
| `--rpc.addr`                                 | rpc listening address                                                                                                                                                                                                       | `"0.0.0.0"`            | `OP_BATCHER_RPC_ADDR`                                 |
| `--rpc.enable-admin`                         | Enable the admin API                                                                                                                                                                                                        | `false`                | `OP_BATCHER_RPC_ENABLE_ADMIN`                         |
| `--rpc.port`                                 | rpc listening port                                                                                                                                                                                                          | `8545`                 | `OP_BATCHER_RPC_PORT`                                 |
| `--safe-abort-nonce-too-low-count`           | Number of ErrNonceTooLow observations required to give up on a tx at a particular nonce without receiving confirmation                                                                                                      | `3`                    | `OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT`           |
| `--sequencer-hd-path`                        | DEPRECATED: The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic flag must also be set.                                                                                                          | —                      | `OP_BATCHER_SEQUENCER_HD_PATH`                        |
| `--signer.address`                           | Address the signer is signing requests for                                                                                                                                                                                  | —                      | `OP_BATCHER_SIGNER_ADDRESS`                           |
| `--signer.endpoint`                          | Signer endpoint the client will connect to                                                                                                                                                                                  | —                      | `OP_BATCHER_SIGNER_ENDPOINT`                          |
| `--signer.header`                            | Headers to pass to the remote signer. Format `key=value`. Value can contain any character allowed in a HTTP header. When using env vars, split with commas. When using flags one key value pair per flag.                   | —                      | `OP_BATCHER_SIGNER_HEADER`                            |
| `--signer.tls.ca`                            | tls ca cert path                                                                                                                                                                                                            | `"tls/ca.crt"`         | `OP_BATCHER_SIGNER_TLS_CA`                            |
| `--signer.tls.cert`                          | tls cert path                                                                                                                                                                                                               | `"tls/tls.crt"`        | `OP_BATCHER_SIGNER_TLS_CERT`                          |
| `--signer.tls.enabled`                       | Enable or disable TLS client authentication for the signer                                                                                                                                                                  | `true`                 | `OP_BATCHER_SIGNER_TLS_ENABLED`                       |
| `--signer.tls.key`                           | tls key                                                                                                                                                                                                                     | `"tls/tls.key"`        | `OP_BATCHER_SIGNER_TLS_KEY`                           |
| `--stopped`                                  | Initialize the batcher in a stopped state. The batcher can be started using the admin\_startBatcher RPC                                                                                                                     | `false`                | `OP_BATCHER_STOPPED`                                  |
| `--sub-safety-margin`                        | The batcher tx submission safety margin (in #L1-blocks) to subtract from a channel's timeout and sequencing window, to guarantee safe inclusion of a channel on L1.                                                         | `10`                   | `OP_BATCHER_SUB_SAFETY_MARGIN`                        |
| `--target-num-frames`                        | The target number of frames to create per channel. Controls number of blobs per blob tx, if using Blob DA.                                                                                                                  | `1`                    | `OP_BATCHER_TARGET_NUM_FRAMES`                        |
| `--throttle.additional-endpoints`            | Comma-separated list of endpoints to distribute throttling configuration to (in addition to the L2 endpoints specified with --l2-eth-rpc).                                                                                  | —                      | `OP_BATCHER_THROTTLE_ADDITIONAL_ENDPOINTS`            |
| `--throttle.block-size-lower-limit`          | The limit on the DA size of blocks when we are at maximum throttle intensity (linear and quadratic controllers only). 0 means no limits will ever be applied, so consider 1 the smallest effective limit.                   | `2000`                 | `OP_BATCHER_THROTTLE_BLOCK_SIZE_LOWER_LIMIT`          |
| `--throttle.block-size-upper-limit`          | The limit on the DA size of blocks when we are at 0 throttle intensity (applied when throttling is inactive)                                                                                                                | `130000`               | `OP_BATCHER_THROTTLE_BLOCK_SIZE_UPPER_LIMIT`          |
| `--throttle.controller-type`                 | Type of throttle controller to use: 'step', 'linear', 'quadratic' (default) or 'pid' (EXPERIMENTAL - use with caution)                                                                                                      | `"quadratic"`          | `OP_BATCHER_THROTTLE_CONTROLLER_TYPE`                 |
| `--throttle.pid-integral-max`                | EXPERIMENTAL: PID controller maximum integral windup. Only relevant if --throttle-controller-type is set to 'pid'                                                                                                           | `1000`                 | `OP_BATCHER_THROTTLE_PID_INTEGRAL_MAX`                |
| `--throttle.pid-kd`                          | EXPERIMENTAL: PID controller derivative gain. Only relevant if --throttle-controller-type is set to 'pid'                                                                                                                   | `0.05`                 | `OP_BATCHER_THROTTLE_PID_KD`                          |
| `--throttle.pid-ki`                          | EXPERIMENTAL: PID controller integral gain. Only relevant if --throttle-controller-type is set to 'pid'                                                                                                                     | `0.01`                 | `OP_BATCHER_THROTTLE_PID_KI`                          |
| `--throttle.pid-kp`                          | EXPERIMENTAL: PID controller proportional gain. Only relevant if --throttle-controller-type is set to 'pid'                                                                                                                 | `0.33`                 | `OP_BATCHER_THROTTLE_PID_KP`                          |
| `--throttle.pid-output-max`                  | EXPERIMENTAL: PID controller maximum output. Only relevant if --throttle-controller-type is set to 'pid'                                                                                                                    | `1`                    | `OP_BATCHER_THROTTLE_PID_OUTPUT_MAX`                  |
| `--throttle.pid-sample-time`                 | EXPERIMENTAL: PID controller sample time interval, default is 2s                                                                                                                                                            | `2s`                   | `OP_BATCHER_THROTTLE_PID_SAMPLE_TIME`                 |
| `--throttle.tx-size-lower-limit`             | The limit on the DA size of transactions when we are at maximum throttle intensity. 0 means no limits will ever be applied, so consider 1 the smallest effective limit.                                                     | `150`                  | `OP_BATCHER_THROTTLE_TX_SIZE_LOWER_LIMIT`             |
| `--throttle.tx-size-upper-limit`             | The limit on the DA size of transactions when we are at 0+ throttle intensity (limit of the intensity as it approaches 0 from positive values). Not applied when throttling is inactive.                                    | `20000`                | `OP_BATCHER_THROTTLE_TX_SIZE_UPPER_LIMIT`             |
| `--throttle.unsafe-da-bytes-lower-threshold` | The threshold on unsafe\_da\_bytes beyond which the batcher will start to throttle the block builder. Zero disables throttling.                                                                                             | `3200000`              | `OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_LOWER_THRESHOLD` |
| `--throttle.unsafe-da-bytes-upper-threshold` | Threshold on unsafe\_da\_bytes at which throttling has the maximum intensity (linear and quadratic controllers only)                                                                                                        | `12800000`             | `OP_BATCHER_THROTTLE_UNSAFE_DA_BYTES_UPPER_THRESHOLD` |
| `--txmgr.already-published-custom-errs`      | List of custom RPC error messages that indicate that a transaction has already been published.                                                                                                                              | —                      | `OP_BATCHER_TXMGR_ALREADY_PUBLISHED_CUSTOM_ERRS`      |
| `--txmgr.blob-tip-cap-dynamic`               | Use dynamic blob tip cap from the blob tip oracle instead of static tip cap for blob transactions. Regular transactions still use min-tip-cap/max-tip-cap.                                                                  | `false`                | `OP_BATCHER_TXMGR_BLOB_TIP_CAP_DYNAMIC`               |
| `--txmgr.blob-tip-cap-percentile`            | Percentile of recent blob tx tips to use for suggestion (1-100). Only used when blob-tip-cap-dynamic is enabled.                                                                                                            | `60`                   | `OP_BATCHER_TXMGR_BLOB_TIP_CAP_PERCENTILE`            |
| `--txmgr.blob-tip-cap-range`                 | Number of recent blocks to analyze for blob tip cap distribution. Only used when blob-tip-cap-dynamic is enabled.                                                                                                           | `20`                   | `OP_BATCHER_TXMGR_BLOB_TIP_CAP_RANGE`                 |
| `--txmgr.cell-proof-time`                    | Enables cell proofs in blob transactions for Fusaka (EIP-7742) compatibility from the provided unix timestamp. Should be set to the L1 Fusaka time. May be left blank for Ethereum Mainnet, Sepolia, Holesky, or Hoodi L1s. | `18446744073709551615` | `OP_BATCHER_TXMGR_CELL_PROOF_TIME`                    |
| `--txmgr.fee-limit-threshold`                | The minimum threshold (in GWei) at which fee bumping starts to be capped. Allows arbitrary fee bumps below this threshold.                                                                                                  | `100`                  | `OP_BATCHER_TXMGR_FEE_LIMIT_THRESHOLD`                |
| `--txmgr.max-basefee`                        | Enforces a maximum base fee (in GWei) to assume when determining tx fees, `TxMgr` returns an error when exceeded. Disabled by default.                                                                                      | `0`                    | `OP_BATCHER_TXMGR_MAX_BASEFEE`                        |
| `--txmgr.max-retries`                        | Maximum number of times to resubmit a transaction to L1 on a transient error. Set to 0 to disable retries.                                                                                                                  | `10`                   | `OP_BATCHER_TXMGR_MAX_RETRIES`                        |
| `--txmgr.max-tip-cap`                        | Enforces a maximum tip cap (in GWei) to use when determining tx fees, `TxMgr` returns an error when exceeded. Disabled by default.                                                                                          | `0`                    | `OP_BATCHER_TXMGR_MAX_TIP_CAP`                        |
| `--txmgr.min-basefee`                        | Enforces a minimum base fee (in GWei) to assume when determining tx fees. 1 GWei by default.                                                                                                                                | `1`                    | `OP_BATCHER_TXMGR_MIN_BASEFEE`                        |
| `--txmgr.min-tip-cap`                        | Enforces a minimum tip cap (in GWei) to use when determining tx fees. 1 GWei by default.                                                                                                                                    | `1`                    | `OP_BATCHER_TXMGR_MIN_TIP_CAP`                        |
| `--txmgr.not-in-mempool-timeout`             | Timeout for aborting a tx send if the tx does not make it to the mempool.                                                                                                                                                   | `2m0s`                 | `OP_BATCHER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT`          |
| `--txmgr.rebroadcast-interval`               | Interval at which a published transaction will be rebroadcasted if it has not yet been mined. Should be less than ResubmissionTimeout to have an effect.                                                                    | `12s`                  | `OP_BATCHER_TXMGR_REBROADCAST_INTERVAL`               |
| `--txmgr.receipt-query-interval`             | Frequency to poll for receipts                                                                                                                                                                                              | `12s`                  | `OP_BATCHER_TXMGR_RECEIPT_QUERY_INTERVAL`             |
| `--txmgr.retry-interval`                     | Duration we will wait before resubmitting a transaction to L1 on a transient error. Values \<= 0 will result in retrying immediately. Should be less than ResubmissionTimeout to have an effect.                            | `1s`                   | `OP_BATCHER_TXMGR_RETRY_INTERVAL`                     |
| `--txmgr.send-timeout`                       | Timeout for sending transactions. If 0 it is disabled.                                                                                                                                                                      | `0s`                   | `OP_BATCHER_TXMGR_TX_SEND_TIMEOUT`                    |
| `--wait-node-sync`                           | Indicates if, during startup, the batcher should wait for a recent batcher tx on L1 to finalize (via more block confirmations). This should help avoid duplicate batcher txs.                                               | `false`                | `OP_BATCHER_WAIT_NODE_SYNC`                           |

## Throttling

The `throttle.*` flags control how the batcher limits data availability (DA)
usage when a backlog builds up. When the amount of sequenced data that has not
yet been posted to L1 (the `unsafe_da_bytes` metric) exceeds
`--throttle.unsafe-da-bytes-lower-threshold`, the batcher instructs block
builders — over the `--l2-eth-rpc` endpoints, plus any endpoints listed in
`--throttle.additional-endpoints` — to limit transaction and block DA sizes,
scaling between the configured upper and lower size limits as the backlog
grows.

`--throttle.controller-type` selects how throttling intensity ramps with the
backlog: `step`, `linear`, `quadratic` (the default), or the experimental
`pid` controller, which is tuned with the six `throttle.pid-*` flags.

For the design of the throttling subsystem, including the PID controller, see
[`op-batcher/throttling.md`](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/throttling.md)
in the monorepo.

## Notes on selected flags

### batch-type

Span batches (`--batch-type=1`) aggregate consecutive L2 blocks into a single
batch for better compression. See the
[span batch feature page](/op-stack/features/span-batches) to learn more.

### data-availability-type

<Info>
  Setting this flag to `auto` allows the batcher to automatically switch
  between `calldata` and `blobs` based on the current L1 gas price.
</Info>

### altda.\*

The `altda.*` flags configure Alt-DA mode, a Beta feature of the OP Stack.
While it has received initial review from core contributors, it is still
undergoing testing, and may have bugs or other issues. See the
[Alt-DA mode guide](/chain-operators/guides/features/alt-da-mode-guide) for
setup instructions.


# Challenger configuration reference
Source: https://docs.optimism.io/chain-operators/reference/challenger-configuration

Reference for all op-challenger configuration options, covering CLI flags, environment variables, and default values.

This page catalogues every configuration option for the op-challenger, the
dispute game agent that monitors fault proof games on L1, challenges invalid
claims, and defends valid state transitions.

<ConfigReferencePreamble />

For step-by-step setup instructions — prestates, trace types, wallets, and
monitoring — see the
[challenger configuration guide](/chain-operators/guides/configuration/op-challenger-config-guide);
for how the fault proof system works, see the
[challenger explainer](/op-stack/fault-proofs/challenger).

## Flags

Generated from [`op-challenger/v1.9.3`](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger%2Fv1.9.3)
flag definitions. 88 flags: 4 required, 84 optional.

### Required flags

| Flag           | Description                                                             | Environment variable       |
| -------------- | ----------------------------------------------------------------------- | -------------------------- |
| `--datadir`    | Directory to store data generated as part of responding to games        | `OP_CHALLENGER_DATADIR`    |
| `--l1-beacon`  | Address of L1 Beacon API endpoint to use                                | `OP_CHALLENGER_L1_BEACON`  |
| `--l1-eth-rpc` | HTTP provider URL for L1.                                               | `OP_CHALLENGER_L1_ETH_RPC` |
| `--l2-eth-rpc` | URLs of L2 JSON-RPC endpoints to use (eth and debug namespace required) | `OP_CHALLENGER_L2_ETH_RPC` |

### Optional flags

| Flag                                    | Description                                                                                                                                                                                                                  | Default                   | Environment variable                                |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | --------------------------------------------------- |
| `--additional-bond-claimants`           | List of addresses to claim bonds for, in addition to the configured transaction sender                                                                                                                                       | —                         | `OP_CHALLENGER_ADDITIONAL_BOND_CLAIMANTS`           |
| `--cannon-bin`                          | Path to cannon executable to use when generating trace data (cannon game type only)                                                                                                                                          | —                         | `OP_CHALLENGER_CANNON_BIN`                          |
| `--cannon-depset-config`                | Interop dependency set config file (cannon game type only)                                                                                                                                                                   | —                         | `OP_CHALLENGER_CANNON_DEPSET_CONFIG`                |
| `--cannon-info-freq`                    | Frequency of cannon info log messages to generate in VM steps (cannon game type only)                                                                                                                                        | `10000000`                | `OP_CHALLENGER_CANNON_INFO_FREQ`                    |
| `--cannon-kona-depset-config`           | Interop dependency set config file (cannon-kona game type only)                                                                                                                                                              | —                         | `OP_CHALLENGER_CANNON_KONA_DEPSET_CONFIG`           |
| `--cannon-kona-l1-genesis`              | Path to the L1 genesis file. Only required if the L1 is not mainnet, sepolia, holesky, or hoodi.                                                                                                                             | —                         | `OP_CHALLENGER_CANNON_KONA_L1_GENESIS`              |
| `--cannon-kona-l2-genesis`              | Paths to the op-geth genesis file (cannon-kona game type only)                                                                                                                                                               | —                         | `OP_CHALLENGER_CANNON_KONA_L2_GENESIS`              |
| `--cannon-kona-prestate`                | Path to absolute prestate to use when generating trace data (cannon-kona game type only)                                                                                                                                     | —                         | `OP_CHALLENGER_CANNON_KONA_PRESTATE`                |
| `--cannon-kona-prestates-url`           | Base URL to absolute prestates to use when generating trace data. Prestates in this directory should be name as \<commitment>.bin.gz \<commitment>.json.gz or \<commitment>.json (cannon-kona game type only)                | —                         | `OP_CHALLENGER_CANNON_KONA_PRESTATES_URL`           |
| `--cannon-kona-rollup-config`           | Rollup chain parameters (cannon-kona game type only)                                                                                                                                                                         | —                         | `OP_CHALLENGER_CANNON_KONA_ROLLUP_CONFIG`           |
| `--cannon-kona-server`                  | Path to kona executable to use as pre-image oracle server when generating trace data (cannon-kona game type only)                                                                                                            | —                         | `OP_CHALLENGER_CANNON_KONA_SERVER`                  |
| `--cannon-l1-genesis`                   | Path to the L1 genesis file. Only required if the L1 is not mainnet, sepolia, holesky, or hoodi.                                                                                                                             | —                         | `OP_CHALLENGER_CANNON_L1_GENESIS`                   |
| `--cannon-l2-genesis`                   | Paths to the op-geth genesis file (cannon game type only)                                                                                                                                                                    | —                         | `OP_CHALLENGER_CANNON_L2_GENESIS`                   |
| `--cannon-prestate`                     | Path to absolute prestate to use when generating trace data (cannon game type only)                                                                                                                                          | —                         | `OP_CHALLENGER_CANNON_PRESTATE`                     |
| `--cannon-prestates-url`                | Base URL to absolute prestates to use when generating trace data. Prestates in this directory should be name as \<commitment>.bin.gz \<commitment>.json.gz or \<commitment>.json (cannon game type only)                     | —                         | `OP_CHALLENGER_CANNON_PRESTATES_URL`                |
| `--cannon-rollup-config`                | Rollup chain parameters (cannon game type only)                                                                                                                                                                              | —                         | `OP_CHALLENGER_CANNON_ROLLUP_CONFIG`                |
| `--cannon-server`                       | Path to executable to use as pre-image oracle server when generating trace data (cannon game type only)                                                                                                                      | —                         | `OP_CHALLENGER_CANNON_SERVER`                       |
| `--cannon-snapshot-freq`                | Frequency of cannon snapshots to generate in VM steps (cannon game type only)                                                                                                                                                | `1000000000`              | `OP_CHALLENGER_CANNON_SNAPSHOT_FREQ`                |
| `--depset-config`                       | Interop dependency set config file                                                                                                                                                                                           | —                         | `OP_CHALLENGER_DEPSET_CONFIG`                       |
| `--fee-limit-multiplier`                | The multiplier applied to fee suggestions to put a hard limit on fee increases                                                                                                                                               | `5`                       | `OP_CHALLENGER_TXMGR_FEE_LIMIT_MULTIPLIER`          |
| `--game-allowlist`                      | List of Fault Game contract addresses the challenger is allowed to play. If empty, the challenger will play all games.                                                                                                       | —                         | `OP_CHALLENGER_GAME_ALLOWLIST`                      |
| `--game-factory-address`                | Address of the fault game factory contract.                                                                                                                                                                                  | —                         | `OP_CHALLENGER_GAME_FACTORY_ADDRESS`                |
| `--game-types`                          | The game types to support. Valid options: alphabet, cannon, cannon-kona, permissioned, fast, super-cannon-kona, super-permissioned, zk                                                                                       | `"cannon", "cannon-kona"` | `OP_CHALLENGER_GAME_TYPES`                          |
| `--game-window`                         | The time window which the challenger will look for games to progress and claim bonds. This should include a buffer for the challenger to claim bonds for games outside the maximum game duration.                            | `672h0m0s`                | `OP_CHALLENGER_GAME_WINDOW`                         |
| `--hd-path`                             | The HD path used to derive the sequencer wallet from the mnemonic. The mnemonic flag must also be set.                                                                                                                       | —                         | `OP_CHALLENGER_HD_PATH`                             |
| `--http-poll-interval`                  | Polling interval for latest-block subscription when using an HTTP RPC provider.                                                                                                                                              | `12s`                     | `OP_CHALLENGER_HTTP_POLL_INTERVAL`                  |
| `--l1-genesis`                          | Path to the L1 genesis file. Only required if the L1 is not mainnet, sepolia, holesky, or hoodi.                                                                                                                             | —                         | `OP_CHALLENGER_L1_GENESIS`                          |
| `--l1-rpc-kind`                         | The kind of RPC provider, used to inform optimal transactions receipts fetching, and thus reduce costs. Valid options: alchemy, quicknode, infura, parity, nethermind, debug\_geth, erigon, basic, any, standard             | `standard`                | `OP_CHALLENGER_L1_RPC_KIND`                         |
| `--l2-experimental-eth-rpc`             | L2 Address of L2 JSON-RPC endpoint to use (eth and debug namespace required with execution witness support) (cannon game type only)                                                                                          | —                         | `OP_CHALLENGER_L2_EXPERIMENTAL_ETH_RPC`             |
| `--l2-genesis`                          | Paths to the op-geth genesis file                                                                                                                                                                                            | —                         | `OP_CHALLENGER_L2_GENESIS`                          |
| `--log.color`                           | Color the log output if in terminal mode                                                                                                                                                                                     | `false`                   | `OP_CHALLENGER_LOG_COLOR`                           |
| `--log.format`                          | Format the log output. Supported formats: text, terminal, logfmt, logfmtms, json, jsonms                                                                                                                                     | `text`                    | `OP_CHALLENGER_LOG_FORMAT`                          |
| `--log.level`                           | The lowest log level that will be output                                                                                                                                                                                     | `INFO`                    | `OP_CHALLENGER_LOG_LEVEL`                           |
| `--log.pid`                             | Show pid in the log                                                                                                                                                                                                          | `false`                   | `OP_CHALLENGER_LOG_PID`                             |
| `--max-concurrency`                     | Maximum number of threads to use when progressing games                                                                                                                                                                      | `4`                       | `OP_CHALLENGER_MAX_CONCURRENCY`                     |
| `--max-pending-tx`                      | The maximum number of pending transactions. 0 for no limit.                                                                                                                                                                  | `10`                      | `OP_CHALLENGER_MAX_PENDING_TX`                      |
| `--metrics.addr`                        | Metrics listening address                                                                                                                                                                                                    | `"0.0.0.0"`               | `OP_CHALLENGER_METRICS_ADDR`                        |
| `--metrics.enabled`                     | Enable the metrics server                                                                                                                                                                                                    | `false`                   | `OP_CHALLENGER_METRICS_ENABLED`                     |
| `--metrics.port`                        | Metrics listening port                                                                                                                                                                                                       | `7300`                    | `OP_CHALLENGER_METRICS_PORT`                        |
| `--min-update-interval`                 | Minimum time between scheduling update cycles based on the L1 block time.                                                                                                                                                    | `0s`                      | `OP_CHALLENGER_MIN_UPDATE_INTERVAL`                 |
| `--mnemonic`                            | The mnemonic used to derive the wallets for either the service                                                                                                                                                               | —                         | `OP_CHALLENGER_MNEMONIC`                            |
| `--network`                             | Predefined network selection. Available networks: every chain bundled from the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) at the release; run `op-challenger --help` for the exact list | —                         | `OP_CHALLENGER_NETWORK`                             |
| `--network-timeout`                     | Timeout for all network operations                                                                                                                                                                                           | `10s`                     | `OP_CHALLENGER_NETWORK_TIMEOUT`                     |
| `--num-confirmations`                   | Number of confirmations which we will wait after sending a transaction                                                                                                                                                       | `3`                       | `OP_CHALLENGER_NUM_CONFIRMATIONS`                   |
| `--pprof.addr`                          | pprof listening address                                                                                                                                                                                                      | `"0.0.0.0"`               | `OP_CHALLENGER_PPROF_ADDR`                          |
| `--pprof.enabled`                       | Enable the pprof server                                                                                                                                                                                                      | `false`                   | `OP_CHALLENGER_PPROF_ENABLED`                       |
| `--pprof.path`                          | pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof                                                                                                                                                | —                         | `OP_CHALLENGER_PPROF_PATH`                          |
| `--pprof.port`                          | pprof listening port                                                                                                                                                                                                         | `6060`                    | `OP_CHALLENGER_PPROF_PORT`                          |
| `--pprof.type`                          | pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs                                                                                                                                          | —                         | `OP_CHALLENGER_PPROF_TYPE`                          |
| `--prestates-url`                       | Base URL to absolute prestates to use when generating trace data. Prestates in this directory should be name as \<commitment>.bin.gz \<commitment>.json.gz or \<commitment>.json                                             | —                         | `OP_CHALLENGER_PRESTATES_URL`                       |
| `--private-key`                         | The private key to use with the service. Must not be used with mnemonic.                                                                                                                                                     | —                         | `OP_CHALLENGER_PRIVATE_KEY`                         |
| `--response-delay`                      | Delay before responding to game actions to slow down game progression.                                                                                                                                                       | `0s`                      | `OP_CHALLENGER_RESPONSE_DELAY`                      |
| `--response-delay-after`                | Number of responses after which to start applying the delay (0 = from first response).                                                                                                                                       | `0`                       | `OP_CHALLENGER_RESPONSE_DELAY_AFTER`                |
| `--resubmission-timeout`                | Duration we will wait before resubmitting a transaction to L1                                                                                                                                                                | `24s`                     | `OP_CHALLENGER_RESUBMISSION_TIMEOUT`                |
| `--rollup-config`                       | Rollup chain parameters                                                                                                                                                                                                      | —                         | `OP_CHALLENGER_ROLLUP_CONFIG`                       |
| `--rollup-rpc`                          | HTTP provider URL for the rollup node                                                                                                                                                                                        | —                         | `OP_CHALLENGER_ROLLUP_RPC`                          |
| `--safe-abort-nonce-too-low-count`      | Number of ErrNonceTooLow observations required to give up on a tx at a particular nonce without receiving confirmation                                                                                                       | `3`                       | `OP_CHALLENGER_SAFE_ABORT_NONCE_TOO_LOW_COUNT`      |
| `--selective-claim-resolution`          | Only resolve claims for the configured claimants                                                                                                                                                                             | `false`                   | `OP_CHALLENGER_SELECTIVE_CLAIM_RESOLUTION`          |
| `--signer.address`                      | Address the signer is signing requests for                                                                                                                                                                                   | —                         | `OP_CHALLENGER_SIGNER_ADDRESS`                      |
| `--signer.endpoint`                     | Signer endpoint the client will connect to                                                                                                                                                                                   | —                         | `OP_CHALLENGER_SIGNER_ENDPOINT`                     |
| `--signer.header`                       | Headers to pass to the remote signer. Format `key=value`. Value can contain any character allowed in a HTTP header. When using env vars, split with commas. When using flags one key value pair per flag.                    | —                         | `OP_CHALLENGER_SIGNER_HEADER`                       |
| `--signer.tls.ca`                       | tls ca cert path                                                                                                                                                                                                             | `"tls/ca.crt"`            | `OP_CHALLENGER_SIGNER_TLS_CA`                       |
| `--signer.tls.cert`                     | tls cert path                                                                                                                                                                                                                | `"tls/tls.crt"`           | `OP_CHALLENGER_SIGNER_TLS_CERT`                     |
| `--signer.tls.enabled`                  | Enable or disable TLS client authentication for the signer                                                                                                                                                                   | `true`                    | `OP_CHALLENGER_SIGNER_TLS_ENABLED`                  |
| `--signer.tls.key`                      | tls key                                                                                                                                                                                                                      | `"tls/tls.key"`           | `OP_CHALLENGER_SIGNER_TLS_KEY`                      |
| `--super-cannon-kona-depset-config`     | Interop dependency set config file (super-cannon-kona game type only)                                                                                                                                                        | —                         | `OP_CHALLENGER_SUPER_CANNON_KONA_DEPSET_CONFIG`     |
| `--super-cannon-kona-l1-genesis`        | Path to the L1 genesis file. Only required if the L1 is not mainnet, sepolia, holesky, or hoodi.                                                                                                                             | —                         | `OP_CHALLENGER_SUPER_CANNON_KONA_L1_GENESIS`        |
| `--super-cannon-kona-l2-genesis`        | Paths to the op-geth genesis file (super-cannon-kona game type only)                                                                                                                                                         | —                         | `OP_CHALLENGER_SUPER_CANNON_KONA_L2_GENESIS`        |
| `--super-cannon-kona-prestates-url`     | Base URL to absolute prestates to use when generating trace data. Prestates in this directory should be name as \<commitment>.bin.gz \<commitment>.json.gz or \<commitment>.json (super-cannon-kona game type only)          | —                         | `OP_CHALLENGER_SUPER_CANNON_KONA_PRESTATES_URL`     |
| `--super-cannon-kona-rollup-config`     | Rollup chain parameters (super-cannon-kona game type only)                                                                                                                                                                   | —                         | `OP_CHALLENGER_SUPER_CANNON_KONA_ROLLUP_CONFIG`     |
| `--supernode-rpc`                       | Provider URL for supernode roots                                                                                                                                                                                             | —                         | `OP_CHALLENGER_SUPERNODE_RPC`                       |
| `--txmgr.already-published-custom-errs` | List of custom RPC error messages that indicate that a transaction has already been published.                                                                                                                               | —                         | `OP_CHALLENGER_TXMGR_ALREADY_PUBLISHED_CUSTOM_ERRS` |
| `--txmgr.cell-proof-time`               | Enables cell proofs in blob transactions for Fusaka (EIP-7742) compatibility from the provided unix timestamp. Should be set to the L1 Fusaka time. May be left blank for Ethereum Mainnet, Sepolia, Holesky, or Hoodi L1s.  | `18446744073709551615`    | `OP_CHALLENGER_TXMGR_CELL_PROOF_TIME`               |
| `--txmgr.fee-limit-threshold`           | The minimum threshold (in GWei) at which fee bumping starts to be capped. Allows arbitrary fee bumps below this threshold.                                                                                                   | `100`                     | `OP_CHALLENGER_TXMGR_FEE_LIMIT_THRESHOLD`           |
| `--txmgr.max-basefee`                   | Enforces a maximum base fee (in GWei) to assume when determining tx fees, `TxMgr` returns an error when exceeded. Disabled by default.                                                                                       | `0`                       | `OP_CHALLENGER_TXMGR_MAX_BASEFEE`                   |
| `--txmgr.max-retries`                   | Maximum number of times to resubmit a transaction to L1 on a transient error. Set to 0 to disable retries.                                                                                                                   | `10`                      | `OP_CHALLENGER_TXMGR_MAX_RETRIES`                   |
| `--txmgr.max-tip-cap`                   | Enforces a maximum tip cap (in GWei) to use when determining tx fees, `TxMgr` returns an error when exceeded. Disabled by default.                                                                                           | `0`                       | `OP_CHALLENGER_TXMGR_MAX_TIP_CAP`                   |
| `--txmgr.min-basefee`                   | Enforces a minimum base fee (in GWei) to assume when determining tx fees. 1 GWei by default.                                                                                                                                 | `1`                       | `OP_CHALLENGER_TXMGR_MIN_BASEFEE`                   |
| `--txmgr.min-tip-cap`                   | Enforces a minimum tip cap (in GWei) to use when determining tx fees. 1 GWei by default.                                                                                                                                     | `1`                       | `OP_CHALLENGER_TXMGR_MIN_TIP_CAP`                   |
| `--txmgr.not-in-mempool-timeout`        | Timeout for aborting a tx send if the tx does not make it to the mempool.                                                                                                                                                    | `1m0s`                    | `OP_CHALLENGER_TXMGR_TX_NOT_IN_MEMPOOL_TIMEOUT`     |
| `--txmgr.rebroadcast-interval`          | Interval at which a published transaction will be rebroadcasted if it has not yet been mined. Should be less than ResubmissionTimeout to have an effect.                                                                     | `0s`                      | `OP_CHALLENGER_TXMGR_REBROADCAST_INTERVAL`          |
| `--txmgr.receipt-query-interval`        | Frequency to poll for receipts                                                                                                                                                                                               | `12s`                     | `OP_CHALLENGER_TXMGR_RECEIPT_QUERY_INTERVAL`        |
| `--txmgr.retry-interval`                | Duration we will wait before resubmitting a transaction to L1 on a transient error. Values \<= 0 will result in retrying immediately. Should be less than ResubmissionTimeout to have an effect.                             | `1s`                      | `OP_CHALLENGER_TXMGR_RETRY_INTERVAL`                |
| `--txmgr.send-timeout`                  | Timeout for sending transactions. If 0 it is disabled.                                                                                                                                                                       | `2m0s`                    | `OP_CHALLENGER_TXMGR_TX_SEND_TIMEOUT`               |

## Notes on selected flags

### Conditionally required flags

The required table above lists the flags op-challenger always checks at
startup. Additional flags become required depending on the configuration: the
chain must be identified by `--network` or by `--game-factory-address`, and
each enabled game type requires its trace-execution flags (for example the
`cannon-kona` game type requires the kona server and an absolute prestate via
`--cannon-kona-prestate` or `--cannon-kona-prestates-url`).

### network

When `--network` is set to a chain bundled from the superchain-registry, the
`--game-factory-address` is resolved automatically from the registry and does
not need to be set.

### game-types

Selects which dispute game types the challenger plays. Which type defends
your chain depends on the protocol version it runs; see the
[challenger configuration guide](/chain-operators/guides/configuration/op-challenger-config-guide)
for choosing game types, trace types, and the matching prestates.

### cannon-\* and cannon-kona-\*

The `cannon-*` flags apply only when a cannon-based game type is enabled, and
the `cannon-kona-*` variants only to the `cannon-kona` game type. Each of
these settings has a default variant plus a game-type-specific variant that
overrides it (the `(<game type> game type only)` suffix in the table above).

Note that op-program, the fault proof program the non-kona cannon game types
execute, has
[reached end of support](/notices/archive/op-geth-deprecation), so only the kona
variants are still being maintained.

## Utility subcommands

Beyond running the challenger service, the `op-challenger` binary provides
utility subcommands for inspecting and interacting with dispute games:
`list-games`, `list-claims`, `list-credits`, `create-game`, `move`,
`resolve`, `resolve-claim`, and `run-trace`. Each takes its own flags; run
`op-challenger <subcommand> --help` for details.


# How the DA footprint block limit works
Source: https://docs.optimism.io/chain-operators/reference/da-footprint

Understand the Data Availability (DA) footprint block limit introduced in the Jovian hardfork, how the DA footprint is calculated, and why the default gas scalar is 400.

The **Data Availability (DA) Footprint Block Limit** was introduced in the **[Jovian hardfork](https://docs.optimism.io/notices/upgrade-17)** to limit the total amount of transaction data that can fit into a block based on a scaled estimate of the compressed size (or "data availability footprint") of that data.
This page explains the problem the limit solves, how the DA footprint is calculated, and how the `daFootprintGasScalar` parameter shapes the limit.
To change the scalar on your chain, follow the [DA footprint setup guide](/chain-operators/guides/features/setting-da-footprint).

## Why a DA footprint limit exists

When an OP Stack chain receives more calldata-heavy transactions than can fit into the L1's available blob space, the [batcher can throttle the chain's throughput](https://docs.optimism.io/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling).

However, continuous batcher throttling may cause the base fee to drop to the [minimum base fee](https://docs.optimism.io/chain-operators/guides/features/setting-min-base-fee),
causing unnecessary losses for the chain operator and negative user experiences such as priority fee auctions.
And without throttling, the batcher runs the risk of becoming overwhelmed with chain data to batch to the blob space.
Limiting the amount of (estimated compressed) calldata taken up by transactions in a block using their total DA footprint can reduce the need for batcher throttling and its related issues.

## How the DA footprint is calculated

For all [non-deposit transactions](https://docs.optimism.io/reference/glossary#deposited-transaction) processed by an OP Stack chain, a DA footprint value is recorded alongside the transaction's gas usage.
The DA footprint can be configured via the `daFootprintGasScalar` variable in the `SystemConfig` contract on the L1 chain.
The DA footprint is automatically calculated for every transaction first by calculating a `daUsageEstimate` for that transaction:

```python theme={null}
daUsageEstimate = max(
          minTransactionSize,
          (intercept + fastlzCoef * tx.fastlzSize) // 1e6
      )
```

where the `minTransactionSize`, `intercept`, `fastlzCoef`, and `tx.fastlzSize` are as specified in the [Fjord specs](https://specs.optimism.io/protocol/fjord/exec-engine.html#fees).
Then the `daUsageEstimate` is multiplied by the `daFootprintGasScalar` to get the `daFootprint` for that individual transaction.

```python theme={null}
      daFootprint += daUsageEstimate * daFootprintGasScalar
```

The `daFootprint` for all the transactions in a block are then added together to calculate that block's total `daFootprint`.
With the block's total `daFootprint` calculated:

<Info>
  * The block's total `daFootprint` must stay below its `gasLimit`.
  * The `blobGasUsed` property of each block header is set to that block's `daFootprint`.
  * The base fee update calculation then uses `gasMetered := max(gasUsed, blobGasUsed)` as a replacement for the `gasUsed` variable.
</Info>

From Jovian, transaction receipts also record the transaction's DA Footprint in the receipt's `blobGasUsed` field, as well as the block's `daFootprintGasScalar` in a new field with the same name.

## What the DA footprint gas scalar controls

The *DA footprint gas scalar* scales the *estimated DA usage in bytes* to the gas dimension, and this scaled estimate of the DA usage is what we call the *DA footprint*.
This allows us to limit the estimated DA usage using the block's `gasLimit`: the effective limit of estimated DA usage per block is `gasLimit / daFootprintGasScalar` bytes.
So *increasing* this scalar makes DA usage more gas-heavy, so *decreases* the limit, and vice versa.

This is closely related to how the calldata (floor) cost of `40` gas per non-zero byte limits the total amount of calldata in a block.
A DA footprint gas scalar of `400` effectively limits *incompressible* calldata by a factor of `10` compared to its limit without a DA footprint block limit.
As such, the feature can be seen as an extension of the existing calldata limit.
But instead of repricing the calldata (floor) gas cost, the limit is accounted in parallel to EVM execution gas, and is based on the more relevant FastLZ-based DA usage estimate instead of simply counting zero and non-zero bytes.

## Why the default value is 400

The default scalar of `400` was chosen so that it protects chains in worst-case DA spam scenarios, but has negligible to no impact during normal operation.
Careful [analyses](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md) have been done to estimate the impact on current OP Stack chains and pick the right default.
Only high-throughput chains would occasionally even see a small impact from the resulting DA footprint limit (as slightly faster rising base fees). The DA footprint limit is mostly invisible.
On mid to low-throughput chains, the feature is expected to have no impact under normal usage conditions.
It acts more like an insurance to protect against worst-case *incompressible* DA spam.

<Info>
  A `daFootprintGasScalar` value of `0` in the `SystemConfig` is treated as the default of `400`. To effectively disable the limit, set the scalar to a very low value such as `1`.
</Info>

## Next steps

* To set or change the scalar on your chain, follow [Set the DA Footprint Gas Scalar](/chain-operators/guides/features/setting-da-footprint).
* For the full set of fee-related `SystemConfig` parameters, see the [fee parameters reference](/chain-operators/reference/fee-parameters).

## References

* [DA Footprint Configuration Spec](https://specs.optimism.io/protocol/jovian/system-config.html#da-footprint-configuration)
* [Jovian Upgrade Spec](https://specs.optimism.io/protocol/jovian/overview.html)
* [SystemConfig Contract Spec](https://specs.optimism.io/protocol/system-config.html)
* [Design Doc](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/da-footprint-block-limit.md)


# Fee parameters
Source: https://docs.optimism.io/chain-operators/reference/fee-parameters

Reference for the fee-related SystemConfig parameters on an OP Stack chain — what each parameter controls, its setter and getter, and the OP Mainnet values.

This page catalogues the fee-related parameters a chain operator can set on the `SystemConfig` contract, from the Jovian hardfork onward.
For how fees are calculated and charged, see [transaction fees on OP Mainnet](https://docs.optimism.io/op-stack/transactions/fees#transaction-fees-on-op-mainnet).
For when and how to adjust these parameters, see the [fee tuning guide](/chain-operators/guides/management/transaction-fees-101).

<Info>
  Only the [SystemConfig owner](/op-stack/protocol/privileged-roles) can call the setter methods listed below.
</Info>

## Fee formulas

On an OP Stack chain a transaction's **Total Fee** is made of three main components:

`Total Fee = L2 Fee + L1 Fee + Operator Fee`

| Component    | Formula                                                     |
| ------------ | ----------------------------------------------------------- |
| L2 fee       | `gasUsed * (baseFee + priorityFee)`                         |
| L1 fee       | `estimatedSizeScaled * l1FeeScaled / 1e12` (see below)      |
| Operator fee | `(gasUsed * operatorFeeScalar * 100) + operatorFeeConstant` |

The L1 fee charges for posting L2 data to L1, based on the transaction's estimated compressed (FastLZ) size:

```ts theme={null}
l1FeeScaled =
  baseFeeScalar * 16 * l1BaseFee +
  blobBaseFeeScalar * l1BlobBaseFee

estimatedSizeScaled =
  max(
    minTransactionSize * 1e6,
    intercept + fastlzCoef * fastlzSize
  )

l1Fee = estimatedSizeScaled * l1FeeScaled / 1e12
```

<Info>
  **Pre-Jovian (Isthmus) operator fee formula:** `operatorFee = (gasUsed * operatorFeeScalar / 1e6) + operatorFeeConstant`
</Info>

## Parameters

All parameters live on the `SystemConfig` contract on L1 (see the [`ISystemConfig` interface](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L1/ISystemConfig.sol)).
Each getter below is a `view` method with the same name as the parameter.

| Parameter              | Type     | What it controls                                                                                                                                                                          | Setter                                 | OP Mainnet value       |
| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------- |
| `eip1559Denominator`   | `uint32` | EIP-1559 max-change denominator: appears in the denominator of the per-block base fee delta. Lower = faster base fee response, more volatility.                                           | `setEIP1559Params(uint32,uint32)`      | `250`                  |
| `eip1559Elasticity`    | `uint32` | Elasticity multiplier: sets the gas target relative to the gas limit (`gas_target = gasLimit / elasticity`). Larger elasticity = smaller target, so base fee increases sooner under load. | `setEIP1559Params(uint32,uint32)`      | `2`                    |
| `gasLimit`             | `uint64` | Maximum gas per block. Lower limit = less supply per block, making base fees more sensitive to demand.                                                                                    | `setGasLimit(uint64)`                  | `40,000,000`           |
| `minBaseFee`           | `uint64` | Minimum floor on the base fee, in wei (can be 0). See [setting the minimum base fee](/chain-operators/guides/features/setting-min-base-fee).                                              | `setMinBaseFee(uint64)`                | `0`                    |
| `basefeeScalar`        | `uint32` | Scales the `l1BaseFee` (per-byte) contribution to the L1 data fee.                                                                                                                        | `setGasConfigEcotone(uint32,uint32)`   | `5227`                 |
| `blobbasefeeScalar`    | `uint32` | Scales the `l1BlobBaseFee` (per-blob) contribution to the L1 data fee.                                                                                                                    | `setGasConfigEcotone(uint32,uint32)`   | `1014213`              |
| `operatorFeeScalar`    | `uint32` | Per-gas operator margin. See [setting the operator fee](/chain-operators/guides/features/setting-operator-fee).                                                                           | `setOperatorFeeScalars(uint32,uint64)` | `0`                    |
| `operatorFeeConstant`  | `uint64` | Flat per-transaction operator fee, in wei.                                                                                                                                                | `setOperatorFeeScalars(uint32,uint64)` | `0`                    |
| `daFootprintGasScalar` | `uint16` | Scales estimated DA usage to the gas dimension to limit DA-heavy blocks. See [how the DA footprint block limit works](/chain-operators/reference/da-footprint).                           | `setDAFootprintGasScalar(uint16)`      | `0` (treated as `400`) |

<Warning>
  * Any non-zero operator fee makes the chain configuration [non-standard](/op-stack/protocol/superchain-registry#what-is-a-standard-chain).
  * A `daFootprintGasScalar` of `0` is treated as the default of `400`; set it to `1` to effectively disable the DA footprint limit.
</Warning>

The OP Mainnet values can be verified against the [OP Mainnet SystemConfig contract on Etherscan](https://etherscan.io/address/0x229047fed2591dbec1eF1118d64F7aF3dB9EB290#readProxyContract).

## Fee vault recipients

Fees are gathered in dedicated contract [fee vaults](/op-stack/transactions/fee-vaults). See the [fee vault operations guide](/chain-operators/guides/management/fee-vaults) for how to manage and withdraw from these vaults.

| Fee component | Recipient vault     |
| ------------- | ------------------- |
| `baseFee`     | `BaseFeeVault`      |
| `priorityFee` | `SequencerFeeVault` |
| `l1Fee`       | `L1FeeVault`        |
| `operatorFee` | `OperatorFeeVault`  |

## Reading current values

Each parameter has a getter with the same name on the `SystemConfig` contract:

```bash theme={null}
export L1_RPC=<L1_RPC>
export SYSTEM_CONFIG=<SYSTEM_CONFIG_ADDRESS>

cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "eip1559Denominator()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "eip1559Elasticity()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "gasLimit()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "minBaseFee()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "basefeeScalar()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "blobbasefeeScalar()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "operatorFeeScalar()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "operatorFeeConstant()"
cast call --rpc-url $L1_RPC $SYSTEM_CONFIG "daFootprintGasScalar()"
```

## References

* [Transaction fees on OP Mainnet](https://docs.optimism.io/op-stack/transactions/fees#transaction-fees-on-op-mainnet)
* [Operator fee](https://docs.optimism.io/op-stack/transactions/fees#operator-fee)
* [L1 data fee](https://docs.optimism.io/op-stack/transactions/fees#l1-data-fee)
* [`ISystemConfig` interface](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/interfaces/L1/ISystemConfig.sol)
* [DA footprint](https://docs.optimism.io/notices/archive/upgrade-17#block-header-changes)
* [EIP-1559 parameters](https://docs.optimism.io/op-stack/protocol/differences#eip-1559-parameters)


# OP Contracts Manager
Source: https://docs.optimism.io/chain-operators/reference/opcm

Understand what OP Contracts Manager is, why it exists, and how it deploys and upgrades the L1 contracts for OP Stack chains in a single transaction.

The OP Contracts Manager is a contract that deploys the L1 contracts for an OP Stack chain in a single transaction. It provides a minimal set of user-configurable parameters to ensure that the resulting chain meets the standard configuration requirements. Additionally, as of [Upgrade 13](https://gov.optimism.io/t/upgrade-proposal-13-opcm-and-incident-response-improvements/9739), instances of OPCM can upgrade existing OP Stack chains.

The version deployed is always a governance-approved contract release. The set of governance approved contract releases can be found on the Optimism Monorepo releases page, and is the set of releases named `op-contracts/vX.Y.Z`. It deploys the [Fault Proof System](/op-stack/fault-proofs/explainer), using the [PermissionedDisputeGame](/op-stack/protocol/smart-contracts#proposals-and-fault-proofs).

## Purpose

OPCM simplifies the L1 contract deployments for new OP Stack chains. For each smart contract release there will be a new OPCM instance. It addresses three aspects of deploying the OP Stack's L1 contracts:

1. **Deploy Shared Contracts.** Shared contracts are used between many OP chains, so this occurs only occasionally in production.
2. **Deploy Shared Implementation Contracts.** This occurs once per contracts release in production.
3. **Deploy OP Chain Contracts.** This occurs for every OP chain deployment in production.

Additionally, after the Upgrade 13 network upgrade, OPCM instances will be used to upgrade existing OP Stack chains.

## Learn more

* Checkout the [OPCM specs](https://specs.optimism.io/experimental/op-contracts-manager.html?utm_source=op-docs\&utm_medium=docs)
* Checkout the [OPCM design document](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/op-contracts-manager-arch.md)


# Rollup deployment configuration
Source: https://docs.optimism.io/chain-operators/reference/rollup-deployment-configuration

Reference for the OP Stack rollup deployment configuration values.

This page is the reference for the values in the `DeployConfig` — the flat JSON
configuration that sets the L1 contract parameters and the L2 genesis state when
an OP Stack chain is deployed.

The schema tables below are generated directly from the `DeployConfig` Go
struct tree in the monorepo (`op-chain-ops/genesis`) at a finalized op-deployer
release, so the field list, JSON keys, types, and descriptions cannot silently
fall behind the source. Recommended values and standard-configuration
requirements are policy rather than code, and are maintained by hand in the
[guidance section](#guidance-and-standard-configuration-requirements) below.

<Info>
  **The recommended way to deploy an OP Stack chain is [OP Deployer](/chain-operators/tools/op-deployer/overview).**
  OP Deployer takes a declarative [intent file](/chain-operators/tools/op-deployer/usage/init) (`intent.toml`)
  rather than a hand-written `DeployConfig` JSON, and derives the `DeployConfig`
  documented here from that intent as part of its deployment pipeline. Most chain
  operators set the intent file and never edit a `DeployConfig` directly.

  This page documents the underlying `DeployConfig` surface: the exhaustive set of
  values a deployment ultimately resolves to. Use it to understand what an intent
  setting maps to, to interpret the `DeployConfig` that OP Deployer can emit for an
  applied deployment (via `op-deployer inspect deploy-config`), or as background for
  the lower-level [custom deployments](/chain-operators/tools/op-deployer/usage/custom-deployments)
  OP Deployer also supports.
</Info>

<Info>
  Deploy-config values are largely immutable after a chain is deployed, so this page targets the values you set at genesis.
  The output-oracle proposal fields (the [`l2OutputOracle*` values](#legacy-output-oracle)) describe the legacy `L2OutputOracle` proposal system and apply only to chains still on that system. Chains using [permissionless fault proofs](/op-stack/fault-proofs/explainer) — the standard configuration for new OP Stack chains — set the [fault-proof deployment values](#fault-proofs) instead: `useFaultProofs` together with the `faultGame*`, `preimageOracle*`, `proofMaturityDelaySeconds`, `disputeGameFinalityDelaySeconds`, and `respectedGameType` fields.
</Info>

<Info>
  Standard configuration is the set of requirements for an OP Stack chain to be
  considered a Standard Chain within the OP Stack. These requirements are
  currently a draft, pending governance approval. For more details, please see
  this [governance thread](https://gov.optimism.io/t/season-6-draft-standard-rollup-charter/8135)
  and the actual requirements in the [OP Stack Configurability Specification](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs\&utm_medium=docs).
</Info>

## Configuration values

Generated from the [`DeployConfig` struct](https://github.com/ethereum-optimism/optimism/blob/op-deployer%2Fv0.7.1/op-chain-ops/genesis/config.go)
in `op-chain-ops/genesis` at [`op-deployer/v0.7.1`](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer%2Fv0.7.1):
122 values in 20 groups. The JSON key for each value is its `json:"..."` struct
tag there; descriptions are the Go doc comments. When this page and the source
disagree, the source wins.

### Development accounts

| JSON key          | Type    | Description                                                                                                      |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `fundDevAccounts` | boolean | FundDevAccounts configures whether to fund the dev accounts. This should only be used during devnet deployments. |

### L2 genesis block

| JSON key                      | Type                             | Description |
| ----------------------------- | -------------------------------- | ----------- |
| `l2GenesisBlockNonce`         | number (hex-encoded)             | —           |
| `l2GenesisBlockGasLimit`      | number (hex-encoded)             | —           |
| `l2GenesisBlockDifficulty`    | number (hex-encoded big integer) | —           |
| `l2GenesisBlockMixHash`       | 32-byte hash                     | —           |
| `l2GenesisBlockNumber`        | number (hex-encoded)             | —           |
| `l2GenesisBlockGasUsed`       | number (hex-encoded)             | —           |
| `l2GenesisBlockParentHash`    | 32-byte hash                     | —           |
| `l2GenesisBlockBaseFeePerGas` | number (hex-encoded big integer) | —           |

### Ownership

OwnershipDeployConfig defines the ownership of an L2 chain deployment. This excludes superchain-wide contracts.

| JSON key           | Type    | Description                                                                                                           |
| ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `proxyAdminOwner`  | address | ProxyAdminOwner represents the owner of the ProxyAdmin predeploy on L2.                                               |
| `finalSystemOwner` | address | FinalSystemOwner is the owner of the system on L1. Any L1 contract that is ownable has this account set as its owner. |

### Fee vaults

| JSON key                                   | Type                                                                               | Description                                                                                                                                                                                 |
| ------------------------------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `baseFeeVaultRecipient`                    | address                                                                            | BaseFeeVaultRecipient represents the recipient of fees accumulated in the BaseFeeVault. Can be an account on L1 or L2, depending on the BaseFeeVaultWithdrawalNetwork value.                |
| `l1FeeVaultRecipient`                      | address                                                                            | L1FeeVaultRecipient represents the recipient of fees accumulated in the L1FeeVault. Can be an account on L1 or L2, depending on the L1FeeVaultWithdrawalNetwork value.                      |
| `sequencerFeeVaultRecipient`               | address                                                                            | SequencerFeeVaultRecipient represents the recipient of fees accumulated in the SequencerFeeVault. Can be an account on L1 or L2, depending on the SequencerFeeVaultWithdrawalNetwork value. |
| `operatorFeeVaultRecipient`                | address                                                                            | OperatorFeeVaultRecipient represents the recipient of fees accumulated in the OperatorFeeVault.                                                                                             |
| `baseFeeVaultMinimumWithdrawalAmount`      | number (hex-encoded big integer)                                                   | BaseFeeVaultMinimumWithdrawalAmount represents the minimum withdrawal amount for the BaseFeeVault.                                                                                          |
| `l1FeeVaultMinimumWithdrawalAmount`        | number (hex-encoded big integer)                                                   | L1FeeVaultMinimumWithdrawalAmount represents the minimum withdrawal amount for the L1FeeVault.                                                                                              |
| `sequencerFeeVaultMinimumWithdrawalAmount` | number (hex-encoded big integer)                                                   | SequencerFeeVaultMinimumWithdrawalAmount represents the minimum withdrawal amount for the SequencerFeeVault.                                                                                |
| `operatorFeeVaultMinimumWithdrawalAmount`  | number (hex-encoded big integer)                                                   | OperatorFeeVaultMinimumWithdrawalAmount represents the minimum withdrawal amount for the OperatorFeeVault.                                                                                  |
| `baseFeeVaultWithdrawalNetwork`            | string: "remote" (withdraw to L1) or "local" (withdraw to L2); legacy 0/1 accepted | BaseFeeVaultWithdrawalNetwork represents the withdrawal network for the BaseFeeVault.                                                                                                       |
| `l1FeeVaultWithdrawalNetwork`              | string: "remote" (withdraw to L1) or "local" (withdraw to L2); legacy 0/1 accepted | L1FeeVaultWithdrawalNetwork represents the withdrawal network for the L1FeeVault.                                                                                                           |
| `sequencerFeeVaultWithdrawalNetwork`       | string: "remote" (withdraw to L1) or "local" (withdraw to L2); legacy 0/1 accepted | SequencerFeeVaultWithdrawalNetwork represents the withdrawal network for the SequencerFeeVault.                                                                                             |
| `operatorFeeVaultWithdrawalNetwork`        | string: "remote" (withdraw to L1) or "local" (withdraw to L2); legacy 0/1 accepted | OperatorFeeVaultWithdrawalNetwork represents the withdrawal network for the OperatorFeeVault.                                                                                               |

### Governance token

GovernanceDeployConfig is exclusive to OP-Mainnet and the testing of OP-Mainnet-like chains.

| JSON key                | Type    | Description                                                                                                |
| ----------------------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| `enableGovernance`      | boolean | EnableGovernance configures whether or not include governance token predeploy.                             |
| `governanceTokenSymbol` | string  | GovernanceTokenSymbol represents the ERC20 symbol of the GovernanceToken.                                  |
| `governanceTokenName`   | string  | GovernanceTokenName represents the ERC20 name of the GovernanceToken                                       |
| `governanceTokenOwner`  | address | GovernanceTokenOwner represents the owner of the GovernanceToken. Has the ability to mint and burn tokens. |

### Gas price oracle

GasPriceOracleDeployConfig configures the GasPriceOracle L2 predeploy.

| JSON key                            | Type   | Description                                                                                                                                                                                                                      |
| ----------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `gasPriceOracleOverhead`            | number | GasPriceOracleOverhead represents the initial value of the gas overhead in the GasPriceOracle predeploy. Deprecated: Since Ecotone, this field is superseded by GasPriceOracleBaseFeeScalar and GasPriceOracleBlobBaseFeeScalar. |
| `gasPriceOracleScalar`              | number | GasPriceOracleScalar represents the initial value of the gas scalar in the GasPriceOracle predeploy. Deprecated: Since Ecotone, this field is superseded by GasPriceOracleBaseFeeScalar and GasPriceOracleBlobBaseFeeScalar.     |
| `gasPriceOracleBaseFeeScalar`       | number | GasPriceOracleBaseFeeScalar represents the value of the base fee scalar used for fee calculations.                                                                                                                               |
| `gasPriceOracleBlobBaseFeeScalar`   | number | GasPriceOracleBlobBaseFeeScalar represents the value of the blob base fee scalar used for fee calculations.                                                                                                                      |
| `gasPriceOracleOperatorFeeScalar`   | number | GasPriceOracleOperatorFeeScalar represents the value of the operator fee scalar used for fee calculations.                                                                                                                       |
| `gasPriceOracleOperatorFeeConstant` | number | GasPriceOracleOperatorFeeConstant represents the value of the operator fee constant used for fee calculations.                                                                                                                   |

### Custom gas token

GasTokenDeployConfig configures the optional custom gas token functionality.

| JSON key                     | Type                             | Description                                                                                                       |
| ---------------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `useCustomGasToken`          | boolean                          | UseCustomGasToken is a flag to indicate that a custom gas token should be used                                    |
| `gasPayingTokenName`         | string                           | GasPayingTokenName represents the custom gas token name.                                                          |
| `gasPayingTokenSymbol`       | string                           | GasPayingTokenSymbol represents the custom gas token symbol.                                                      |
| `nativeAssetLiquidityAmount` | number (hex-encoded big integer) | NativeAssetLiquidityAmount represents the amount of liquidity to pre-fund the NativeAssetLiquidity contract with. |
| `liquidityControllerOwner`   | address                          | LiquidityControllerOwner represents the owner of the LiquidityController.                                         |

### Operator addresses

OperatorDeployConfig configures the hot-key addresses for operations such as sequencing and batch-submission.

| JSON key              | Type    | Description                                                                                                                                                               |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `p2pSequencerAddress` | address | P2PSequencerAddress is the address of the key the sequencer uses to sign blocks on the P2P layer.                                                                         |
| `batchSenderAddress`  | address | BatchSenderAddress represents the initial sequencer account that authorizes batches. Transactions sent from this account to the batch inbox address are considered valid. |

### EIP-1559 fee market

EIP1559DeployConfig configures the EIP-1559 parameters of the chain.

| JSON key                   | Type   | Description                                                                                   |
| -------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| `eip1559Elasticity`        | number | EIP1559Elasticity is the elasticity of the EIP1559 fee market.                                |
| `eip1559Denominator`       | number | EIP1559Denominator is the denominator of EIP1559 base fee market.                             |
| `eip1559DenominatorCanyon` | number | EIP1559DenominatorCanyon is the denominator of EIP1559 base fee market when Canyon is active. |

### Network upgrade (hardfork) activations

UpgradeScheduleDeployConfig configures when network upgrades activate.

| JSON key                                | Type                               | Description                                                                                                                                                                                                  |
| --------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `l2GenesisRegolithTimeOffset`           | number (hex-encoded), nullable     | L2GenesisRegolithTimeOffset is the number of seconds after genesis block that Regolith hard fork activates. Set it to 0 to activate at genesis. Nil to disable Regolith.                                     |
| `l2GenesisCanyonTimeOffset`             | number (hex-encoded), nullable     | L2GenesisCanyonTimeOffset is the number of seconds after genesis block that Canyon hard fork activates. Set it to 0 to activate at genesis. Nil to disable Canyon.                                           |
| `l2GenesisDeltaTimeOffset`              | number (hex-encoded), nullable     | L2GenesisDeltaTimeOffset is the number of seconds after genesis block that Delta hard fork activates. Set it to 0 to activate at genesis. Nil to disable Delta.                                              |
| `l2GenesisEcotoneTimeOffset`            | number (hex-encoded), nullable     | L2GenesisEcotoneTimeOffset is the number of seconds after genesis block that Ecotone hard fork activates. Set it to 0 to activate at genesis. Nil to disable Ecotone.                                        |
| `l2GenesisFjordTimeOffset`              | number (hex-encoded), nullable     | L2GenesisFjordTimeOffset is the number of seconds after genesis block that Fjord hard fork activates. Set it to 0 to activate at genesis. Nil to disable Fjord.                                              |
| `l2GenesisGraniteTimeOffset`            | number (hex-encoded), nullable     | L2GenesisGraniteTimeOffset is the number of seconds after genesis block that Granite hard fork activates. Set it to 0 to activate at genesis. Nil to disable Granite.                                        |
| `l2GenesisHoloceneTimeOffset`           | number (hex-encoded), nullable     | L2GenesisHoloceneTimeOffset is the number of seconds after genesis block that the Holocene hard fork activates. Set it to 0 to activate at genesis. Nil to disable Holocene.                                 |
| `l2GenesisIsthmusTimeOffset`            | number (hex-encoded), nullable     | L2GenesisIsthmusTimeOffset is the number of seconds after genesis block that the Isthmus hard fork activates. Set it to 0 to activate at genesis. Nil to disable Isthmus.                                    |
| `l2GenesisJovianTimeOffset`             | number (hex-encoded), nullable     | L2GenesisJovianTimeOffset is the number of seconds after genesis block that the Jovian hard fork activates. Set it to 0 to activate at genesis. Nil to disable Jovian.                                       |
| `l2GenesisKarstTimeOffset`              | number (hex-encoded), nullable     | L2GenesisKarstTimeOffset is the number of seconds after genesis block that the Karst hard fork activates. Set it to 0 to activate at genesis. Nil to disable Karst.                                          |
| `l2GenesisInteropTimeOffset`            | number (hex-encoded), nullable     | L2GenesisInteropTimeOffset is the number of seconds after genesis block that the Interop hard fork activates. Set it to 0 to activate at genesis. Nil to disable Interop.                                    |
| `l2GenesisPectraBlobScheduleTimeOffset` | number (hex-encoded), nullable     | L2GenesisPectraBlobScheduleTimeOffset is the number of seconds after genesis block that the PectraBlobSchedule fix activates. Set it to 0 to activate at genesis. Nil to disable the PectraBlobSchedule fix. |
| `l1CancunTimeOffset`                    | number (hex-encoded), nullable     | When Cancun activates. Relative to L1 genesis.                                                                                                                                                               |
| `l1PragueTimeOffset`                    | number (hex-encoded), nullable     | When Prague activates. Relative to L1 genesis.                                                                                                                                                               |
| `l1OsakaTimeOffset`                     | number (hex-encoded), nullable     | When Osaka activates. Relative to L1 genesis.                                                                                                                                                                |
| `l1BPO1TimeOffset`                      | number (hex-encoded), nullable     | When BPO1 activates. Relative to L1 genesis.                                                                                                                                                                 |
| `l1BPO2TimeOffset`                      | number (hex-encoded), nullable     | When BPO2 activates. Relative to L1 genesis.                                                                                                                                                                 |
| `l1BPO3TimeOffset`                      | number (hex-encoded), nullable     | When BPO3 activates. Relative to L1 genesis.                                                                                                                                                                 |
| `l1BPO4TimeOffset`                      | number (hex-encoded), nullable     | When BPO4 activates. Relative to L1 genesis.                                                                                                                                                                 |
| `l1BlobScheduleConfig`                  | object (go-ethereum blob schedule) | Blob schedule config.                                                                                                                                                                                        |

### Core protocol parameters

L2CoreDeployConfig configures the core protocol parameters of the chain.

| JSON key                    | Type    | Description                                                                                                                                                                                                                                                  |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `l1ChainID`                 | number  | L1ChainID is the chain ID of the L1 chain.                                                                                                                                                                                                                   |
| `l2ChainID`                 | number  | L2ChainID is the chain ID of the L2 chain.                                                                                                                                                                                                                   |
| `l2BlockTime`               | number  | L2BlockTime is the number of seconds between each L2 block.                                                                                                                                                                                                  |
| `finalizationPeriodSeconds` | number  | FinalizationPeriodSeconds represents the number of seconds before an output is considered finalized. This impacts the amount of time that withdrawals take to finalize and is generally set to 1 week.                                                       |
| `maxSequencerDrift`         | number  | MaxSequencerDrift is the number of seconds after the L1 timestamp of the end of the sequencing window that batches must be included, otherwise L2 blocks including deposits are force included.                                                              |
| `sequencerWindowSize`       | number  | SequencerWindowSize is the number of L1 blocks per sequencing window.                                                                                                                                                                                        |
| `channelTimeout`            | number  | ChannelTimeoutBedrock is the number of L1 blocks that a frame stays valid when included in L1.                                                                                                                                                               |
| `batchInboxAddress`         | address | BatchInboxAddress is the L1 account that batches are sent to.                                                                                                                                                                                                |
| `systemConfigStartBlock`    | number  | SystemConfigStartBlock represents the block at which the op-node should start syncing from. It is an override to set this value on legacy networks where it is not set by default. It can be removed once all networks have this value set in their storage. |

### Fee market limits

| JSON key               | Type   | Description                                                                       |
| ---------------------- | ------ | --------------------------------------------------------------------------------- |
| `minBaseFee`           | number | MinBaseFee is the minimum base applied to each block.                             |
| `daFootprintGasScalar` | number | DAFootprintGasScalar is the scalar used to compute the DAFootprint of each block. |

### Alt-DA mode

AltDADeployConfig configures optional AltDA functionality.

| JSON key                     | Type    | Description                                                                                                                              |
| ---------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `useAltDA`                   | boolean | UseAltDA is a flag that indicates if the system is using op-alt-da                                                                       |
| `daCommitmentType`           | string  | DACommitmentType specifies the allowed commitment                                                                                        |
| `daChallengeWindow`          | number  | DAChallengeWindow represents the block interval during which the availability of a data commitment can be challenged.                    |
| `daResolveWindow`            | number  | DAResolveWindow represents the block interval during which a data availability challenge can be resolved.                                |
| `daBondSize`                 | number  | DABondSize represents the required bond size to initiate a data availability challenge.                                                  |
| `daResolverRefundPercentage` | number  | DAResolverRefundPercentage represents the percentage of the resolving cost to be refunded to the resolver such as 100 means 100% refund. |

### Development L1 genesis

DevL1DeployConfig is used to configure a L1 chain for development/testing purposes. A production L2 deployment does not utilize this configuration, except of a L1BlockTime sanity-check (set this to 12 for L1 Ethereum).

| JSON key                      | Type                             | Description |
| ----------------------------- | -------------------------------- | ----------- |
| `l1BlockTime`                 | number                           | —           |
| `l1GenesisBlockTimestamp`     | number (hex-encoded)             | —           |
| `l1GenesisBlockNonce`         | number (hex-encoded)             | —           |
| `l1GenesisBlockGasLimit`      | number (hex-encoded)             | —           |
| `l1GenesisBlockDifficulty`    | number (hex-encoded big integer) | —           |
| `l1GenesisBlockMixHash`       | 32-byte hash                     | —           |
| `l1GenesisBlockCoinbase`      | address                          | —           |
| `l1GenesisBlockNumber`        | number (hex-encoded)             | —           |
| `l1GenesisBlockGasUsed`       | number (hex-encoded)             | —           |
| `l1GenesisBlockParentHash`    | 32-byte hash                     | —           |
| `l1GenesisBlockBaseFeePerGas` | number (hex-encoded big integer) | —           |
| `l1GenesisBlockExcessBlobGas` | number (hex-encoded), nullable   | —           |
| `l1GenesisBlockblobGasUsed`   | number (hex-encoded), nullable   | —           |

### L1 starting block

| JSON key             | Type                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `l1StartingBlockTag` | L1 block number, tag, or hash | L1StartingBlockTag anchors the L2 at an L1 block. The timestamp of the block referenced by l1StartingBlockTag is used in the L2 genesis block, rollup-config, and L1 output-oracle contract. The Output oracle deploy script may use it if the L2 starting timestamp is nil, assuming the L2 genesis is set up with this. The L2 genesis timestamp does not affect the initial L2 account state: the storage of the L1Block contract at genesis is zeroed, since the adoption of the L2-genesis allocs-generation through solidity script. |

### Superchain configuration

SuperchainL1DeployConfig configures parameters of the superchain-wide deployed contracts to L1. This deployment is global, and can be reused between L2s that target the same superchain.

| JSON key                   | Type    | Description                                                                                                             |
| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------- |
| `superchainConfigGuardian` | address | SuperchainConfigGuardian represents the GUARDIAN account in the SuperchainConfig. Has the ability to pause withdrawals. |

### Legacy output oracle

OutputOracleDeployConfig configures the legacy OutputOracle deployment to L1. This is obsoleted with Fault Proofs. See FaultProofDeployConfig.

| JSON key                            | Type    | Description                                                                                                                                                                                                                      |
| ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `l2OutputOracleSubmissionInterval`  | number  | L2OutputOracleSubmissionInterval is the number of L2 blocks between outputs that are submitted to the L2OutputOracle contract located on L1.                                                                                     |
| `l2OutputOracleStartingTimestamp`   | number  | L2OutputOracleStartingTimestamp is the starting timestamp for the L2OutputOracle. MUST be the same as the timestamp of the L2OO start block.                                                                                     |
| `l2OutputOracleStartingBlockNumber` | number  | L2OutputOracleStartingBlockNumber is the starting block number for the L2OutputOracle. Must be greater than or equal to the first Bedrock block. The first L2 output will correspond to this value plus the submission interval. |
| `l2OutputOracleProposer`            | address | L2OutputOracleProposer is the address of the account that proposes L2 outputs.                                                                                                                                                   |
| `l2OutputOracleChallenger`          | address | L2OutputOracleChallenger is the address of the account that challenges L2 outputs.                                                                                                                                               |

### Fault proofs

FaultProofDeployConfig configures the fault-proof deployment to L1.

| JSON key                          | Type         | Description                                                                                                                                                                                                                                                                                      |
| --------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `useFaultProofs`                  | boolean      | UseFaultProofs is a flag that indicates if the system is using fault proofs instead of the older output oracle mechanism.                                                                                                                                                                        |
| `faultGameAbsolutePrestate`       | 32-byte hash | FaultGameAbsolutePrestate is the absolute prestate of Cannon. This is computed by generating a proof from the 0th -> 1st instruction and grabbing the prestate from the output JSON. All honest challengers should agree on the setup state of the program.                                      |
| `faultGameMaxDepth`               | number       | FaultGameMaxDepth is the maximum depth of the position tree within the fault dispute game. `2^{FaultGameMaxDepth}` is how many instructions the execution trace bisection game supports. Ideally, this should be conservatively set so that there is always enough room for a full Cannon trace. |
| `faultGameClockExtension`         | number       | FaultGameClockExtension is the amount of time that the dispute game will set the potential grandchild claim's, clock to, if the remaining time is less than this value at the time of a claim's creation.                                                                                        |
| `faultGameMaxClockDuration`       | number       | FaultGameMaxClockDuration is the maximum amount of time that may accumulate on a team's chess clock before they may no longer respond.                                                                                                                                                           |
| `faultGameGenesisBlock`           | number       | FaultGameGenesisBlock is the block number for genesis.                                                                                                                                                                                                                                           |
| `faultGameGenesisOutputRoot`      | 32-byte hash | FaultGameGenesisOutputRoot is the output root for the genesis block.                                                                                                                                                                                                                             |
| `faultGameSplitDepth`             | number       | FaultGameSplitDepth is the depth at which the fault dispute game splits from output roots to execution trace claims.                                                                                                                                                                             |
| `faultGameWithdrawalDelay`        | number       | FaultGameWithdrawalDelay is the number of seconds that users must wait before withdrawing ETH from a fault game.                                                                                                                                                                                 |
| `preimageOracleMinProposalSize`   | number       | PreimageOracleMinProposalSize is the minimum number of bytes that a large preimage oracle proposal can be.                                                                                                                                                                                       |
| `preimageOracleChallengePeriod`   | number       | PreimageOracleChallengePeriod is the number of seconds that challengers have to challenge a large preimage proposal.                                                                                                                                                                             |
| `proofMaturityDelaySeconds`       | number       | ProofMaturityDelaySeconds is the number of seconds that a proof must be mature before it can be used to finalize a withdrawal.                                                                                                                                                                   |
| `disputeGameFinalityDelaySeconds` | number       | DisputeGameFinalityDelaySeconds is an additional number of seconds a dispute game must wait before it can be used to finalize a withdrawal.                                                                                                                                                      |
| `respectedGameType`               | number       | RespectedGameType is the dispute game type that the OptimismPortal contract will respect for finalizing withdrawals.                                                                                                                                                                             |

### L1 dependency addresses

L1DependenciesConfig is the set of addresses that affect the L2 genesis construction, and is dependent on prior deployment of contracts to L1. This is generally not configured in deploy-config JSON, but rather merged in through a L1 deployments JSON file.

| JSON key                      | Type    | Description                                                                                                                                       |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `l1StandardBridgeProxy`       | address | L1StandardBridgeProxy represents the address of the L1StandardBridgeProxy on L1 and is used as part of building the L2 genesis state.             |
| `l1CrossDomainMessengerProxy` | address | L1CrossDomainMessengerProxy represents the address of the L1CrossDomainMessengerProxy on L1 and is used as part of building the L2 genesis state. |
| `l1ERC721BridgeProxy`         | address | L1ERC721BridgeProxy represents the address of the L1ERC721Bridge on L1 and is used as part of building the L2 genesis state.                      |
| `systemConfigProxy`           | address | SystemConfigProxy represents the address of the SystemConfigProxy on L1 and is used as part of the derivation pipeline.                           |
| `optimismPortalProxy`         | address | OptimismPortalProxy represents the address of the OptimismPortalProxy on L1 and is used as part of the derivation pipeline.                       |
| `daChallengeProxy`            | address | DAChallengeProxy represents the L1 address of the DataAvailabilityChallenge contract.                                                             |

### Legacy fields

LegacyDeployConfig retains legacy DeployConfig attributes. The genesis generation may log warnings, do a best-effort support attempt, or ignore these attributes completely.

| JSON key                      | Type   | Description                                                                                                                                    |
| ----------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `deploymentWaitConfirmations` | number | DeploymentWaitConfirmations is the number of confirmations to wait during deployment. This is DEPRECATED and should be removed in a future PR. |
| `channelTimeoutGranite`       | number | —                                                                                                                                              |

## Guidance and standard-configuration requirements

The tables above are the exhaustive schema. This section carries the
hand-maintained guidance for the values chain operators most often need to
reason about: recommended values, validation constraints, and the
standard-configuration requirements from the draft
[Standard Rollup Charter](https://gov.optimism.io/t/season-6-draft-standard-rollup-charter/8135).

### Hardfork activation guidance

* The standard configuration requires network upgrades (hardforks) to be
  activated. New chains set each `l2Genesis<Fork>TimeOffset` to `"0x0"` so
  every governance-approved upgrade is active at genesis; a nil (omitted)
  offset disables the fork.
* Later forks cannot activate before earlier ones, and two forks cannot
  activate at the same post-genesis time.
* The interoperability hardfork activation offset is a non-standard feature:
  interoperability is still [experimental](https://specs.optimism.io/interop/overview.html?utm_source=op-docs\&utm_medium=docs).

### Roles and ownership requirements

* `finalSystemOwner`: must not be `address(0)`. It is recommended to have a
  single admin address to retain a common security model. Standard
  configuration: must be the Chain Governor or Servicer; however, the L1
  ProxyAdmin owner must be held by the Optimism Security Council. At the
  moment, the L1 ProxyAdmin owner is transferred from the Chain Governor or
  Servicer to [0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A](https://etherscan.io/address/0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A).
* `proxyAdminOwner`: owns the `ProxyAdmin` predeploy on L2, which owns all of
  the Proxy contracts for every predeployed contract in the range
  `0x42...0000` to `0x42...2048`, making predeploys upgradeable. Must not be
  `address(0)`; a single admin address is recommended.
* `superchainConfigGuardian`: standard configuration requires
  [0x09f7150D8c019BeF34450d6920f6B3608ceFdAf2](https://etherscan.io/address/0x09f7150D8c019BeF34450d6920f6B3608ceFdAf2),
  a 1/1 Safe owned by the Security Council Safe, with the
  [Deputy Pause Module](https://specs.optimism.io/protocol/deputy-pause-module.html?utm_source=op-docs\&utm_medium=docs)
  enabled to allow the Optimism Foundation to act as Pause Deputy.
* `p2pSequencerAddress` and `batchSenderAddress`: hot-key addresses you
  control — the sequencer's block-signing key and the batcher account whose
  transactions to the batch inbox are considered valid. Neither may be
  `address(0)`. `batchSenderAddress` can be updated later via the
  `SystemConfig` contract on L1. No standard requirement.
* The [L1 dependency addresses](#l1-dependency-addresses)
  (`l1StandardBridgeProxy`, `l1CrossDomainMessengerProxy`,
  `l1ERC721BridgeProxy`, `systemConfigProxy`, `optimismPortalProxy`): filled
  in from the L1 deployment rather than hand-configured; none of them may be
  `address(0)`. Standard
  configuration requires the implementation contracts to be the most
  up-to-date, governance-approved version of the OP Stack codebase — and, if
  the chain has been upgraded in the past, that the previous versions were a
  standard release of the codebase.

### Sequencing and batching guidance

* `l2BlockTime`: must be nonzero, a whole number, and less than the L1 block
  time (12 seconds on Ethereum mainnet and Sepolia). Standard configuration:
  1 or 2 seconds.
* `maxSequencerDrift`: must be nonzero. 1800 (30 minutes) is the constant
  that takes effect with the
  [Fjord activation](/op-stack/protocol/network-upgrades#activations).
* `sequencerWindowSize`: must be nonzero. Standard configuration: 3\_600 base
  layer blocks (12 hours for an L2 on Ethereum, assuming 12 second L1
  blocktime). This is an important value for constraining the sequencer's
  ability to re-order transactions; higher values would pose a risk to user
  protections.
* `channelTimeout`: the default of 50 was introduced in the
  [Granite network upgrade](/op-stack/protocol/network-upgrades#activations).
* `batchInboxAddress`: standard configuration convention is
  `versionByte || keccak256(bytes32(chainId))[:19]`, where `||` denotes
  concatenation, `versionByte` is `0x00`, and `chainId` is a `uint256`. This
  covers the full range of chain IDs, up to the full `uint256` size:

  ```solidity theme={null}
  bytes32 hash = keccak256(abi.encodePacked(bytes32(uint256(chainId))));
  // take the first 19 bytes of the hash, then prepend a version byte of 0x00
  // batchInboxAddress = 0x00{hash[:19]}
  ```
* `systemConfigStartBlock`: standard configuration: the block where the
  `SystemConfig` was initialized.
* `l1StartingBlockTag`: it is generally recommended to use a finalized L1
  block to avoid issues with reorgs.

### Chain ID requirements

* `l1ChainID`: must be nonzero. 1 for Ethereum mainnet, 11155111 for the
  Sepolia test network; see [chainlist](https://chainlist.org/?testnets=true)
  for other networks. Standard configuration: 1 (Ethereum).
* `l2ChainID`: must be nonzero and, for security reasons, unique. Standard
  configuration: a Foundation-approved, globally unique value. Chains should
  add their chain IDs to
  [ethereum-lists/chains](https://github.com/ethereum-lists/chains).

### Gas and fee guidance

* `l2GenesisBlockGasLimit`: must be nonzero and greater than
  `MaxResourceLimit + SystemTxMaxGas` (the gas a deposit plus the system
  transaction can use). Standard configuration: no higher than 200\_000\_000
  gas; chain operators are driven to maintain a stable and reliable chain,
  so careful deliberation is necessary when considering a change.
* `l2GenesisBlockBaseFeePerGas`: cannot be nil.
* `gasPriceOracleBaseFeeScalar` and `gasPriceOracleBlobBaseFeeScalar`: should
  not be 0. Standard configuration: set such that the fee margin is between
  0 and 50%. See [transaction fees](/op-stack/transactions/fees) for how the
  scalars enter the fee calculation.
* `eip1559Elasticity` and `eip1559Denominator`: must be nonzero.
  `eip1559DenominatorCanyon` must be nonzero if Canyon is activated; 250 is
  the recommended value.
* `minBaseFee`: an absolute minimum base fee in wei, to help shorten the
  length of priority fee auctions; 0 disables it (the default). 100000 wei
  is the recommended value; setting the minimum too high may make
  transactions harder to get included for users. Standard configuration:
  must not be set higher than 10000000000 wei. See the
  [minimum base fee specs](https://specs.optimism.io/protocol/jovian/exec-engine.html#minimum-base-fee)
  for more detail.
* `daFootprintGasScalar`: multiplied by the DA usage estimate to limit the
  total estimated compressed transaction data that can fit into a block; 400
  is the recommended value. As of Jovian, the base fee update calculation
  uses `gasMetered := max(gasUsed, blobGasUsed)` in place of `gasUsed`, so
  blocks with high DA usage may cause the base fee to increase in subsequent
  blocks. See the
  [DA footprint block limit specs](https://specs.optimism.io/protocol/jovian/exec-engine.html#da-footprint-block-limit)
  for more detail.

### Fee vault guidance

* The `*FeeVaultRecipient` addresses must not be `address(0)`; a single
  admin address is recommended to retain a common security model.
* The `*FeeVaultWithdrawalNetwork` values choose where each vault withdraws:
  `"remote"` sends fees to the recipient address on L1, `"local"` on L2.
  Withdrawals to L1 are more expensive. Note that when the config is
  re-emitted (for example by `op-deployer inspect deploy-config`), these
  values marshal in the legacy numeric form: `0` for `"remote"`, `1` for
  `"local"`.
* The `*FeeVaultMinimumWithdrawalAmount` values exist because withdrawals to
  L1 are expensive: the minimum prevents the overhead cost of continuous
  tiny withdrawals that would cost more to execute than they return.

### Withdrawal finality guidance

* `finalizationPeriodSeconds`: must be nonzero. 12 seconds is recommended on
  test networks, seven days on production ones. Standard configuration: 7
  days — a high-security, excessively safe upper bound that leaves enough
  time to consider social-layer solutions to a hack if necessary, and allows
  other network participants to challenge the integrity of the corresponding
  output root.

### Legacy output-oracle guidance

These apply only to chains still on the legacy `L2OutputOracle` proposal
system; new chains use [fault proofs](#fault-proofs) instead.

* `l2OutputOracleSubmissionInterval`: must be nonzero; 120 blocks (4
  minutes) is suggested.
* `l2OutputOracleStartingBlockNumber`: should be 0 for new chains; may be
  non-zero for networks upgraded from a legacy system (like OP Mainnet).
* `l2OutputOracleStartingTimestamp`: MUST be the timestamp corresponding to
  the block defined by `l1StartingBlockTag`.
* `l2OutputOracleProposer`: must not be `address(0)`. No standard
  requirement. This role is only active when the `OptimismPortal` respected
  game type is `PERMISSIONED_CANNON`. The L1 ProxyAdmin sets the
  implementation of the `PERMISSIONED_CANNON` game type, and thus determines
  the proposer configuration of the permissioned dispute game.
* `l2OutputOracleChallenger`: must not be `address(0)`; a single admin
  address is recommended to retain a common security model.

### Fault-proof value guidance

You should understand the implications of running a fault-proof chain before
setting `useFaultProofs`; see the
[fault proofs explainer](/op-stack/fault-proofs/explainer).
`proofMaturityDelaySeconds` and `disputeGameFinalityDelaySeconds` should not
be 0. `faultGameMaxDepth` should be conservatively set so that there is always
enough room for a full Cannon trace.

### Alt-DA guidance

Alt-DA mode is a non-standard feature. It enables integration of Data
Availability layers into the OP Stack regardless of their commitment type; see
[Alt-DA mode](/op-stack/features/experimental/alt-da-mode).

* `daCommitmentType`: must be either `KeccakCommitment` or
  `GenericCommitment` (recommended); `KeccakCommitment` will be deprecated.
* `daChallengeWindow` and `daResolveWindow`: must be nonzero when using
  Alt-DA mode with Keccak commitments.
* `daChallengeProxy`: must not be `address(0)` when using Alt-DA mode with
  Keccak commitments, and must be `address(0)` with generic commitments.

### Governance and development settings

* `enableGovernance`: false is recommended; the governance token predeploy
  is exclusive to OP Mainnet and the testing of OP-Mainnet-like chains.
* `fundDevAccounts` and the [development L1 genesis](#development-l1-genesis)
  values are for devnet deployments only; a production L2 deployment does
  not use them, except for the `l1BlockTime` sanity check (12 for Ethereum).


# Chain monitoring options
Source: https://docs.optimism.io/chain-operators/tools/chain-monitoring

Learn about onchain and offchain monitoring options for your OP Stack chain.

This explainer covers the basics of onchain and offchain monitoring options for your OP Stack chain. Onchain monitoring services allow chain operators to monitor the overall system and onchain events.
Offchain monitoring lets chain operators to monitor the operation and behavior of nodes and other offchain components.

## Onchain monitoring services

Onchain monitoring services provide insights into the overall system, helping chain operators track and monitor on-chain events. Some examples of onchain monitoring services include `monitorism` and `dispute-mon`.

### `monitorism`

Monitorism is a tooling suite that supports monitoring and active remediation actions for the OP Stack chain. Monitorism uses monitors as passive security providing automated monitoring for the OP Stack. They are used to monitor the OP stack and alert on specific events that could be a sign of a security incident.

Currently, the list of monitors includes:

Security integrity monitors: These are monitors necessary for making sure Bridges between L2 and L1 are safe and work as expected. These monitors are divided in two subgroups:

* Pre-Faultproof Chain Monitors:
  * Fault Monitor: checks for changes in output roots posted to the L2OutputOracle contract. When a change is detected, it reconstructs the output root from a trusted L2 source and looks for a match.
  * Withdrawals Monitor: checks for new withdrawals that have been proven to the OptimismPortal contract. Each withdrawal is checked against the `L2ToL1MessagePasser` contract.
* Faultproof chain monitors:
  * Faultproof Withdrawal: The Faultproof Withdrawal component monitors `ProvenWithdrawals` events on the `OptimismPortal` contract and performs checks to detect any violations of invariant conditions on the chain. If a violation is detected, the issue is logged, and a Prometheus metric is set for the event. This component is designed to work exclusively with chains that are already utilizing the Fault Proofs system. This is a new version of the deprecated `chain-mon`,  `faultproof-wd-mon`. For detailed information on how the component works and the algorithms used, please refer to the component README.

Security monitors: Those tools monitor other aspects of several contracts used in optimism:

* Global Events Monitor: made for taking YAML rules as configuration and monitoring the events that are emitted on the chain.
* Liveness Expiration Monitor: monitors the liveness expiration on Safes.
* Balances Monitor: emits a metric reporting the balances for the configured accounts.
* Multisig Monitor: The multisig monitor reports the paused status of the OptimismPortal contract. If set, reports the latest nonce of the configured Safe address and the latest presigned nonce stored in One Password.. The latest presigned nonce is identified by looking for items in the configured vault that follow a `ready-<nonce>.json` name. The highest nonce of this item name format is reported.
* Drippie Monitor: tracks the execution and executability of drips within a Drippie contract.
* Secrets Monitor: takes a Drippie contract as a parameter and monitors for any drips within that contract that use the `CheckSecrets` dripcheck contract. `CheckSecrets` is a dripcheck that allows a drip to begin once a specific secret has been revealed (after a delay period) and cancels the drip if a second secret is revealed. Monitoring these secrets is important, as their revelation may indicate that the secret storage platform has been compromised and someone is attempting to exfiltrate the ETH controlled by the drip.

For more information on these monitors and how to use them, [check out the repo](https://github.com/ethereum-optimism/monitorism?tab=readme-ov-file#monitorism).

### `dispute-mon`

Chain operators should consider running `op-dispute-mon`. It's an essential security monitoring service that tracks game statuses, providing visibility over the last 28 days.

`dispute-mon` is set up and built the same way as `op-challenger`. This means that you can run it the same way (run `make op-dispute-mon` in the directory).

A basic configuration option would look like this:

```
OP_DISPUTE_MON_LOG_FORMAT=logfmt
OP_DISPUTE_MON_METRICS_ENABLED=true
OP_DISPUTE_MON_METRICS_ADDR=0.0.0.0
OP_DISPUTE_MON_METRICS_PORT=7300

OP_DISPUTE_MON_L1_ETH_RPC=..
OP_DISPUTE_MON_ROLLUP_RPC=..
OP_DISPUTE_MON_GAME_FACTORY_ADDRESS=..

OP_DISPUTE_MON_HONEST_ACTORS=..
```

`OP_DISPUTE_MON_HONEST_ACTORS` is a CSV (no spaces) list of addresses that are used for the honest `op-challenger` instances.

Additional flags:

* `OP_DISPUTE_MON_GAME_WINDOW`: This is the window of time to report on games. It should leave a buffer beyond the max game duration for bond claiming. If Fault Proof game parameters are not changes (e.g. MAX\_CLOCK\_DURATION), it is recommended to leave this as the default.
* `OP_DISPUTE_MON_MONITOR_INTERVAL`: The interval at which to check for new games. Defaults to 30 seconds currently.
* `OP_DISPUTE_MON_MAX_CONCURRENCY`: The max thread count. Defaults to 5 currently.

You can find more info on `op-dispute-mon` on [the repo](https://github.com/ethereum-optimism/optimism/tree/develop/op-dispute-mon).

## Offchain component monitoring

Offchain monitoring allows chain operators to monitor the operation and behavior of nodes and other offchain components. Some of the more common components that you'll likely want to monitor include `op-node`, `op-geth`, `op-proposer`, `op-batcher`, and `op-challenger`.
The general steps for enabling offchain monitoring are pretty consistent for all the OP components:

1. Expose the monitoring port by enabling the `--metrics.enabled` flag
2. Customize the metrics port and address via the `--metrics.port` and `--metrics.addr` flags, respectively
3. Use [Prometheus](https://prometheus.io/) to scrape data from the metrics port
4. Save the data in `influxdb`
5. Share the data with [Grafana](https://grafana.com/) to build your custom dashboard

### `op-node`

`op-node` metrics and monitoring is detailed in the [Node Metrics and Monitoring](/node-operators/guides/monitoring/metrics) guide. To enable metrics, pass the `--metrics.enabled` flag to `op-node` and follow the steps above for customization options.
See [this curated list](/operators/node-operators/management/metrics#important-metrics) for important metrics to track specifically for `op-node`.

### `op-geth`

To enable metrics, pass the `--metrics.enabled` flag to the op-geth. You can customize the metrics port and address via the `--metrics.port` and `--metrics.addr` flags, respectively.

### `op-proposer`

To enable metrics, pass the `--metrics.enabled` flag to the op-proposer. You can customize the metrics port and address via the `--metrics.port` and `--metrics.addr` flags, respectively.

You can find more information about these flags in our [Proposer configuration doc](/operators/chain-operators/configuration/proposer#metricsenabled).

### `op-batcher`

To enable metrics, pass the `--metrics.enabled` flag to the op-batcher. You can customize the metrics port and address via the `--metrics.port` and `--metrics.addr` flags, respectively.

You can find more information about these flags in our [Batcher configuration doc](/operators/chain-operators/configuration/proposer#metricsenabled).

### `op-challenger`

The `op-challenger` operates as the *honest actor* in the fault dispute system and defends the chain by securing the `OptimismPortal` and ensuring the game always resolves to the correct state of the chain.
For verifying the legitimacy of claims, `op-challenger` relies on a synced, trusted rollup node as well as a trace provider (e.g., [Cannon](/op-stack/fault-proofs/cannon)). See the [OP-Challenger Explainer](/op-stack/fault-proofs/challenger) for more information on this service.

To enable metrics, pass the `--metrics.enabled` flag to `op-challenger` and follow the steps above for customization options.

```
    --metrics.addr value                (default: "0.0.0.0")               ($OP_CHALLENGER_METRICS_ADDR)
          Metrics listening address
   
    --metrics.enabled                   (default: false)                   ($OP_CHALLENGER_METRICS_ENABLED)
          Enable the metrics server
   
    --metrics.port value                (default: 7300)                    ($OP_CHALLENGER_METRICS_PORT)
          Metrics listening port
```

## Next steps

* If you encounter difficulties at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions).


# Blockscout block explorer
Source: https://docs.optimism.io/chain-operators/tools/explorer

Blockscout an open source block explorer for the OP Stack.

[Blockscout](https://www.blockscout.com/) is an open source block explorer that supports OP Stack chains.
Keep reading for a quick overview on how to deploy Blockscout for your OP Stack chain.

<Info>
  Check out the [Blockscout documentation](https://docs.blockscout.com) for up-to-date information on how to deploy and maintain a Blockscout instance.
</Info>

## Dependencies

* [Docker](https://docs.docker.com/get-docker/)

## Create an archive node

Blockscout needs access to an [archive node](https://www.alchemy.com/overviews/archive-nodes#archive-nodes) for your OP Stack chain to properly index transactions, blocks, and internal interactions.
If using `op-geth`, you can run a node in archive mode with the `--gcmode=archive` flag.

<Info>
  Archive nodes take up significantly more disk space than full nodes.
  You may need to have 2-4 terabytes of disk space available (ideally SSD) if you intend to run an archive node for a production OP Stack chain.
  1-200 gigabytes of disk space may be sufficient for a development chain.
</Info>

## Installation

Blockscout can be started from its source code on GitHub.

```sh theme={null}
git clone https://github.com/blockscout/blockscout.git -b production-optimism
cd blockscout/docker-compose
```

## Configuration

Review the configuration files within the `envs` directory and make any necessary changes.
In particular, make sure to review `envs/common-blockscout.env` and `envs/common-frontend.env`.

## Starting Blockscout

Start Blockscout with the following command:

```sh theme={null}
DOCKER_REPO=blockscout-optimism docker compose -f geth.yml up
```

## Usage

### Explorer

After Blockscout is started, browse to [http://localhost](http://localhost) to view the user interface.
Note that this URL may differ if you have changed the Blockscout configuration.

### API

Blockscout provides both a REST API and a GraphQL API.
Refer to the [API documentation](https://docs.blockscout.com/for-users/api) for more information.


# OP Conductor
Source: https://docs.optimism.io/chain-operators/tools/op-conductor

Understand how op-conductor keeps an OP Stack sequencer highly available, the guarantees it provides, and how its Raft-based design works.

This page explains what the `op-conductor` service is and how it works at a
high level. To add it to an existing network, follow the
[setup guide](/chain-operators/tools/op-conductor/setup). For the full flag and
RPC catalogue, see the
[configuration and RPC reference](/chain-operators/tools/op-conductor/reference).

## Enhancing sequencer reliability and availability

The [op-conductor](https://github.com/ethereum-optimism/optimism/tree/develop/op-conductor)
is an auxiliary service designed to enhance the reliability and availability of
a sequencer within high-availability setups. By minimizing the risks
associated with a single point of failure, the op-conductor ensures that the
sequencer remains operational and responsive.

### Assumptions

It is important to note that the `op-conductor` does not incorporate Byzantine
fault tolerance (BFT). This means the system operates under the assumption that
all participating nodes are honest and act correctly.

### Summary of guarantees

The design of the `op-conductor` provides the following guarantees:

* **No Unsafe Reorgs**
* **No Unsafe Head Stall During Network Partition**
* **100% Uptime with No More Than 1 Node Failure**

## Design

<img alt="op-conductor." />

**On a high level, `op-conductor` serves the following functions:**

### Raft consensus layer participation

* **Leader determination:** Participates in the Raft consensus algorithm to
  determine the leader among sequencers.
* **State management:** Stores the latest unsafe block ensuring consistency
  across the system.

### RPC request handling

* **Admin RPC:** Provides administrative RPCs for manual recovery scenarios,
  including, but not limited to: stopping the leadership vote and removing itself
  from the cluster.
* **Health RPC:** Offers health RPCs for the `op-node` to determine whether it
  should allow the publishing of transactions and unsafe blocks.

### Sequencer health monitoring

* Continuously monitors the health of the sequencer (op-node) to ensure
  optimal performance and reliability.

### Control loop management

* Implements a control loop to manage the status of the sequencer (op-node),
  including starting and stopping operations based on different scenarios and
  health checks.

## Conductor state transition

The following is a state machine diagram of how the op-conductor manages the
sequencers Raft consensus.

<img alt="op-conductor-state-transition." />

**Helpful tips:** To better understand the graph, focus on one node at a time,
understand what can be transitioned to this current state and how it can
transition to other states. This way you could understand how we handle the
state transitions.

## Next steps

* Follow the [setup guide](/chain-operators/tools/op-conductor/setup) to add
  op-conductor to an existing multi-sequencer network without downtime.
* Look up flags and admin RPCs in the
  [configuration and RPC reference](/chain-operators/tools/op-conductor/reference).
* Checkout [op-conductor-mon](https://github.com/ethereum-optimism/infra):
  which monitors multiple op-conductor instances and provides a unified interface
  for reporting metrics.
* Get familiar with [op-conductor-ops](https://github.com/ethereum-optimism/infra/tree/main/op-conductor-ops) to interact with op-conductor.


# Configuration and RPCs
Source: https://docs.optimism.io/chain-operators/tools/op-conductor/reference

Reference for op-conductor configuration flags, environment variables, and conductor namespace RPC methods.

This page catalogues op-conductor's configuration options and its admin RPC
methods. For how the service works, see
[OP Conductor](/chain-operators/tools/op-conductor); to add it to a running
network, follow the [setup guide](/chain-operators/tools/op-conductor/setup).

## Configuration options

<ConfigReferencePreamble />

Generated from [`op-conductor/v0.9.4`](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor%2Fv0.9.4)
flag definitions. 61 flags: 9 required, 52 optional.

### Required flags

| Flag                            | Description                                                                         | Environment variable                       |
| ------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------ |
| `--consensus.addr`              | Address (excluding port) to listen for consensus connections.                       | `OP_CONDUCTOR_CONSENSUS_ADDR`              |
| `--consensus.port`              | Port to listen for consensus connections. May be 0 to let the system select a port. | `OP_CONDUCTOR_CONSENSUS_PORT`              |
| `--execution.rpc`               | HTTP provider URL for execution layer                                               | `OP_CONDUCTOR_EXECUTION_RPC`               |
| `--healthcheck.interval`        | Interval between health checks                                                      | `OP_CONDUCTOR_HEALTHCHECK_INTERVAL`        |
| `--healthcheck.min-peer-count`  | Minimum number of peers required to be considered healthy                           | `OP_CONDUCTOR_HEALTHCHECK_MIN_PEER_COUNT`  |
| `--healthcheck.unsafe-interval` | Interval allowed between unsafe head and now measured in seconds                    | `OP_CONDUCTOR_HEALTHCHECK_UNSAFE_INTERVAL` |
| `--node.rpc`                    | HTTP provider URL for op-node                                                       | `OP_CONDUCTOR_NODE_RPC`                    |
| `--raft.server.id`              | Unique ID for this server used by raft consensus                                    | `OP_CONDUCTOR_RAFT_SERVER_ID`              |
| `--raft.storage.dir`            | Directory to store raft data                                                        | `OP_CONDUCTOR_RAFT_STORAGE_DIR`            |

### Optional flags

| Flag                                                                        | Description                                                                                                                                                                                                                              | Default     | Environment variable                                                                   |
| --------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `--consensus.advertised`                                                    | Full address (host and port) for other peers to contact the consensus server. Optional: if left empty, the local address is advertised.                                                                                                  | —           | `OP_CONDUCTOR_CONSENSUS_ADVERTISED`                                                    |
| `--healthcheck.execution-p2p-check-api`                                     | Type of EL P2P check to perform. If not set, the default `net` type will be used corresponding to the `net_peerCount` RPC call.                                                                                                          | `"net"`     | `OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_CHECK_API`                                     |
| `--healthcheck.execution-p2p-enabled`                                       | Whether to enable EL P2P checks                                                                                                                                                                                                          | `false`     | `OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_ENABLED`                                       |
| `--healthcheck.execution-p2p-min-peer-count`                                | Minimum number of EL P2P peers required to be considered healthy                                                                                                                                                                         | `0`         | `OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_MIN_PEER_COUNT`                                |
| `--healthcheck.execution-p2p-rpc-url`                                       | URL override for the execution layer RPC client for the sake of p2p healthcheck. If not set, the execution RPC URL will be used.                                                                                                         | —           | `OP_CONDUCTOR_HEALTHCHECK_EXECUTION_P2P_RPC_URL`                                       |
| `--healthcheck.rollup-boost-partial-healthiness-tolerance-interval-seconds` | The time frame within which rollup-boost partial healthiness tolerance is evaluated                                                                                                                                                      | `0`         | `OP_CONDUCTOR_HEALTHCHECK_ROLLUP_BOOST_PARTIAL_HEALTHINESS_TOLERANCE_INTERVAL_SECONDS` |
| `--healthcheck.rollup-boost-partial-healthiness-tolerance-limit`            | Sets the count of rollup-boost partial healthiness failures to occur before marking op-conducto as unhealthy. Default is 0 with which a single occurrence of rollup-boost partial healthiness is enough to set op-conductor as unhealthy | `0`         | `OP_CONDUCTOR_HEALTHCHECK_ROLLUP_BOOST_PARTIAL_HEALTHINESS_TOLERANCE_LIMIT`            |
| `--healthcheck.safe-enabled`                                                | Whether to enable safe head progression checks                                                                                                                                                                                           | `false`     | `OP_CONDUCTOR_HEALTHCHECK_SAFE_ENABLED`                                                |
| `--healthcheck.safe-interval`                                               | Interval between safe head progression measured in seconds                                                                                                                                                                               | `1200`      | `OP_CONDUCTOR_HEALTHCHECK_SAFE_INTERVAL`                                               |
| `--log.color`                                                               | Color the log output if in terminal mode                                                                                                                                                                                                 | `false`     | `OP_CONDUCTOR_LOG_COLOR`                                                               |
| `--log.format`                                                              | Format the log output. Supported formats: text, terminal, logfmt, logfmtms, json, jsonms                                                                                                                                                 | `text`      | `OP_CONDUCTOR_LOG_FORMAT`                                                              |
| `--log.level`                                                               | The lowest log level that will be output                                                                                                                                                                                                 | `INFO`      | `OP_CONDUCTOR_LOG_LEVEL`                                                               |
| `--log.pid`                                                                 | Show pid in the log                                                                                                                                                                                                                      | `false`     | `OP_CONDUCTOR_LOG_PID`                                                                 |
| `--metrics.addr`                                                            | Metrics listening address                                                                                                                                                                                                                | `"0.0.0.0"` | `OP_CONDUCTOR_METRICS_ADDR`                                                            |
| `--metrics.enabled`                                                         | Enable the metrics server                                                                                                                                                                                                                | `false`     | `OP_CONDUCTOR_METRICS_ENABLED`                                                         |
| `--metrics.port`                                                            | Metrics listening port                                                                                                                                                                                                                   | `7300`      | `OP_CONDUCTOR_METRICS_PORT`                                                            |
| `--network`                                                                 | Predefined network selection. Available networks: every chain bundled from the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) at the release; run `op-conductor --help` for the exact list              | —           | `OP_CONDUCTOR_NETWORK`                                                                 |
| `--override.canyon`                                                         | Manually specify the canyon fork timestamp, overriding the bundled setting                                                                                                                                                               | `0`         | `OP_CONDUCTOR_OVERRIDE_CANYON`                                                         |
| `--override.delta`                                                          | Manually specify the delta fork timestamp, overriding the bundled setting                                                                                                                                                                | `0`         | `OP_CONDUCTOR_OVERRIDE_DELTA`                                                          |
| `--override.ecotone`                                                        | Manually specify the ecotone fork timestamp, overriding the bundled setting                                                                                                                                                              | `0`         | `OP_CONDUCTOR_OVERRIDE_ECOTONE`                                                        |
| `--override.fjord`                                                          | Manually specify the fjord fork timestamp, overriding the bundled setting                                                                                                                                                                | `0`         | `OP_CONDUCTOR_OVERRIDE_FJORD`                                                          |
| `--override.granite`                                                        | Manually specify the granite fork timestamp, overriding the bundled setting                                                                                                                                                              | `0`         | `OP_CONDUCTOR_OVERRIDE_GRANITE`                                                        |
| `--override.holocene`                                                       | Manually specify the holocene fork timestamp, overriding the bundled setting                                                                                                                                                             | `0`         | `OP_CONDUCTOR_OVERRIDE_HOLOCENE`                                                       |
| `--override.interop`                                                        | Manually specify the interop fork timestamp, overriding the bundled setting                                                                                                                                                              | `0`         | `OP_CONDUCTOR_OVERRIDE_INTEROP`                                                        |
| `--override.isthmus`                                                        | Manually specify the isthmus fork timestamp, overriding the bundled setting                                                                                                                                                              | `0`         | `OP_CONDUCTOR_OVERRIDE_ISTHMUS`                                                        |
| `--override.jovian`                                                         | Manually specify the jovian fork timestamp, overriding the bundled setting                                                                                                                                                               | `0`         | `OP_CONDUCTOR_OVERRIDE_JOVIAN`                                                         |
| `--override.karst`                                                          | Manually specify the karst fork timestamp, overriding the bundled setting                                                                                                                                                                | `0`         | `OP_CONDUCTOR_OVERRIDE_KARST`                                                          |
| `--override.pectrablobschedule`                                             | Manually specify the pectrablobschedule fork timestamp, overriding the bundled setting                                                                                                                                                   | `0`         | `OP_CONDUCTOR_OVERRIDE_PECTRABLOBSCHEDULE`                                             |
| `--paused`                                                                  | Whether the conductor is paused                                                                                                                                                                                                          | `false`     | `OP_CONDUCTOR_PAUSED`                                                                  |
| `--pprof.addr`                                                              | pprof listening address                                                                                                                                                                                                                  | `"0.0.0.0"` | `OP_CONDUCTOR_PPROF_ADDR`                                                              |
| `--pprof.enabled`                                                           | Enable the pprof server                                                                                                                                                                                                                  | `false`     | `OP_CONDUCTOR_PPROF_ENABLED`                                                           |
| `--pprof.path`                                                              | pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof                                                                                                                                                            | —           | `OP_CONDUCTOR_PPROF_PATH`                                                              |
| `--pprof.port`                                                              | pprof listening port                                                                                                                                                                                                                     | `6060`      | `OP_CONDUCTOR_PPROF_PORT`                                                              |
| `--pprof.type`                                                              | pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs                                                                                                                                                      | —           | `OP_CONDUCTOR_PPROF_TYPE`                                                              |
| `--raft.bootstrap`                                                          | If this node should bootstrap a new raft cluster                                                                                                                                                                                         | `false`     | `OP_CONDUCTOR_RAFT_BOOTSTRAP`                                                          |
| `--raft.heartbeat-timeout`                                                  | Heartbeat interval timeout                                                                                                                                                                                                               | `1s`        | `OP_CONDUCTOR_RAFT_HEARTBEAT_TIMEOUT`                                                  |
| `--raft.lease-timeout`                                                      | Leader lease timeout                                                                                                                                                                                                                     | `500ms`     | `OP_CONDUCTOR_RAFT_LEASE_TIMEOUT`                                                      |
| `--raft.round-robin-leader-transfer`                                        | Enable deterministic round-robin leader transfer instead of Raft's default log-based selection. Must be enabled on all conductors in the cluster.                                                                                        | `false`     | `OP_CONDUCTOR_RAFT_ROUND_ROBIN_LEADER_TRANSFER`                                        |
| `--raft.snapshot-interval`                                                  | The interval to check if a snapshot should be taken.                                                                                                                                                                                     | `2m0s`      | `OP_CONDUCTOR_RAFT_SNAPSHOT_INTERVAL`                                                  |
| `--raft.snapshot-threshold`                                                 | Number of logs to trigger a snapshot                                                                                                                                                                                                     | `8192`      | `OP_CONDUCTOR_RAFT_SNAPSHOT_THRESHOLD`                                                 |
| `--raft.trailing-logs`                                                      | Number of logs to keep after a snapshot                                                                                                                                                                                                  | `10240`     | `OP_CONDUCTOR_RAFT_TRAILING_LOGS`                                                      |
| `--rollup-boost.enabled`                                                    | Enable the rollup-boost healthcheck that uses HTTP status codes (200/206/503). Healthchecks are performed against execution.rpc + '/healthz' (path appended automatically). Mutually exclusive with rollup-boost.next-enabled.           | `false`     | `OP_CONDUCTOR_ROLLUP_BOOST_ENABLED`                                                    |
| `--rollup-boost.healthcheck-timeout`                                        | Timeout for rollup-boost healthchecks (applies to both standard and next)                                                                                                                                                                | `5s`        | `OP_CONDUCTOR_ROLLUP_BOOST_HEALTHCHECK_TIMEOUT`                                        |
| `--rollup-boost.next-enabled`                                               | Enable rollup-boost healthcheck using JSON response parsing. Requires rollup-boost.next-healthcheck-url. Mutually exclusive with rollup-boost.enabled.                                                                                   | `false`     | `OP_CONDUCTOR_ROLLUP_BOOST_NEXT_ENABLED`                                               |
| `--rollup-boost.next-healthcheck-url`                                       | Full URL including path for the rollup-boost health endpoint (e.g., '[http://localhost:8080/healthz](http://localhost:8080/healthz)'). Required when rollup-boost.next-enabled is true.                                                  | —           | `OP_CONDUCTOR_ROLLUP_BOOST_NEXT_HEALTHCHECK_URL`                                       |
| `--rollup.config`                                                           | Rollup chain parameters                                                                                                                                                                                                                  | —           | `OP_CONDUCTOR_ROLLUP_CONFIG`                                                           |
| `--rollupboost.ws-url`                                                      | WebSocket URL for the rollup boost to listen for payload streams.                                                                                                                                                                        | —           | `OP_CONDUCTOR_ROLLUPBOOST_WS_URL`                                                      |
| `--rpc.addr`                                                                | rpc listening address                                                                                                                                                                                                                    | `"0.0.0.0"` | `OP_CONDUCTOR_RPC_ADDR`                                                                |
| `--rpc.enable-admin`                                                        | Enable the admin API                                                                                                                                                                                                                     | `false`     | `OP_CONDUCTOR_RPC_ENABLE_ADMIN`                                                        |
| `--rpc.enable-proxy`                                                        | Enable the RPC proxy to underlying sequencer services                                                                                                                                                                                    | `true`      | `OP_CONDUCTOR_RPC_ENABLE_PROXY`                                                        |
| `--rpc.port`                                                                | rpc listening port                                                                                                                                                                                                                       | `8545`      | `OP_CONDUCTOR_RPC_PORT`                                                                |
| `--websocket.server-port`                                                   | Port for the conductor to run a WebSocket server that pushes payload streams out.                                                                                                                                                        | `8546`      | `OP_CONDUCTOR_WEBSOCKET_SERVER_PORT`                                                   |

## Notes on selected flags

### raft.bootstrap

<Info>
  For bootstrapping a new cluster. This should only be used on the sequencer
  that is currently active and can only be started once with this flag,
  otherwise the flag has to be removed or the raft log must be deleted before
  re-bootstrapping the cluster.
</Info>

### paused

<Info>
  There is no configuration state, so if you unpause via RPC and then restart,
  it will start paused again.
</Info>

## RPCs

Conductor exposes [admin RPCs](https://github.com/ethereum-optimism/optimism/blob/develop/op-conductor/rpc/api.go#L17)
on the `conductor` namespace.

### conductor\_overrideLeader

`OverrideLeader` is used to override the leader status, this is only used to
return true for `Leader()` & `LeaderWithID()` calls. It does not impact the
actual raft consensus leadership status. It is supposed to be used when the
cluster is unhealthy and the node is the only one up, to allow batcher to
be able to connect to the node so that it could download blocks from the
manually started sequencer.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_overrideLeader","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_overrideLeader --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_pause

`Pause` pauses op-conductor.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_pause","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_pause --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_resume

`Resume` resumes op-conductor.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_resume","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_resume --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_paused

Paused returns true if the op-conductor is paused.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_paused","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_paused --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_stopped

Stopped returns true if the op-conductor is stopped.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_stopped","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_stopped --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_sequencerHealthy

SequencerHealthy returns true if the sequencer is healthy.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_sequencerHealthy","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_sequencerHealthy --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_leader

<Info>
  API related to consensus.
</Info>

Leader returns true if the server is the leader.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_leader","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_leader --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_leaderWithID

<Info>
  API related to consensus.
</Info>

LeaderWithID returns the current leader's server info.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_leaderWithID","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_leaderWithID --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_addServerAsVoter

<Info>
  API related to consensus.
</Info>

AddServerAsVoter adds a server as a voter to the cluster.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_addServerAsVoter","params":[<raft-server-id>, <raft-consensus-addr>, <raft-config-version>],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_addServerAsVoter <raft-server-id> <raft-consensus-addr> <raft-config-version> --rpc-url http://127.0.0.1:8547 
    ```
  </Tab>
</Tabs>

### conductor\_addServerAsNonvoter

<Info>
  API related to consensus.
</Info>

AddServerAsNonvoter adds a server as a non-voter to the cluster. non-voter
The non-voter will not participate in the leader election.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_addServerAsNonvoter","params":[<raft-server-id>, <raft-consensus-addr>, <raft-config-version>],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_addServerAsNonvoter <raft-server-id> <raft-consensus-addr> <raft-config-version> --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_removeServer

<Info>
  API related to consensus.
</Info>

RemoveServer removes a server from the cluster.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_removeServer","params":[<raft-server-id>, <raft-config-version>],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_removeServer <raft-server-id> <raft-config-version> --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_transferLeader

<Info>
  API related to consensus.
</Info>

TransferLeader transfers leadership to another server (resigns).

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_transferLeader","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_transferLeader --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_transferLeaderToServer

<Info>
  API related to consensus.
</Info>

TransferLeaderToServer transfers leadership to a specific server.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_transferLeaderToServer","params":[<raft-server-id>, <raft-consensus-addr>, <raft-config-version>],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_transferLeaderToServer <raft-server-id> <raft-consensus-addr> <raft-config-version> --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_clusterMembership

ClusterMembership returns the current cluster membership configuration.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_clusterMembership","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_clusterMembership --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_active

<Info>
  API called by `op-node`.
</Info>

Active returns true if the op-conductor is active (not paused or stopped).

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_active","params":[],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc conductor_active --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>

### conductor\_commitUnsafePayload

<Info>
  API called by `op-node`.
</Info>

CommitUnsafePayload commits an unsafe payload (latest head) to the consensus
layer. This method is typically called by the op-node to commit execution payload envelopes.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"conductor_commitUnsafePayload","params":[{
            "executionPayload": {
                "parentHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                "feeRecipient": "0x4200000000000000000000000000000000000019",
                "stateRoot": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
                "receiptsRoot": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
                "prevRandao": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
                "blockNumber": "0x64",
                "gasLimit": "0x1c9c380",
                "gasUsed": "0x5208",
                "timestamp": "0x12345678",
                "extraData": "0x",
                "baseFeePerGas": "0x7",
                "blockHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
                "transactions": []
            }
        }],"id":1}'  \
        http://127.0.0.1:8547
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    # Example with basic payload structure
    cast rpc conductor_commitUnsafePayload \
        '{"executionPayload":{"parentHash":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","feeRecipient":"0x4200000000000000000000000000000000000019","stateRoot":"0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890","receiptsRoot":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000","prevRandao":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef","blockNumber":"0x64","gasLimit":"0x1c9c380","gasUsed":"0x5208","timestamp":"0x12345678","extraData":"0x","baseFeePerGas":"0x7","blockHash":"0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba","transactions":[]}}' \
        --rpc-url http://127.0.0.1:8547
    ```
  </Tab>
</Tabs>


# Setup
Source: https://docs.optimism.io/chain-operators/tools/op-conductor/setup

Add op-conductor to an existing multi-sequencer OP Stack network without downtime.

For how op-conductor works and the guarantees it provides, see
[OP Conductor](/chain-operators/tools/op-conductor). The flags and RPC methods
used below are catalogued in the
[configuration and RPC reference](/chain-operators/tools/op-conductor/reference).

At OP Labs, op-conductor is deployed as a kubernetes statefulset because it
requires a persistent volume to store the raft log. This guide describes
setting up conductor on an existing network without incurring downtime.

You can utilize the [op-conductor-ops](https://github.com/ethereum-optimism/infra/tree/main/op-conductor-ops) tool to confirm the conductor status between the steps.

## Assumptions

This setup guide has the following assumptions:

* 3 deployed sequencers (sequencer-0, sequencer-1, sequencer-2) that are all
  in sync and in the same vpc network
* sequencer-0 is currently the active sequencer
* You can execute a blue/green style sequencer deployment workflow that
  involves no downtime (described below)
* conductor and sequencers are running in k8s or some other container
  orchestrator (vm-based deployment may be slightly different and not covered
  here)

## Spin up op-conductor

<Steps>
  <Step title="Deploy conductor">
    Deploy a conductor instance per sequencer with sequencer-1 as the raft cluster
    bootstrap node:

    * suggested conductor configs:

      ```yaml theme={null}
      OP_CONDUCTOR_CONSENSUS_ADDR: '0.0.0.0'
      OP_CONDUCTOR_CONSENSUS_ADVERTISED: '<raft url or ip>'
      OP_CONDUCTOR_CONSENSUS_PORT: '50050'
      OP_CONDUCTOR_EXECUTION_RPC: '<op-geth url or ip>:8545'
      OP_CONDUCTOR_HEALTHCHECK_INTERVAL: '1'
      OP_CONDUCTOR_HEALTHCHECK_MIN_PEER_COUNT: '2'  # set based on your internal p2p network peer count
      OP_CONDUCTOR_HEALTHCHECK_UNSAFE_INTERVAL: '5' # recommend a 2-3x multiple of your network block time to account for temporary performance issues
      OP_CONDUCTOR_LOG_FORMAT: logfmt
      OP_CONDUCTOR_LOG_LEVEL: info
      OP_CONDUCTOR_METRICS_ADDR: 0.0.0.0
      OP_CONDUCTOR_METRICS_ENABLED: 'true'
      OP_CONDUCTOR_METRICS_PORT: '7300'
      OP_CONDUCTOR_NETWORK: '<network>'
      OP_CONDUCTOR_NODE_RPC: '<op-node url or ip>:8545'
      OP_CONDUCTOR_RAFT_SERVER_ID: 'unique raft server id'
      OP_CONDUCTOR_RAFT_STORAGE_DIR: /conductor/raft
      OP_CONDUCTOR_RPC_ADDR: 0.0.0.0
      OP_CONDUCTOR_RPC_ENABLE_ADMIN: 'true'
      OP_CONDUCTOR_RPC_ENABLE_PROXY: 'true'
      OP_CONDUCTOR_RPC_PORT: '8547'
      ```

    * sequencer-1 op-conductor extra config:

      ```yaml theme={null}
      OP_CONDUCTOR_PAUSED: "true"
      OP_CONDUCTOR_RAFT_BOOTSTRAP: "true"
      ```
  </Step>

  <Step title="Pause two conductors">
    Pause `sequencer-0` &` sequencer-2` conductors with [conductor\_pause](/chain-operators/tools/op-conductor/reference#conductor_pause) RPC request.
  </Step>

  <Step title="Update op-node configuration and switch the active sequencer">
    Deploy an `op-node` config update to all sequencers that enables conductor. Use
    a blue/green style deployment workflow that switches the active sequencer to
    `sequencer-1`:

    * all sequencer op-node configs:

      ```yaml theme={null}
      OP_NODE_CONDUCTOR_ENABLED: "true" # this is what commits unsafe blocks to the raft logs
      OP_NODE_RPC_ADMIN_STATE: "" # this flag can't be used with conductor
      ```
  </Step>

  <Step title="Confirm sequencer switch was successful">
    Confirm `sequencer-1` is active and successfully producing unsafe blocks.
    Because `sequencer-1` was the raft cluster bootstrap node, it is now committing
    unsafe payloads to the raft log.
  </Step>

  <Step title="Add voting nodes">
    Add voting nodes to cluster using [conductor\_AddServerAsVoter](/chain-operators/tools/op-conductor/reference#conductor_addserverasvoter)
    RPC request to the leader conductor (`sequencer-1`)
  </Step>

  <Step title="Confirm state">
    Confirm cluster membership and sequencer state:

    * `sequencer-0` and `sequencer-2`:
      1. raft cluster follower
      2. sequencer is stopped
      3. conductor is paused
      4. conductor enabled in op-node config

    * `sequencer-1`
      1. raft cluster leader
      2. sequencer is active
      3. conductor is paused
      4. conductor enabled in op-node config
  </Step>

  <Step title="Resume conductors">
    Resume all conductors with [conductor\_resume](/chain-operators/tools/op-conductor/reference#conductor_resume) RPC request to
    each conductor instance.
  </Step>

  <Step title="Confirm state">
    Confirm all conductors successfully resumed with [conductor\_paused](/chain-operators/tools/op-conductor/reference#conductor_paused)
  </Step>

  <Step title="Transfer leadership">
    Trigger leadership transfer to `sequencer-0` using [conductor\_transferLeaderToServer](/chain-operators/tools/op-conductor/reference#conductor_transferleadertoserver)
  </Step>

  <Step title="Confirm state">
    Confirm cluster membership and sequencer state:

    **`sequencer-1` and `sequencer-2`:**

    1. raft cluster follower
    2. sequencer is stopped
    3. conductor is active
    4. conductor enabled in op-node config

    **`sequencer-0`:**

    1. raft cluster leader
    2. sequencer is active
    3. conductor is active
    4. conductor enabled in op-node config
  </Step>

  <Step title="Update configuration">
    Deploy a config change to `sequencer-1` conductor to remove the
    `OP_CONDUCTOR_PAUSED: true` flag and `OP_CONDUCTOR_RAFT_BOOTSTRAP` flag.
  </Step>
</Steps>

### Blue/green deployment

In order to ensure there is no downtime when setting up conductor, you need to
have a deployment script that can update sequencers without network downtime.

An example of this workflow might look like:

1. Query current state of the network and determine which sequencer is
   currently active (referred to as "original" sequencer below).
   From the other available sequencers, choose a candidate sequencer.
2. Deploy the change to the candidate sequencer and then wait for it to sync
   up to the original sequencer's unsafe head. You may want to check peer counts
   and other important health metrics.
3. Stop the original sequencer using `admin_stopSequencer` which returns the
   last inserted unsafe block hash. Wait for candidate sequencer to sync with
   this returned hash in case there is a delta.
4. Start the candidate sequencer at the original's last inserted unsafe block
   hash.
   1. Here you can also execute additional check for unsafe head progression
      and decide to roll back the change (stop the candidate sequencer, start the
      original, rollback deployment of candidate, etc.)
5. Deploy the change to the original sequencer, wait for it to sync to the
   chain head. Execute health checks.

### Post-conductor launch deployments

After conductor is live, a similar canary style workflow is used to ensure
minimal downtime in case there is an issue with deployment:

1. Choose a candidate sequencer from the raft-cluster followers
2. Deploy to the candidate sequencer. Run health checks on the candidate.
3. Transfer leadership to the candidate sequencer using
   `conductor_transferLeaderToServer`. Run health checks on the candidate.
4. Test if candidate is still the leader using `conductor_leader` after some
   grace period (ex: 30 seconds)
   1. If not, then there is likely an issue with the deployment. Roll back.
5. Upgrade the remaining sequencers, run healthchecks.


# Install op-deployer
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/installation

Learn how to install op-deployer from pre-built binaries or from source.

OP Deployer can be installed both from pre-built binaries and from source. This guide will walk you through both
methods.

## Install From Binaries

Installing OP Deployer from pre-built binaries is the easiest and most preferred way to get started. To install from
binaries, download the latest release from the [releases page](https://github.com/ethereum-optimism/optimism/releases?q=op-deployer\&expanded=true) and extract the binary to a directory in your
`$PATH`.

## Install From Source

To install from source, you will need Go, `just`, and `git`. Then, run the following:

```shell theme={null}
git clone git@github.com:ethereum-optimism/optimism.git # you can skip this if you already have the repo
cd optimism/op-deployer
just build
cp ./bin/op-deployer /usr/local/bin/op-deployer # or any other directory in your $PATH
```


# Known Limitations
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/known-limitations

Known limitations and workarounds for OP Deployer.

OP Deployer is subject to some known limitations which we're working on addressing in future releases.

## Tagged Releases on New Chains

<Info>
  **Fixed in all versions after v0.0.11.**
</Info>

It is not currently possible to deploy chains using tagged contract locators (i.e., those starting with `tag://`)
anywhere except Sepolia and Ethereum mainnet. If you try to, you'll see an error like this:

```
####################### WARNING! WARNING WARNING! #######################

You are deploying a tagged release to a chain with no pre-deployed OPCM.
Due to a quirk of our contract version system, this can lead to deploying
contracts containing unaudited or untested code. As a result, this
functionality is currently disabled.

We will fix this in an upcoming release.

This process will now exit.

####################### WARNING! WARNING WARNING! #######################
```

Like the error says, this is due to a quirk of how we version our smart contracts. We currently follow a process
like this:

1. We tag a release, like op-contracts/v1.8.0.
2. We update the [release notes](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv1.8.0) to reference which contracts are updated in that release.
3. We manually deploy the updated contract implementations.
4. We manually deploy a new OPCM to reference the newly-deployed implementations, as well as existing implementations
   for any contracts that have not been updated.

There's a flaw in this strategy, however. The release only includes the contracts that explicitly changed during
that release. **This means that any contract not referenced as "updated" in the release notes is "in-development," and
has not been audited or approved by governance.** Deploying all contracts from the release tag will therefore deploy a
combination of prod-ready and in-development code. To get the version of the contract that will *actually* run in prod,
OP Deployer would have to reference all previous releases to get the correct combination of contracts.

For example, to deploy on Holesky you will need to deploy contracts from versions `op-contracts/v1.8.0`, `op-contracts/v1.6.0`, and `op-contracts/v1.3.0`. On
Sepolia and mainnet, we've been incrementally deploying implementation contracts so we just use the existing
implementations to work around this issue.

We plan on addressing this in our next release. In the meantime, as a workaround you can use a non-tagged locator for
development chains, or use Sepolia or Ethereum mainnet as your L1.


# OP Deployer
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/overview

A CLI tool for deploying and upgrading smart contracts for OP Stack chains.

OP Deployer is a CLI tool that simplifies deploying and upgrading smart contracts for OP Stack chains. It also
exposes a suite of libraries that allow developers to easily manage smart contracts from their applications.

## Goals

### Declarative

With OP Deployer, developers define their chain's desired configuration in a declarative configuration file. The tool
then makes the minimum number of smart contract calls required to make the deployment match the configuration. This
ensures that the implementation details of the deployment are abstracted away, and allows complex configurations to be
expressed cleanly without concern for the underlying deployment process.

### Portable

OP Deployer is designed to be small, portable, and easily installed. As such it is distributed as a standalone binary
with no additional dependencies. This allows it to be used in a variety of contexts, including as a CLI tool, in CI
pipelines, and as part of local development environments like [Kurtosis](https://github.com/ethpandaops/optimism-package).

### Standard, But Extensible

OP Deployer aims to make doing the right thing easy, and doing dangerous things hard. As such its configuration and
API are optimized for deploying and upgrading Standard OP Chains. However, it also exposes a lower-level set of
primitives and configuration directives which users can use to deploy more complex configurations if the need arises.

## Development Status

<Warning>
  OP Deployer is undergoing active development and has been used for several mainnet deployments. It is considered
  production-ready. However, please keep in mind that **OP Deployer has not been audited** and that any chains
  deployed using OP Deployer should be checked thoroughly for correctness prior to launch.
</Warning>

## Next Steps

* [Install op-deployer](/chain-operators/tools/op-deployer/installation) - Install from pre-built binaries or from source
* [Bootstrap](/chain-operators/tools/op-deployer/usage/bootstrap) - Deploy global singletons and implementation contracts
* [Architecture](/chain-operators/tools/op-deployer/reference/architecture/overview) - Understand OP Deployer's architecture


# Scripting Engine
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/reference/architecture/engine

Understand OP Deployer's in-memory EVM scripting engine: what it enables, why on-chain interactions run through Solidity scripts, and how Go code communicates with scripts inside the simulated EVM.

One of OP Deployer's most powerful features is its in-memory EVM scripting engine. The scripting engine provides
similar capabilities to Forge:

* It runs all on-chain calls in a simulated environment first, which allows the effects of on-chain calls to be
  validated before they cost gas.
* It exposes Foundry cheatcodes, which allow for deep instrumentation and customization of the EVM environment. These
  cheatcodes in turn allow OP Deployer to call into Solidity scripts.

The scripting engine is really the heart of OP Deployer. Without it, OP Deployer would be nothing more than a thin
wrapper over Forge. The scripting engine enables:

* Easy integration with existing Solidity-based tooling.
* Detailed stack traces when deployments fail.
* Fast feedback loops that prevent sending on-chain transactions that may fail.
* Live chain forking.

For these reasons and more, the scripting engine is a critical part of OP Deployer's architecture. You will see that
almost all on-chain interactions initiated by OP Deployer use the scripting engine to call into a Solidity script.
The script then uses `vm.broadcast` to signal a transaction that should be sent on-chain.

## Why Use Solidity Scripts?

Solidity scripts are much more ergonomic than Go code for complex on-chain interactions. They allow for:

* Easy integration with existing Solidity-based tooling and libraries.
* Simple ABI encoding/decoding.
* Clear separation of concerns between inter-contract calls, and the underlying RPC calls that drive them.

The alternative is to encode all on-chain interactions in Go code. This is possible, but it is much more verbose and
requires writing bindings between Go and the Solidity ABI. These bindings are error-prone and difficult to maintain.

## Engine Implementation

The scripting engine is implemented in the `op-chain-ops/script` package. It extends Geth's EVM implementation with
Forge cheatcodes, and defines some tools that allow Go structs to be etched into the EVM's memory. Geth exposes
hooks that drive most of the engine's behavior. The best way to understand these further is to read the code.

## Using the Engine

OP Deployer uses the etching tooling described above to communicate between OP Deployer and the scripting engine.
Most Solidity scripts define an input contract, an output contract, and the script itself. The script reads data
from fields on the input contract, then sets fields on the output contract as it runs. OP Deployer defines the input
and output contracts as Go structs, like this:

```go theme={null}
package foo_script

type FooInput struct {
  Number uint64
  Bytes []byte
}

type FooOutput struct {
  Result uint64
  Bytes []byte
}
```

The input and output contracts are then "etched" into the EVM's memory, like this:

```go theme={null}
package foo_script

// ... struct defs elided

func Run(host *script.Host, input FooInput) (FooOutput, error) {
	// Create a variable to hold our output
	var output FooOutput

	// Make new addresses for our input/output contracts
	inputAddr := host.NewScriptAddress()
	outputAddr := host.NewScriptAddress()

	// Inject the input/output contracts into the EVM as precompiles
	cleanupInput, err := script.WithPrecompileAtAddress[*FooInput](host, inputAddr, &input)
	if err != nil {
		return output, fmt.Errorf("failed to insert input precompile: %w", err)
	}
	defer cleanupInput()

	cleanupOutput, err := script.WithPrecompileAtAddress[*FooOutput](host, outputAddr, &output,
		script.WithFieldSetter[*FooOutput])
	if err != nil {
		return output, fmt.Errorf("failed to insert output precompile: %w", err)
	}
	defer cleanupOutput()

	// ... do stuff with the input/output contracts ...
}
```

The script engine will automatically generate getters and setters for the fields on the input and output contracts.
You can use the `evm:` struct tag to customize the behavior of these getters and setters.

Finally, the script itself gets etched into the EVM's memory and executed, like this:

```go theme={null}
package foo_script

type FooScript struct {
	Run func(input, output common.Address) error
}

func Run(host *script.Host, input FooInput) (FooOutput, error) {
	// .. see implementation above...

	deployScript, cleanupDeploy, err := script.WithScript[FooScript](host, "FooScript.s.sol", "FooScript")
	if err != nil {
		return output, fmt.Errorf("failed to load %s script: %w", scriptFile, err)
	}
	defer cleanupDeploy()

	if err := deployScript.Run(inputAddr, outputAddr); err != nil {
		return output, fmt.Errorf("failed to run %s script: %w", scriptFile, err)
	}

	return output, nil
}
```

You may notice that the script is loaded from a file. To run the scripting engine, contract artifacts (**not**
source code) must exist somewhere on disk for the scripting engine to use. For more information on that, see the
[Artifacts Locators](/chain-operators/tools/op-deployer/reference/artifacts-locators) page.


# Architecture
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/reference/architecture/overview

Understand OP Deployer's architecture and internals.

This section details OP Deployer's architecture and internals. Unless you're contributing directly to OP Deployer,
you don't need to read this.

* [Deployment Pipeline](/chain-operators/tools/op-deployer/reference/architecture/pipeline): Describes the stages of the deployment pipeline.
* [Scripting Engine](/chain-operators/tools/op-deployer/reference/architecture/engine): Describes the scripting engine that OP Deployer uses to interact
  with the EVM.

<img alt="Full architecture diagram" />

*Full architecture diagram ([source](https://www.figma.com/board/bbp16y6ZwIkxzOoKhDu9kk/op-deployer-architecture?node-id=0-1\&p=f\&t=1Eg9JBP0RuVmdtsM-0))*


# Deployment Pipeline
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/reference/architecture/pipeline

Understand how OP Deployer's pipeline is architected: the intent and state files it consumes and produces, and what each deployment stage is responsible for.

This page explains how OP Deployer is architected: a pipeline in which each stage is responsible for a single piece of the deployment process.
The pipeline consumes a configuration called an *intent* which describes the desired state of the chain, and
produces a file called the *state* which describes the current state of the chain during and after the deployment.
The steps of the pipeline are:

1. Initialization
2. Shared Contracts Deployment
3. Implementations Deployment
4. OP Chain Deployment
5. Alt-DA Deployment
6. Dispute Game Deployment
7. L2 Genesis Generation
8. Setting Start Block

State is written to disk after each state. This allows the pipeline to be restarted from any point in the event of a
recoverable error.

We'll cover each of these stages in more detail below.

## Initialization

During this step, OP Deployer sets initial values for the pipeline based on the user's intent. These values will be
used by downstream stages. For example, if the user is deploying using an existing set of shared contracts,
those contracts will be inserted into the state during this step.

## Shared Contracts/Implementations Deployment

Next, the base contracts for the chain are deployed. This includes shared management contracts like
`SuperchainConfig`, as well as implementation contracts that will be used for the OP Chain
deployment in the future like the OP Contracts Manager (OPCM).

Most chains will be configured to use existing implementations. In this case, these steps will be skipped.

## OP Chain Deployment

The OP Chain itself is deployed during this step. Multiple chains will be deployed if they are specified in the
intent. The deployment works by calling into the OPCM, which will emit an event for each successfully-deployed chain.

## Customizations Deployment

The next two steps (Alt-DA and Dispute Game) deploy customizations. As their names imply, they deploy Alt-DA and
additional dispute game contracts. Typically, these steps will be skipped as they are mostly useful in testing.

## L2 Genesis Generation

This step generates the L2 Genesis file which is used to initialize the chain. This file is generated by calling
into `L2Genesis.sol`, and dumping the outputted state.

## Setting Start Block

Lastly, the start block is set to the current block number on L1. This is done last to ensure that the start block
is relatively recent, since the deployment process can take arbitrarily long.


# Artifacts Locators
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/reference/artifacts-locators

Learn how OP Deployer uses artifacts locators to point to contract artifacts.

OP Deployer calls into precompiled contract artifacts. To make this work, OP Deployer uses artifacts locators to
point to the location of contract artifacts. While locators are nothing more than URLs, they do encode some
additional behaviors which are described here.

## Locator Types

Locators can be one of three types:

* `tag://` locators, which point to a versioned contracts release. These resolve to a known URL. Artifacts
  downloaded using a tagged locator are validated against a hardcoded checksum in the OP Deployer implementation.
  This prevents tampering with the contract artifacts once they have been tagged. Additionally, tagged locators are
  cached on disk to avoid repeated downloads.
  * ex: `tag://op-contracts/v1.8.0-rc.4`
* `https://` locators, which point to a tarball of contract artifacts somewhere on the web. HTTP locators are cached
  just like tagged locators are, but they are not validated against a checksum.
  * ex: `https://<url-to-remote-forge-artifacts>`
* `file://` locators, which point to a directory on local disk containing the artifacts.
  * ex: `file://<path-to-repo-root>/packages/contracts-bedrock/forge-artifacts`


# op-deployer versioning and releases
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/reference/releases

Reference for where to find OP Deployer releases and how each OP Deployer version maps to a supported contract release.

## Latest Releases

The latest version of OP Deployer is always available at [releases](https://github.com/ethereum-optimism/optimism/releases?q=op-deployer\&expanded=true). You should search for `op-deployer` to
exclude other packages.

## Versioning

For all releases after `v0.0.11`, each minor version of OP Deployer will support a single release of the
governance-approved smart contracts. If you want to deploy an earlier version of the contracts (which may be
dangerous!), you should use an earlier version of OP Deployer. This setup allows our smart contract developers to make
breaking changes on `develop`, while still allowing new chains to be deployed and upgraded using production-ready smart
contracts.

If you deploy from an HTTPS or file [locator](/chain-operators/tools/op-deployer/reference/artifacts-locators), the deployment behavior will match the
contract's tag. For example, if version `v0.2.0` supports `v2.0.0` then the deployment will work as if you were
deploying `op-contracts/v2.0.0`. Typically, errors like `unknown selector: <some hex>` imply that you're using the wrong
version of OP Deployer for your contract artifacts. If this happens, we recommend trying different versions until you
get one that works. Note that this workflow is **not recommended** for production chains.

## Contributor Workflows

Step-by-step procedures for backporting fixes onto earlier OP Deployer versions and adding support for new contract
versions live in [Release Workflows](/chain-operators/tools/op-deployer/usage/release-workflows).


# Apply Command
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/usage/apply

Learn how to deploy your OP Chain based on the intent file.

Once you have [initialized](/chain-operators/tools/op-deployer/usage/init) your intent and state files, you can use the `apply` command to perform the
deployment.

## Usage

You can call the `apply` command like this:

```shell theme={null}
op-deployer apply \
  --workdir <directory containing the intent and state files> \
  <... additional arguments ...>
```

You will need to specify additional arguments depending on what you're trying to do. See below for a reference of each
supported CLI arg.

## CLI Arguments

### `--deployment-target`

**Default:** `live`

`--deployment-target` specifies where each chain should be deployed to. It can be one of the following values:

* `live`: Deploys to a live L1. Concretely, this means that OP Deployer will send transactions identified by
  `vm.broadcast` calls to L1. `--l1-rpc-url` and `--private-key` must be specified when using this target.
* `genesis`: Deploys to an L1 genesis file. This is useful for testing or local development purposes. You do not need to
  specify any additional arguments when using this target.
* `calldata`: Deploys to a calldata file. This is useful for generating inputs to multisig wallets for future execution.
* `noop`: Doesn't deploy anything. This is useful for performing a dry-run of the deployment process prior to another
  deployment target.

### `--l1-rpc-url`

Defines the RPC URL of the L1 chain to deploy to.

### `--private-key`

Defines the private key to use for signing transactions. This is only required for deployment targets that involve
sending live transactions. Note that ownership over each L2 is transferred to the proxy admin owner specified in the
intent after the deployment completes, so it's OK to use a hot key for this purpose.


# Bootstrap Commands
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/usage/bootstrap

Learn how to deploy global singletons and implementation contracts for new OP Stack deployments.

<Info>
  If you are joining an existing OP Stack deployment, you can skip to the [`init`](/chain-operators/tools/op-deployer/usage/init) and [`apply`](/chain-operators/tools/op-deployer/usage/apply) commands to create your L2 chain(s).
</Info>

Bootstrap commands are used to deploy global singletons and implementation contracts for new OP Stack deployments.
The deployed contracts can then be used with future invocations of `apply` so that new L2 chains can join that deployment.
Most users won't need to use these commands, since `op-deployer apply` will automatically use standard predeployed contracts for the L1/settlement-layer you are deploying on. However, you will need to use bootstrap commands if you're creating a new standalone deployment.

There are several bootstrap commands available, which you can view by running `op-deployer bootstrap --help`. We'll
focus on the most important ones, which should be run in the sequence listed below.

**It is safe to call these commands from a hot wallet.** None of the contracts deployed by these command are "ownable,"
so the deployment address has no further control over the system.

## Bootstrap Shared Contracts

```shell theme={null}
op-deployer bootstrap superchain \
  --l1-rpc-url="<rpc url>" \
  --private-key="<contract deployer private key>" \
  --outfile="./.deployer/bootstrap_superchain.json" \
  --superchain-proxy-admin-owner="<role address>" \
  --guardian="<role address>"
```

### CLI Arguments

#### `--superchain-proxy-admin-owner`, `--guardian`

In a dev environment, these can all be hot wallet EOAs. In a production environment, `--guardian` should be an HSM (hardware security module) protected hot wallet and `--superchain-proxy-admin-owner` should be a multisig cold-wallet (e.g. Gnosis Safe).

### Output

This command will deploy several contracts, and output a JSON like the one below:

```json theme={null}
{
  "proxyAdminAddress": "0x269b95a33f48a9055b82ce739b0c105a83edd64a",
  "superchainConfigImplAddress": "0x2f4c87818d67fc3c365ea10051b94f98893f3c64",
  "superchainConfigProxyAddress": "0xd0c74806fa114c0ec176c0bf2e1e84ff0a8f91a1"
}
```

## Bootstrap Implementations

```shell theme={null}
op-deployer bootstrap implementations \
  --l1-rpc-url="<rpc url>" \
  --outfile="./.deployer/bootstrap_implementations.json" \
  --private-key="<contract deployer private key>" \
  --superchain-config-proxy="<contract address output from bootstrap superchain>" \
  --superchain-proxy-admin="<contract address from bootstrap superchain>" \
  --challenger="<role address for the superchain's challenger>" \
  --upgrade-controller="<superchain-proxy-admin-owner used in bootstrap superchain>"
```

### Output

This command will deploy implementations, blueprints, and the OPCM. Deployments are (for the most part)
deterministic, so contracts will only be deployed once per chain as long as the implementation and constructor args
remain the same. This applies to the `op-deployer apply` pipeline - that is, if someone else ran `op-deployer bootstrap implementations`
at some point on a given L1 chain, then the `apply` pipeline will re-use those implementations.

The command will output a JSON like the one below:

```json theme={null}
{
  "opcmAddress": "0x82879934658738b6d5e8f781933ae7bbae05ba31",
  "opcmContractsContainerAddress": "0x1e8de1574a2e085b7a292c760d90cf982d3c1a11",
  "opcmGameTypeAdderAddress": "0xcab868d42d9088b86598a96d010db5819c19b847",
  "opcmDeployerAddress": "0xf8b6718b28fa36b430334e78adaf97174fed818c",
  "opcmUpgraderAddress": "0xa4d0a44890fafce541bdc4c1ca36fca1b5d22f56",
  "opcmInteropMigratorAddress": "0xf0fca53bb450dd2230c7eb58a39a5dbfc8492fb6",
  "opcmStandardValidatorAddress": "0x1364a02f64f03cd990f105058b8cc93a9a0ab2a1",
  "delayedWETHImplAddress": "0x570da3694c06a250aea4855b4adcd09505801f9a",
  "optimismPortalImplAddress": "0x1aa1d3fc9b39d7edd7ca69f54a35c66dcf1168f1",
  "ethLockboxImplAddress": "0xe6e51fa10d481002301534445612c61bae6b3258",
  "preimageOracleSingletonAddress": "0x1fb8cdfc6831fc866ed9c51af8817da5c287add3",
  "mipsSingletonAddress": "0x7a8456ba22df0cb303ae1c93d3cf68ea3a067006",
  "systemConfigImplAddress": "0x9f2b1fffd8a7aeef7aeeb002fd8477a4868e7e0a",
  "l1CrossDomainMessengerImplAddress": "0x085952eb0f0c3d1ca82061e20e0fe8203cdd630a",
  "l1ERC721BridgeImplAddress": "0xbafd2cae054ddf69af27517c6bea912de6b7eb8f",
  "l1StandardBridgeImplAddress": "0x6abaa7b42b9a947047c01f41b9bcb8684427bf24",
  "optimismMintableERC20FactoryImplAddress": "0xdd0b293b8789e9208481cee5a0c7e78f451d32bf",
  "disputeGameFactoryImplAddress": "0xe7ab0c07ee92aae31f213b23a132a155f5c2c7cc",
  "anchorStateRegistryImplAddress": "0xda4f46fad0e38d763c56da62c4bc1e9428624893",
  "superchainConfigImplAddress": "0xdaf60e3c5ef116810779719da88410cce847c2a4"
}
```


# Custom Deployments
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/usage/custom-deployments

Learn how to manage custom deployments with OP Deployer.

While OP Deployer was designed primarily for use with chains that are governed by Optimism, it also supports managing
custom deployments. This is particularly common for RaaS providers, whose customers often request deployments with
custom L1s (or L2s, in the case of L3s) or governance. This guide will walk you through the process of managing these
chains using OP Deployer.

<Warning>
  Chains deployed in this way are not subject to Optimism Governance. They may be running customized or unaudited
  code. Use at your own risk.
</Warning>

## Bootstrapping

The first step to deploying a custom OP Stack is to bootstrap it onto an L1. This process will:

* Deploy shared management contracts like `SuperchainConfig` and `SuperchainVersions`.
* Deploy contract implementations that will be shared among all OP Chains in this deployment.
* Set up ownership so that you can control the deployment.

You will use the [`bootstrap`](/chain-operators/tools/op-deployer/usage/bootstrap) family of commands on `op-deployer` to do this.

### Bootstrap Shared Contracts

Every OP Chain belongs to a logical deployment group. This group consists of a set of shared contracts that control the behavior
of a group of OP Chains. This includes:

* Pausing bridges
* Signaling which protocol versions are required and recommended

You can deploy a new set of shared contracts for each OP Chain, or you can deploy them once and share across multiple OP Chains.
The choice is up to the deployer. Note that you **cannot** share a set of shared contracts across multiple L1s.

To begin, bootstrap the shared contracts onto your chosen L1 with the following command:

```shell theme={null}
op-deployer bootstrap superchain \
  --l1-rpc-url="<rpc url>" \
  --private-key="<contract deployer private key>" \
  --artifacts-locator="<locator>" \
  --outfile="<path to outfile>" \
  --superchain-proxy-admin-owner="<role address>" \
  --guardian="<role address>"
```

This will output a JSON file containing the addresses of the relevant contracts. Keep track of this file, as you will
need it in subsequent steps.

We recommend the following these best practices when bootstrapping:

1. Use Gnosis SAFEs for ownership roles like `guardian` and `superchain-proxy-admin-owner`. The owner **must** be a
   smart contract to support future upgrades, so a SAFE is a sensible default.
2. Use a regular EOA as the deployer. It will not have any control over the deployment once the deployment completes.
3. Use a standard contracts tag (e.g. `tag://op-contracts/v2.0.0`). This will make upgrading easier.

### Bootstrapping Implementations

The smart contracts for an OP Chain are deployed using a factory that points to a set of predeployed implementations.
You must deploy the factory and the implementations every time you deploy to a new L1 and whenever new smart
contract versions are released. Implementations are deployed using `CREATE2`, so addresses may be reused if they
already exist on the L1.

<Warning>
  You may need to use different versions of OP Deployer depending on which contracts version you are deploying. See the
  [releases guide](/chain-operators/tools/op-deployer/reference/releases) for more information on picking the right release.
</Warning>

To deploy the implementations, use the following command:

```shell theme={null}
op-deployer bootstrap implementations \
  --artifacts-locator="<locator, should be the same as the one used in bootstrap superchain>" \
  --l1-rpc-url="<rpc url>" \
  --outfile="<path to outfile>" \
  --mips-version="2" \
  --private-key="<contract deployer private key>" \
  --superchain-config-proxy="<address output from bootstrap superchain>" \
  --upgrade-controller="<superchain-proxy-admin-owner used in bootstrap superchain>"
```

Similar to the `bootstrap superchain` command, this will output a JSON file containing the addresses of the relevant
contracts. Again, keep track of this file.

The most important address in the implementations file is the OPCM, or OP Contracts Manager. This contract is the
factory that will deploy all the OP Chains belonging to this deployment group. It is also responsible for upgrading between
different contracts versions. Please keep the following **very important** invariants in mind with the OPCM:

* There is a one-to-one mapping between each OPCM, and contracts version.
* Each OPCM is associated with **exactly one** deployment group. This means that you **must** deploy a new OPCM using the
  `bootstrap implementations` command for each new deployment group you manage.

## Deploying

After bootstrapping the contracts and implementations, you can deploy your L2 chains with the `apply` command. You
will need to specify a `configType` of `standard-overrides` and set the `opcmAddress` field in your intent to the
address of the OPCM above. **Make sure you call the right OPCM.** Failing to call the right OPCM might lead to
deploying incorrect contract versions, or associating your chain with the wrong deployment.

<Warning>
  Make sure that you use the same `l1ContractsLocator` and `l2ContractsLocator` as the ones used in the bootstrap
  commands. Otherwise, you may run into deployment errors.
</Warning>

See the following config for an example:

```toml theme={null}
configType = "standard-overrides"
l1ChainID = 11155420
opcmAddress = "0x..."
l1ContractsLocator = "tag://..." # must match the one used in bootstrap
l2ContractsLocator = "tag://..."

[[chains]]
# Chain configs...
```

Once `apply` completes successfully, you can use the `inspect` family of commands to download your chain's L2
genesis and rollup config files.

## Upgrading

<Warning>
  The `op-deployer upgrade` command supports upgrades up to `op-contracts/v5.0.0` only. It does **not** support
  upgrading from `op-contracts/v5.0.0` to `op-contracts/v6.0.0`. For upgrades beyond v5.0.0, use
  [superchain-ops](/chain-operators/tutorials/l1-contract-upgrades/superchain-ops-guide) or interact with the
  OPCM directly. See the [notice](/notices/archive/op-deployer-upgrade-deprecation) for details.
</Warning>


# Init Command
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/usage/init

Learn how to initialize intent and state files for your OP Stack deployment.

The `init` command is used to create a new intent and state file in the specified directory. This command is the
starting point of each new deployment.

## Usage

The `init` command is used like this:

```shell theme={null}
op-deployer init \
  --l1-chain-id <chain ID of your L1> \
  --l2-chain-ids <comma separated list of chain IDs for your L2s> \
  --outdir <directory to write the intent and state files> \
  --intent-type <standard/custom/standard-overrides>
```

You should then see the following files appear in your output directory:

```
outdir
├── intent.toml
└── state.json
```

The `intent.toml` file is where you specify the configuration for your deployment. The `state.json` file is where OP
Deployer will output the current state of the deployment after each stage of the deployment.

## Intent File

Your intent should look something like this:

```toml theme={null}
configType = "standard"
l1ChainID = 11155420
fundDevAccounts = false
useInterop = false
l1ContractsLocator = "tag://op-contracts/v1.8.0-rc.4"
l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"

[superchainRoles]
  proxyAdminOwner = "0xeAAA3fd0358F476c86C26AE77B7b89a069730570"
  guardian = "0xeAAA3fd0358F476c86C26AE77B7b89a069730570"

[[chains]]
  id = "0x0000000000000000000000000000000000000000000000000000000000002390"
  baseFeeVaultRecipient = "0x0000000000000000000000000000000000000000"
  l1FeeVaultRecipient = "0x0000000000000000000000000000000000000000"
  sequencerFeeVaultRecipient = "0x0000000000000000000000000000000000000000"
  operatorFeeVaultRecipient = "0x0000000000000000000000000000000000000000"
  eip1559DenominatorCanyon = 250
  eip1559Denominator = 50
  eip1559Elasticity = 6

  [chains.roles]
    l1ProxyAdminOwner = "0x0000000000000000000000000000000000000000"
    l2ProxyAdminOwner = "0x0000000000000000000000000000000000000000"
    systemConfigOwner = "0x0000000000000000000000000000000000000000"
    unsafeBlockSigner = "0x0000000000000000000000000000000000000000"
    batcher = "0x0000000000000000000000000000000000000000"
    proposer = "0x0000000000000000000000000000000000000000"
    challenger = "0x0000000000000000000000000000000000000000"
```

<Warning>
  Before you can use your intent file for a deployment, you will need to update all zero values to whatever is
  appropriate for your chain. For dev environments, it is ok to use all EOAs/hot-wallets.
</Warning>

## Production Setup

In production environments, you should use a more secure setup with cold-wallet multisigs (e.g. Gnosis Safes) for the following:

* `baseFeeVaultRecipient`
* `l1FeeVaultRecipient`
* `sequencerFeeVaultRecipient`
* `operatorFeeVaultRecipient`
* `l1ProxyAdminOwner`
* `l2ProxyAdminOwner`
* `systemConfigOwner`

HSMs (hardware security modules) are recommended for the following hot-wallets:

* `unsafeBlockSigner`
* `batcher`
* `proposer`
* `challenger`


# Release Workflows
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/usage/release-workflows

Learn how to backport fixes onto earlier OP Deployer versions and add support for new contract versions.

<Note>
  This page is for people developing OP Deployer itself. If you only need to pick the right OP Deployer release
  for your contract version, see the [releases reference](/chain-operators/tools/op-deployer/reference/releases).
</Note>

## Backport a Fix to an Earlier Version

From time to time, we may backport bugfixes from develop onto earlier versions of OP Deployer. The process for this is
as follows:

1. If one doesn't exist already, make a new branch for the version lineage you're patching (e.g. `v0.2.x`). This branch
   should be protected (not deletable) and should be based on the latest release of that lineage. The branch should be
   named as follows:
   `backports/op-deployer/<lineage, i.e. v0.2.0>`.
2. Open a PR with the backport against that branch. Be sure to reference the original commit in the backport.
3. Make and push a new tag on that lineage.

Example for backporting fix(es) from `develop` to create a new release `op-deployer/v0.2.1`:

```
git checkout -b backports/op-deployer/v0.2.0 op-deployer/v0.2.0
git push origin backports/op-deployer/v0.2.0
git checkout -b fixes/deployer-v0.2.0 backports/op-deployer/v0.2.0
git cherry-pick <commit-hash>
git push origin fixes/deployer-v0.2.0

1. open pr from fixes/deployer-v0.2.0 targeting backports/op-deployer/v0.2.0
2. merge the pr
3. push a new tag for op-deployer/v0.2.1 on backports/op-deployer/v0.2.0 branch (goreleaser will create the release)
```

## Add Support for a New Contract Version

Adding support for a new contract version is a multi-step process. Here's a high-level overview. For the sake of
simplicity we will assume you are adding support for a new `rc` release.

### Step 1: Add Support on Develop

First, you need to add support for the new contract version on the `develop` branch. This means ensuring that the
deployment pipeline supports whatever changes are required for the new version. Typically, this means passing in new
deployment variables, and responding to ABI changes in the Solidity scripts/OPCM.

### Step 2: Add the Published Artifacts

Run the following from the root of the monorepo:

```bash theme={null}
cd packages/contracts-bedrock
just clean
just build
bash scripts/ops/calculate-checksum.sh
# copy the outputted checksum
cd ../../op-deployer
just calculate-artifacts-hash <checksum>
```

This will calculate the checksum of your artifacts as well as the hash of the artifacts tarball. OP Deployer uses
these values to download and verify tagged contract locators.

Now, update `standard/standard.go` with these values so that the new artifacts tarball can be downloaded:

```go theme={null}
// Add a new const for your release

const ContractsVXTag = "op-contracts/vX.Y.Z"

var taggedReleases = map[string]TaggedRelease{
// Other releases...
ContractsVXTag: {
ArtifactsHash: common.HexToHash("<the artifacts hash>"),
ContentHash:   common.HexToHash("<the checksum>"),
},
}

// Update the L1/L2 versions accordingly
func IsSupportedL1Version(tag string) bool {
return tag == ContractsVXTag
}
```

### Step 3: Update the SR With the New Release

Add the new RC to the [standard versions](https://github.com/ethereum-optimism/superchain-registry/tree/main/validation/standard) in the superchain-registry.

### Step 4: Update the Validation Package

The SR is pulled into OP Deployer via the `validation` package. Update it by running the following command from the
root of the monorepo:

```shell theme={null}
go get -u github.com/ethereum-optimism/superchain-registry/validation@<SR commit SHA>
```

That should be it!


# Verify Command
Source: https://docs.optimism.io/chain-operators/tools/op-deployer/usage/verify

Learn how to verify deployed contract source code on block explorers.

Once you have deployed contracts via [`bootstrap`](/chain-operators/tools/op-deployer/usage/bootstrap) or [`apply`](/chain-operators/tools/op-deployer/usage/apply), you can use the `verify` command to verify the source code on block explorers like Etherscan or Blockscout. The command uses the `forge verify-contract` binary, which automatically handles constructor argument detection and source code verification.

## Usage

You can call the `verify` command like this:

```shell theme={null}
op-deployer verify \
  --l1-rpc-url <l1 rpc url> \
  --input-file <filepath to input .json or state.json file> \
  --verifier-api-key <your api key> \
  --artifacts-locator <l1 forge-artifacts locator> \
  --verifier etherscan
```

For Blockscout verification (uses default URLs for mainnet/sepolia, no API key required):

```shell theme={null}
op-deployer verify \
  --l1-rpc-url <l1 rpc url> \
  --input-file <filepath to input .json or state.json file> \
  --artifacts-locator <l1 forge-artifacts locator> \
  --verifier blockscout
```

For custom block explorer verification (Etherscan v2-compatible, API key may be required):

```shell theme={null}
op-deployer verify \
  --l1-rpc-url <l1 rpc url> \
  --input-file <filepath to input .json or state.json file> \
  --artifacts-locator <l1 forge-artifacts locator> \
  --verifier custom \
  --verifier-url <custom etherscan v2 compatible api url>
```

## CLI Arguments

### `--l1-rpc-url`

Defines the RPC URL of the L1 chain to deploy to (currently only supports mainnet and sepolia).

### `--input-file`

The full filepath to the input file. This can be either:

* A simple JSON file with contract name/address pairs (output from `bootstrap superchain|implementations`)
* A complete `state.json` file (output from `apply`)

The verifier automatically detects the file format and extracts all contracts. Unless the `--contract-name` flag is passed, all contracts in the input file will be verified.

Example:

```json theme={null}
{
  "opcmAddress": "0x437d303c20ea12e0edba02478127b12cbad54626",
  "opcmContractsContainerAddress": "0xf89d7ce62fc3a18354b37b045017d585f7e332ab",
  "opcmGameTypeAdderAddress": "0x9aa4b6c0575e978dbe6d6bc31b7e4403ea8bd81d",
  "opcmDeployerAddress": "0x535388c15294dc77a287430926aba5ba5fe6016a",
  "opcmUpgraderAddress": "0x68a7a93750eb56dd043f5baa41022306e6cd50fa",
  "delayedWETHImplAddress": "0x33ddc90167c923651e5aef8b14bc197f3e8e7b56",
  "optimismPortalImplAddress": "0x54b75cb6f44e36768912e070cd9cb995fc887e6c",
  "ethLockboxImplAddress": "0x05484deeb3067a5332960ca77a5f5603df878ced",
  "preimageOracleSingletonAddress": "0xfbcd4b365f97cb020208b5875ceaf6de76ec068b",
  "mipsSingletonAddress": "0xcc50288ad0d79278397785607ed675292dce37b1",
  "systemConfigImplAddress": "0xfb24aa6d99824b2c526768e97b23694aa3fe31d6",
  "l1CrossDomainMessengerImplAddress": "0x957c0bf84fe541efe46b020a6797fb1fb2eaa6ac",
  "l1ERC721BridgeImplAddress": "0x62786d16978436f5d85404735a28b9eb237e63d0",
  "l1StandardBridgeImplAddress": "0x6c9b377c00ec7e6755aec402cd1cfff34fa75728",
  "optimismMintableERC20FactoryImplAddress": "0x3842175f3af499c27593c772c0765f862b909b93",
  "disputeGameFactoryImplAddress": "0x70ed1725abb48e96be9f610811e33ed8a0fa97f9",
  "anchorStateRegistryImplAddress": "0xce2206af314e5ed99b48239559bdf8a47b7524d4",
  "superchainConfigImplAddress": "0x77008cdc99fb1cf559ac33ca3a67a4a2f04cc5ef"
}
```

### `--contract-name` (optional)

Specifies a single contract name, matching a contract key within the input file, to verify. If not provided, all contracts in the input file will be verified.

### `--artifacts-locator`

The locator to forge-artifacts containing the output of the `forge build` command (i.e. compiled bytecode and solidity source code). This can be a local path (with a `file://` prefix), remote URL (with a `http://` or `https://` prefix), or standard contracts tag (with a `tag://op-contracts/v` prefix).

### `--verifier`

The block explorer(s) to use for verification. Supports multiple verifiers separated by commas.

Options:

* `etherscan` (default): Uses Etherscan for mainnet/sepolia
* `blockscout`: Uses default Blockscout URLs for mainnet/sepolia
* `custom`: For custom Etherscan v2-compatible instances (requires `--verifier-url`)

Examples:

* Single verifier: `--verifier etherscan`
* Multiple verifiers: `--verifier etherscan,blockscout` (verifies on both)

### `--verifier-url`

The verifier API URL. Usage varies by verifier type:

* `etherscan`: Ignored (automatically determined from chain ID)
* `blockscout`: Optional (defaults to standard Blockscout URLs for mainnet/sepolia)
* `custom`: Required. Example: `https://etherscanv2.compat-api.example.com/api`

## Output

Output logs will be printed to the console and look something like the following. If the final results show `numFailed=0`, all contracts were verified successfully.

```sh theme={null}
INFO [03-05|15:56:55.900] Formatting etherscan verify request      name=superchainConfigProxyAddress            address=0x805fc6750ec23bdD58f7BBd6ce073649134C638A
INFO [03-05|15:56:55.900] Opening artifact                         path=Proxy.sol/Proxy.json           name=superchainConfigProxyAddress
INFO [03-05|15:56:55.905] contractName                             name=src/universal/Proxy.sol:Proxy
INFO [03-05|15:56:55.905] Extracting constructor args from initcode address=0x805fc6750ec23bdD58f7BBd6ce073649134C638A argSlots=1
INFO [03-05|15:56:56.087] Contract creation tx hash                txHash=0x71b377ccc11304afc32e1016c4828a34010a0d3d81701c7164fb19525ba4fbc4
INFO [03-05|15:56:56.494] Successfully extracted constructor args  address=0x805fc6750ec23bdD58f7BBd6ce073649134C638A
INFO [03-05|15:56:56.683] Verification request submitted           name=superchainConfigProxyAddress            address=0x805fc6750ec23bdD58f7BBd6ce073649134C638A
INFO [03-05|15:57:02.035] Verification complete                    name=superchainConfigProxyAddress            address=0x805fc6750ec23bdD58f7BBd6ce073649134C638A
INFO [03-05|15:57:07.971] --- COMPLETE ---
INFO [03-05|15:57:07.971] final results                            numVerified=2 numSkipped=1 numFailed=0
```

## Automatic Verification

You can automatically verify contracts after deployment by using the `--verify` flag with `apply` or `bootstrap` commands:

```shell theme={null}
op-deployer apply \
  --workdir ./.deployer \
  --l1-rpc-url <l1 rpc url> \
  --private-key <deployer private key> \
  --verify \
  --verifier-api-key <your api key>
```

This will verify all deployed contracts at the end of the deployment process.

### Multi-Verifier Deployment

You can verify on multiple block explorers simultaneously:

```shell theme={null}
op-deployer bootstrap superchain \
  --l1-rpc-url <l1 rpc url> \
  --private-key <deployer private key> \
  --outfile ./superchain.json \
  --superchain-proxy-admin-owner <owner address> \
  --guardian <guardian address> \
  --verify \
  --verifier etherscan,blockscout \
  --verifier-api-key <etherscan api key>
```

This will:

1. Deploy the shared contracts
2. Verify on Etherscan (using the API key)
3. Verify on Blockscout (no API key required)
4. Report combined results from both verifiers

## Supported Contract Bundles

The verify command now supports all contract bundles:

* **Shared** contracts (from `bootstrap superchain`)
* **Implementations** contracts (from `bootstrap implementations`)
* **OpChain** contracts (from `apply` - including all chain-specific contracts)

When using a `state.json` file from `apply`, the verifier automatically extracts and verifies contracts from all deployment stages.

## Block Explorer Support

The verification command supports both Etherscan and Blockscout block explorers through the forge binary, alongside any Etherscan v2 compatible APIs.


# OP Interop Filter
Source: https://docs.optimism.io/chain-operators/tools/op-interop-filter

Learn how op-interop-filter validates interop executing messages so the execution layer can reject invalid cross-chain transactions before they reach the sequencer.

<Info>
  OP Stack interop is in active development.
  op-interop-filter is the service chain operators will run to validate interop transactions for the execution layer, and the interfaces described here may continue to evolve as the rollout progresses.
</Info>

*op-interop-filter* is a lightweight service that validates interop executing messages so that an execution layer (EL) client — op-reth — can reject invalid cross-chain transactions before they reach the sequencer's transaction pool.

It is the service a chain operator runs to answer the `interop_checkAccessList` RPC that the EL calls on every interop transaction.

## What op-interop-filter does

An interop transaction carries an *access list* of references to initiating messages on other chains in the dependency set.
For the transaction to be valid, every referenced initiating message must exist on its source chain at the safety level the executing chain requires.

The EL cannot answer that question on its own.
It calls a configured interop verification endpoint over JSON-RPC (`interop_checkAccessList`) and lets that service decide whether the transaction is admissible.

op-interop-filter is one such service.
It connects to the L2 RPCs of every chain in the dependency set, ingests their logs into a local database, and answers `interop_checkAccessList` against that database.
When the answer is no — or when the filter has lost confidence in its own state — the EL rejects the transaction.

## How it fits into an interop deployment

op-interop-filter sits between an interop chain's EL and the other chains in its dependency set.

```mermaid theme={null}
graph LR
  classDef filter fill:#FFE
  classDef transparent fill:none,stroke:none

  EL["Execution layer<br/>(op-reth)"]
  Filter["op-interop-filter"]
  L2A["L2 RPC<br/>Chain A"]
  L2B["L2 RPC<br/>Chain B"]
  L2N["L2 RPC<br/>Chain N"]

  EL -- "interop_checkAccessList" --> Filter
  Filter --> L2A
  Filter --> L2B
  Filter --> L2N

  class Filter filter
```

The EL points at the filter through op-reth's `--rollup.interop-http` flag and calls the filter's `interop_checkAccessList` method to validate each interop transaction.

This is a different job from what [op-supernode](/op-stack/interop/supernode) does.
The supernode operates at the consensus layer (CL): it verifies that a block's cross-chain dependencies have been reproduced from L1, then promotes the block to *safe* through the chain's own CL.
op-interop-filter works at transaction-admission time instead: it is the separate service the execution layer consults to decide whether an interop transaction may enter the pool in the first place.
A chain operator running an interop chain runs both.

## Failsafe behavior

op-interop-filter has a *failsafe* that, while active, rejects every `interop_checkAccessList` request with `ErrFailsafeEnabled`.
The EL gates interop transactions on that check, so while failsafe is active no interop transactions are admitted.
Regular transactions that carry no interop access-list entries are unaffected and keep flowing normally.

Failsafe activates in one of two ways:

* **Automatically**, when any chain ingester reports an error — a reorg, a database conflict, data corruption, or an invalid executing message — or when the cross-validator reports an error.
* **Manually**, when an operator enables it over the admin RPC with `admin_setFailsafeEnabled`.

How failsafe clears depends on why it triggered:

* A **manual** failsafe clears when the operator calls `admin_setFailsafeEnabled` with `false`.
* A **reorg-triggered** failsafe clears automatically only when `--reorg-recovery-enabled` is set: the filter rewinds each affected chain's logs database to its finalized block and clears the error.
* Any failsafe that is neither manual nor auto-resolved — a reorg with `--reorg-recovery-enabled` off, a database conflict, data corruption, an invalid executing message, or a cross-validation failure — has no admin RPC to clear it. Recover by wiping the filter's data directory and restarting the service.

Disabling the manual override with `admin_setFailsafeEnabled` does not clear an error-triggered failsafe; the underlying error has to be resolved first.

## Configuration

op-interop-filter is configured via CLI flags or matching `OP_INTEROP_FILTER_*` environment variables.
The full flag set is defined in [`op-interop-filter/flags/flags.go`](https://github.com/ethereum-optimism/optimism/blob/develop/op-interop-filter/flags/flags.go).

### Required flags

| Flag                                 | Description                                                                                                                                                          |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--l2-rpcs`                          | L2 RPC endpoints to connect to. The filter queries the chain ID from each endpoint and matches it against a loaded rollup config.                                    |
| `--networks` *or* `--rollup-configs` | At least one is required. `--networks` loads rollup configs by name from the superchain registry; `--rollup-configs` loads custom JSON files for dev or test chains. |

### Key optional flags

| Flag                       | Default               | Description                                                                                        |
| -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------- |
| `--data-dir`               | (temporary directory) | Directory for the LogsDB. Use a persistent path in production so backfill state survives restarts. |
| `--backfill-duration`      | `24h`                 | How far back to backfill on startup.                                                               |
| `--message-expiry-window`  | `168h` (7 days)       | Messages older than this window are treated as expired.                                            |
| `--poll-interval`          | `2s`                  | How often to poll L2 RPCs for new blocks.                                                          |
| `--reorg-recovery-enabled` | off                   | If set, the filter automatically clears reorg-triggered failsafe by rewinding to finalized.        |
| `--admin.rpc.addr`         | (disabled)            | Bind address for the JWT-protected admin RPC. When set, `--admin.jwt-secret` is also required.     |

### Use-with-caution flags

Two flags are marked DANGEROUS in source and should only be used with a deliberate operational reason:

| Flag                                        | What it does                                                                                                                                                                      |
| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--dangerously-enable-passthrough`          | Lets every transaction through without interop filtering. Disables all executing-message validation.                                                                              |
| `--support-legacy-check-access-list-format` | Accepts `interop_checkAccessList` requests that omit the executing chain ID. Intended only for compatibility with legacy clients; access-list source-chain validation still runs. |

## RPC surface

op-interop-filter exposes two HTTP RPC endpoints, configured separately.

### Public RPC

Bound by `--rpc.addr` (default `0.0.0.0`) and `--rpc.port` (default `8545`).
Exposes the methods an EL or other consumer needs:

* `interop_checkAccessList` — validates an executing-message access list at a minimum safety level. This is the method the EL calls on every interop transaction.
* `interop_getBlockHashByNumber` — returns the latest ingested block hash for a chain, or the hash at a specific height.
* `admin_getFailsafeEnabled` — read-only check of whether failsafe is currently active.

### Admin RPC

Disabled by default.
Bound by `--admin.rpc.addr` and `--admin.rpc.port` (default `8546`), and protected by a JWT secret loaded from `--admin.jwt-secret`.

The admin RPC exposes the operator-only controls:

* `admin_setFailsafeEnabled` — manually enable or disable failsafe.
* `admin_getFailsafeEnabled` — the authenticated read of the same state available on the public RPC.

Admin RPC is intended for operator tooling and should not be exposed publicly.

## Where to go next

* Read the [interop explainer](/op-stack/interop/explainer) for how cross-chain messaging and executing-message access lists work at the protocol level.
* Read the [op-supernode page](/op-stack/interop/supernode) for the consensus-layer side of an interop deployment — block-safety promotion and the supernode topology.
* Read [interop reorg awareness](/op-stack/interop/reorg) for how reorgs interact with cross-chain message safety.
* For implementation detail, see the [op-interop-filter source](https://github.com/ethereum-optimism/optimism/tree/develop/op-interop-filter) in the monorepo.


# OP Txproxy
Source: https://docs.optimism.io/chain-operators/tools/op-txproxy

A passthrough proxy service that can apply additional constraints on transactions prior to reaching the sequencer.

A [passthrough proxy](https://github.com/ethereum-optimism/infra/tree/main/op-txproxy) for the execution engine endpoint. This proxy does not forward all RPC traffic and only exposes a specific set of methods. Operationally, the ingress router should only re-route requests for these specific methods.

<Info>
  [proxyd](./proxyd) as an ingress router supports the mapping of specific methods to unique backends.
</Info>

## Methods

### **eth\_sendRawTransactionConditional**

To safely expose this endpoint publicly, additional stateless constraints are applied. These constraints help scale validation rules horizontally and preemptively reject conditional transactions before they reach the sequencer.

Various metrics are emitted to guide necessary adjustments.

#### Runtime shutoff

This service can be configured with a flag or environment variable to reject conditional transactions without needing to interrupt the execution engine. This feature is useful for diagnosing issues.

`--sendRawTxConditional.enabled (default: true) ($OP_TXPROXY_SENDRAWTXCONDITIONAL_ENABLED)`

When disabled, requests will fail with the `-32003` (transaction rejected) json rpc error code with a message stating that the method is disabled.

#### Rate limits

Even though the op-geth implementation of this endpoint includes rate limits, it is instead applied here to terminate these requests early.

`--sendRawTxConditional.ratelimit (default: 5000) ($OP_TXPROXY_SENDRAWTXCONDITIONAL_RATELIMIT)`

#### Stateless validation

* Conditional cost is below the max
* Conditional values are valid (i.e min \< max)
* Transaction targets are only 4337 Entrypoint contracts

<Info>
  The motivating factor for this endpoint is to enable permissionless 4337 mempools, hence the restricted usage of this method to just [Entrypoint](https://github.com/eth-infinitism/account-abstraction/blob/develop/contracts/core/EntryPoint.sol) transactions.

  Please open up an issue if you'd like this restriction to be optional via configuration to broaden usage of this endpoint.
</Info>

When the request passes validation, it is passed through to the configured backend URL

`--sendRawTxConditional.backend ($OP_TXPROXY_SENDRAWTXCONDITIONAL_BACKENDS)`

<Info>
  Per the [specification](/op-stack/features/send-raw-transaction-conditional), conditional transactions are not gossiped between peers. Thus, if you use replicas in an active/passive sequencer setup, this request must be broadcasted to all replicas.

  [proxyd](./proxyd) as an egress router for this method supports this broadcasting functionality.
</Info>

## How it works

To start using `op-txproxy`, follow these steps:

<Steps>
  <Step title="Build the binary or pull the Docker image">
    1. Run the following command to build the binary

    ```bash theme={null}
    make build
    ```

    2. This will build and output the binary under `/bin/op-txproxy`.

    The image for this binary is also available as a [docker artifact](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-txproxy).
  </Step>

  <Step title="Configure">
    The binary accepts configuration through CLI flags, which also settable via environment variables. Either set the flags explicitly when starting the binary or set the environment variables of the host starting the proxy.

    See [methods](#methods) on the configuration options available for each method.
  </Step>

  <Step title="Start">
    start the service with the following command

    ```bash theme={null}
    op-txproxy // ... with flags if env variables are not set
    ```
  </Step>
</Steps>


# Run proxyd
Source: https://docs.optimism.io/chain-operators/tools/proxyd

Learn how to build, configure, and run proxyd, the OP Stack RPC request router and proxy.

`proxyd` is an important RPC request router and proxy used within the OP Stack infrastructure. It enables operators to efficiently route and manage RPC requests across multiple backend services, ensuring performance, fault tolerance, and security.

## Key features

* RPC method whitelisting
* Backend request routing
* Automatic retries for failed backend requests
* Consensus tracking (latest, safe, and finalized blocks)
* Request/response rewriting to enforce consensus
* Load balancing across backend services
* Caching of immutable responses
* Metrics for request latency, error rates, and backend health

## How it works

To start using `proxyd`, follow these steps:

<Steps>
  <Step title="**Build the binary**:">
    * Run the following command to build the `proxyd` binary:
      ```bash theme={null}
      make proxyd
      ```
    * This will build the `proxyd` binary. No additional dependencies are required.
  </Step>

  <Step title="**Configure `proxyd`**:">
    * Create a configuration file to define your proxy backends and routing rules.
    * Refer to [example.config.toml](https://github.com/ethereum-optimism/infra/blob/main/proxyd/example.config.toml) for a full list of options with commentary.
  </Step>

  <Step title="**Start the service**:">
    Once the configuration file is ready, start the `proxyd` service using the following command:

    ```bash theme={null}
    proxyd <path-to-config.toml>
    ```
  </Step>
</Steps>

## Consensus awareness

Version 4.0.0 and later include consensus awareness to minimize chain reorganizations.

Set `consensus_aware` to `true` in the configuration to enable:

* Polling backends for consensus data (latest block, safe block, peer count, etc.).
* Resolving consensus groups based on healthiest backends
* Enforcing consensus state across client requests

## Caching and metrics

### Cacheable methods

Certain immutable methods, such as `eth_chainId` and `eth_getBlockByHash`, can be cached using Redis to optimize performance.

### Metrics

Extensive metrics are available to monitor request latency, error rates, backend health, and more. These can be configured via `metrics.port` and `metrics.host` in the configuration file.

## Next steps

* Read about the [OP Stack chain architecture](/chain-operators/guides/management/network-architecture).
* Find out how you can support [snap sync](/chain-operators/guides/features/snap-sync).
  on your chain.
* Find out how you can utilize [blob space](/chain-operators/guides/features/blobs)
  to reduce the transaction fee cost on your chain.


# Generating absolute prestate and preimage files
Source: https://docs.optimism.io/chain-operators/tutorials/absolute-prestate

Generate, verify, and configure the kona-client absolute prestate for permissionless fault proofs.

# Overview

The absolute prestate is the on-chain commitment to a specific build of `kona-client`. The matching preimage (a gzipped binary) is what `op-challenger` runs at dispute time. This guide is the minimal reproducer.

<Info>
  As of [Upgrade 19](/notices/archive/upgrade-19), `CANNON_KONA` (game type `8`) is the respected game type for permissionless fault proofs. If your chain is not yet in the public Superchain Registry, follow [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate) instead.
</Info>

## Prerequisites

* [Docker](https://docs.docker.com/engine/install/) running
* [`just`](https://github.com/casey/just) installed

## Generate and verify the prestate

<Steps>
  <Step title="Check out the release tag">
    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism.git
    cd optimism
    git checkout kona-node/v<VERSION>
    ```
  </Step>

  <Step title="Build the prestate">
    ```bash theme={null}
    just reproducible-prestate-kona
    ```

    The build runs in Docker and writes artifacts to `rust/kona/prestate-artifacts-cannon/`.
  </Step>

  <Step title="Read and verify the hash">
    ```bash theme={null}
    jq -r .pre rust/kona/prestate-artifacts-cannon/prestate-proof.json
    ```

    Match the printed hash against the `cannon64-kona` entry for your release tag in [`standard-prestates.toml`](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml). A match confirms your build environment is honest.
  </Step>
</Steps>

## Configure op-challenger

Upload the hash-named file `rust/kona/prestate-artifacts-cannon/0x<HASH>.bin.gz` (produced by the build) to a location reachable by your `op-challenger` instances, then add the kona-specific env vars to your existing challenger config:

```bash theme={null}
OP_CHALLENGER_TRACE_TYPE=cannon-kona,permissioned
OP_CHALLENGER_CANNON_KONA_PRESTATES_URL=<HTTP_URL_PATH_TO_PRESTATES>
```

The challenger appends `/0x<hash>.bin.gz` to `*_PRESTATES_URL` to resolve the right binary per dispute. Your existing `OP_CHALLENGER_ROLLUP_CONFIG`, `OP_CHALLENGER_L2_GENESIS`, and `OP_CHALLENGER_GAME_FACTORY_ADDRESS` continue to apply unchanged.

## Next Steps

* [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate) — for chains not yet in the Superchain Registry.
* [Migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless).
* [Fault proofs explainer](/op-stack/fault-proofs/explainer).


# Adding attributes to the derivation function
Source: https://docs.optimism.io/chain-operators/tutorials/adding-derivation-attributes

Learn how to modify the derivation function for an OP Stack chain to track the amount of ETH being burned on L1.

<Info>
  OP Stack Hacks are explicitly things that you can do with the OP Stack that are *not* currently intended for production use.

  OP Stack Hacks are not for the faint of heart. You will not be able to receive significant developer support for OP Stack Hacks. Be prepared to get your hands dirty and to work without support.
</Info>

## Overview

In this tutorial, you'll modify the Bedrock Rollup. Although there are many ways to modify the OP Stack, you're going to spend this tutorial modifying the Derivation function. Specifically, you're going to update the Derivation function to track the amount of ETH being burned on L1! Who's gonna tell [ultrasound.money](http://ultrasound.money) that they should replace their backend with an OP Stack chain?

## Getting the idea

Let's quickly recap what you're about to do. The `op-node` is responsible for generating the Engine API payloads that trigger `op-geth` to produce blocks and transactions. The `op-node` already generates a "system transaction" for every L1 block that relays information about the current L1 state to the L2 chain. You're going to modify the `op-node` to add a new system transaction that reports the total burn amount (the base fee multiplied by the gas used) in each block.

Although it might sound like a lot, the whole process only involves deploying a single smart contract, adding one new file to `op-node`, and modifying one existing file inside `op-node`. It'll be painless. Let's go!

## Deploy the burn contract

You're going to use a smart contract on your Rollup to store the reports that the `op-node` makes about the L1 burn. Here's the code for your smart contract:

```solidity theme={null}
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

/**
 * @title L1Burn
 * @notice L1Burn keeps track of the total amount of ETH burned on L1.
 */
contract L1Burn {
    /**
     * @notice Total amount of ETH burned on L1.
     */
    uint256 public total;

    /**
     * @notice Mapping of block numbers to total burn.
     */
    mapping (uint64 => uint256) public reports;

    /**
     * @notice Allows the system address to submit a report.
     *
     * @param _blocknum L1 block number the report corresponds to.
     * @param _burn     Amount of ETH burned in the block.
     */
    function report(uint64 _blocknum, uint64 _burn) external {
        require(
            msg.sender == 0xDeaDDEaDDeAdDeAdDEAdDEaddeAddEAdDEAd0001,
            "L1Burn: reports can only be made from system address"
        );

        total += _burn;
        reports[_blocknum] = total;
    }

    /**
     * @notice Tallies up the total burn since a given block number.
     *
     * @param _blocknum L1 block number to tally from.
     *
     * @return Total amount of ETH burned since the given block number;
     */
    function tally(uint64 _blocknum) external view returns (uint256) {
        return total - reports[_blocknum];
    }
}
```

Deploy this smart contract to your L2 (using any tool you find convenient). Make a note of the address that the contract is deployed to because you'll need it in a minute. Simple!

## Add the burn transaction

Now you need to add logic to the `op-node` to automatically submit a burn report whenever an L1 block is produced. Since this transaction is very similar to the system transaction that reports other L1 block info (found in [l1\_block\_info.go](https://github.com/ethereum-optimism/optimism/blob/develop/op-node/rollup/derive/l1_block_info.go)), you'll use that transaction as a jumping-off point.

<Steps>
  <Step title="Navigate to the `op-node` package:">
    ```bash theme={null}
      cd ~/optimism/op-node
    ```
  </Step>

  <Step title="Inside of the folder `rollup/derive`, create a new file called `l1_burn_info.go`:">
    ```bash theme={null}
      touch rollup/derive/l1_burn_info.go
    ```
  </Step>

  <Step title="Paste the following into `l1_burn_info.go`, and make sure to replace `YOUR_BURN_CONTRACT_HERE` with the address of the `L1Burn` contract you just deployed.">
    ```go theme={null}
      package derive

      import (
          "bytes"
          "encoding/binary"
          "fmt"
          "math/big"

          "github.com/ethereum/go-ethereum/common"
          "github.com/ethereum/go-ethereum/core/types"
          "github.com/ethereum/go-ethereum/crypto"

          "github.com/ethereum-optimism/optimism/op-node/eth"
      )

      const (
          L1BurnFuncSignature = "report(uint64,uint64)"
          L1BurnArguments     = 2
          L1BurnLen           = 4 + 32*L1BurnArguments
      )

      var (
          L1BurnFuncBytes4 = crypto.Keccak256([]byte(L1BurnFuncSignature))[:4]
          L1BurnAddress    = common.HexToAddress("YOUR_BURN_CONTRACT_HERE")
      )

      type L1BurnInfo struct {
          Number uint64
          Burn   uint64
      }

      func (info *L1BurnInfo) MarshalBinary() ([]byte, error) {
          data := make([]byte, L1BurnLen)
          offset := 0
          copy(data[offset:4], L1BurnFuncBytes4)
          offset += 4
          binary.BigEndian.PutUint64(data[offset+24:offset+32], info.Number)
          offset += 32
          binary.BigEndian.PutUint64(data[offset+24:offset+32], info.Burn)
          return data, nil
      }

      func (info *L1BurnInfo) UnmarshalBinary(data []byte) error {
          if len(data) != L1InfoLen {
              return fmt.Errorf("data is unexpected length: %d", len(data))
          }
          var padding [24]byte
          offset := 4
          info.Number = binary.BigEndian.Uint64(data[offset+24 : offset+32])
          if !bytes.Equal(data[offset:offset+24], padding[:]) {
              return fmt.Errorf("l1 burn tx number exceeds uint64 bounds: %x", data[offset:offset+32])
          }
          offset += 32
          info.Burn = binary.BigEndian.Uint64(data[offset+24 : offset+32])
          if !bytes.Equal(data[offset:offset+24], padding[:]) {
              return fmt.Errorf("l1 burn tx burn exceeds uint64 bounds: %x", data[offset:offset+32])
          }
          return nil
      }

      func L1BurnDepositTxData(data []byte) (L1BurnInfo, error) {
          var info L1BurnInfo
          err := info.UnmarshalBinary(data)
          return info, err
      }

      func L1BurnDeposit(seqNumber uint64, block eth.BlockInfo, sysCfg eth.SystemConfig) (*types.DepositTx, error) {
          infoDat := L1BurnInfo{
              Number: block.NumberU64(),
              Burn:   block.BaseFee().Uint64() * block.GasUsed(),
          }
          data, err := infoDat.MarshalBinary()
          if err != nil {
              return nil, err
          }
          source := L1InfoDepositSource{
              L1BlockHash: block.Hash(),
              SeqNumber:   seqNumber,
          }
          return &types.DepositTx{
              SourceHash:          source.SourceHash(),
              From:                L1InfoDepositerAddress,
              To:                  &L1BurnAddress,
              Mint:                nil,
              Value:               big.NewInt(0),
              Gas:                 150_000_000,
              IsSystemTransaction: true,
              Data:                data,
          }, nil
      }

      func L1BurnDepositBytes(seqNumber uint64, l1Info eth.BlockInfo, sysCfg eth.SystemConfig) ([]byte, error) {
          dep, err := L1BurnDeposit(seqNumber, l1Info, sysCfg)
          if err != nil {
              return nil, fmt.Errorf("failed to create L1 burn tx: %w", err)
          }
          l1Tx := types.NewTx(dep)
          opaqueL1Tx, err := l1Tx.MarshalBinary()
          if err != nil {
              return nil, fmt.Errorf("failed to encode L1 burn tx: %w", err)
          }
          return opaqueL1Tx, nil
      }
    ```

    Feel free to take a look at this file if you're interested. It's relatively simple, mainly just defining a new transaction type and describing how the transaction should be encoded.
  </Step>
</Steps>

## Insert the burn transactions

Finally, you'll need to update `~/optimism/op-node/rollup/derive/attributes.go` to insert the new burn transaction into every block. You'll need to make the following changes:

<Steps>
  <Step title="Find these lines:">
    ```go theme={null}
      l1InfoTx, err := L1InfoDepositBytes(seqNumber, l1Info, sysConfig)
      if err != nil {
            return nil, NewCriticalError(fmt.Errorf("failed to create l1InfoTx: %w", err))
      }
    ```
  </Step>

  <Step title="After those lines, add this code fragment:">
    ```go theme={null}
      l1BurnTx, err := L1BurnDepositBytes(seqNumber, l1Info, sysConfig)
      if err != nil {
              return nil, NewCriticalError(fmt.Errorf("failed to create l1InfoTx: %w", err))
      }
    ```
  </Step>

  <Step title="Immediately following, change these lines:">
    ```go theme={null}
      txs := make([]hexutil.Bytes, 0, 1+len(depositTxs))
      txs = append(txs, l1InfoTx)
    ```

    to

    ```go theme={null}
    txs := make([]hexutil.Bytes, 0, 2+len(depositTxs))
    txs = append(txs, l1InfoTx)
    txs = append(txs, l1BurnTx)
    ```

    All you're doing here is creating a new burn transaction after every `l1InfoTx` and inserting it into every block.
  </Step>
</Steps>

## Rebuild your op-node

Before you can see this change take effect, you'll need to rebuild your `op-node`:

```bash theme={null}
cd ~/optimism/op-node
make op-node
```

Now start your `op-node` if it isn't running or restart your `op-node` if it's already running. You should see the change immediately — new blocks will contain two system transactions instead of just one!

## Checking the result

Query the `total` function of your contract, you should also start to see the total slowly increasing. Play around with the `tally` function to grab the amount of gas burned since a given L2 block. You could use this to implement a version of [ultrasound.money](http://ultrasound.money) that keeps track of things with an OP Stack as a backend.

One way to get the total is to run these commands:

```bash theme={null}
export ETH_RPC_URL=http://localhost:8545
cast call <YOUR_BURN_CONTRACT_HERE> "total()" | cast --from-wei
```

## Conclusion

With just a few tiny changes to the `op-node`, you were just able to implement a change to the OP Stack that allows you to keep track of the L1 ETH burn on L2. With a live Cannon Fault Proof System, you should not only be able to track the L1 burn on L2, you should be able to *prove* the burn to contracts back on L1. That's crazy!

The OP Stack is an extremely powerful platform that allows you to perform a large amount of computation trustlessly. It's a superpower for smart contracts. Tracking the L1 burn is just one of the many, many wild things you can do with the OP Stack. If you're looking for inspiration or you want to see what others are building on the OP Stack, check out the OP Stack Hacks page. Maybe you'll find a project you want to work on, or maybe you'll get the inspiration you need to build the next killer smart contract.


# Adding a precompile
Source: https://docs.optimism.io/chain-operators/tutorials/adding-precompiles

Learn how to run an EVM with a new precompile for OP Stack chain operations to speed up calculations that are not currently supported.

<Info>
  OP Stack Hacks are explicitly things that you can do with the OP Stack that are *not* currently intended for production use.

  OP Stack Hacks are not for the faint of heart. You will not be able to receive significant developer support for OP Stack Hacks. Be prepared to get your hands dirty and to work without support.
</Info>

One possible use of OP Stack is to run an EVM with a new precompile for operations to speed up calculations that are not currently supported. In this tutorial, you'll make a simple precompile that returns a constant value if it's called with four or less bytes, or an error if it is called with more than that.

To create a new precompile, the file to modify is [`op-geth/core/vm/contracts.go`](https://github.com/ethereum-optimism/op-geth/blob/optimism-history/core/vm/contracts.go).

<Steps>
  <Step title="Add to `PrecompiledContractsBerlin` on line 82 (or a later fork, if the list of precompiles changes again)">
    * add a structure named after your new precompile, and
    * use an address that is unlikely to ever clash with a standard precompile and avoids the [EIP-7587](https://eips.ethereum.org/EIPS/eip-7587) reserved range (0x1337, for example):

      ```go theme={null}
      common.BytesToAddress([]byte{0x13,0x37}): &retConstant{},
      ```
  </Step>

  <Step title="Add the lines for the precompile">
    ```go theme={null}
      type retConstant struct{}

      func (c *retConstant) RequiredGas(input []byte) uint64 {
          return uint64(1024)
      }

      var (
          errConstInvalidInputLength = errors.New("invalid input length")
      )

      func (c *retConstant) Run(input []byte) ([]byte, error) {
          // Only allow input up to four bytes (function signature)
          if len(input) > 4 {
              return nil, errConstInvalidInputLength
          }

          output := make([]byte, 6)
          for i := 0; i < 6; i++ {
              output[i] = byte(64+i)
          }
          return output, nil
      }
    ```
  </Step>

  <Step title="Stop `op-geth` and recompile:">
    ```bash theme={null}
      cd ~/op-geth
      make geth
    ```
  </Step>

  <Step title="Restart `op-geth`" />

  <Step title="Run these commands to see the result of calling the precompile successfully, and the result of an error:">
    ```bash theme={null}
      cast call 0x0000000000000000000000000000000000001337 "whatever()"
      cast call 0x0000000000000000000000000000000000001337 "whatever(string)" "fail"
    ```
  </Step>
</Steps>

## How does it work?

This is the precompile interface definition:

```go theme={null}
type PrecompiledContract interface {
	RequiredGas(input []byte) uint64  // RequiredPrice calculates the contract gas use
	Run(input []byte) ([]byte, error) // Run runs the precompiled contract
}
```

It means that for every precompile you need two functions:

* `RequiredGas` which returns the gas cost for the call. This function takes an array of bytes as input, and returns a single value, the gas cost.
* `Run` which runs the actual precompile. This function also takes an array of bytes, but it returns two values: the call's output (a byte array) and an error.

For every fork that changes the precompiles you have a [`map`](https://www.w3schools.com/go/go_maps.php) from addresses to the `PrecompiledContract` definitions:

```go theme={null}
// PrecompiledContractsBerlin contains the default set of pre-compiled Ethereum
// contracts used in the Berlin release.
var PrecompiledContractsBerlin = map[common.Address]PrecompiledContract{
  common.BytesToAddress([]byte{1}): &ecrecover{},
  .
  .
  .
  common.BytesToAddress([]byte{9}): &blake2F{},
  common.BytesToAddress([]byte{0x13,0x37}): &retConstant{},
}
```

The key of the map is an address. You create those from bytes using `common.BytesToAddress([]byte{<bytes to convert to address go here>})`.  In this case you have two bytes, `0x13` and `0x37`. Together you get the address `0x0…1337`.

The syntax for a precompiled contract interface is `&<variable name>{}`.

The next step is to define the precompiled contract itself.

```go theme={null}
type retConstant struct{}
```

First you create a structure for the precompile.

```go theme={null}
func (c *retConstant) RequiredGas(input []byte) uint64 {
    return uint64(1024)
}
```

Then you define a function as part of that structure. Here you just require a constant amount of gas, but of course the calculation can be a lot more sophisticated.

```go theme={null}
var (
    errConstInvalidInputLength = errors.New("invalid input length")
)

```

Next you define a variable for the error.

```go theme={null}
func (c *retConstant) Run(input []byte) ([]byte, error) {
```

This is the function that actually executes the precompile.

```go theme={null}

    // Only allow input up to four bytes (function signature)
    if len(input) > 4 {
        return nil, errConstInvalidInputLength
    }
```

Return an error if warranted. The reason this precompile allows up to four bytes of input is that any standard call (for example, using `cast`) is going to have at least four bytes for the function signature.

`return a, b` is the way we return two values from a function in Go. The normal output is `nil`, nothing, because we return an error.

```go theme={null}
    output := make([]byte, 6)
    for i := 0; i < 6; i++ {
        output[i] = byte(64+i)
    }
    return output, nil
}
```

Finally, you create the output buffer, fill it, and then return it.

## Conclusion

An OP Stack chain with additional precompiles can be useful, for example, to further reduce the computational effort required for cryptographic operations by moving them from interpreted EVM code to compiled Go code.


# Generating an op-program absolute prestate (archived)
Source: https://docs.optimism.io/chain-operators/tutorials/archive/op-program-prestate

Archived: legacy op-program prestate generation flow for chains resolving in-flight CANNON game type 1 disputes.

<Warning>
  **Archived.** As of [Upgrade 19](/notices/archive/upgrade-19), `CANNON_KONA` (game type `8`) is the respected game type for permissionless fault proofs and `op-program` (game type `0`, `CANNON`) is no longer supported for new fault proofs. This page is retained only for chains that still need to resolve in-flight `CANNON` games created before Upgrade 19.

  For all current work, see [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate) (kona-client) and, if your chain is not yet in the Superchain Registry, [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate).
</Warning>

## Overview

Permissionless fault proofs are a critical component of the OP Stack's security model. They allow anyone to challenge invalid state proposals, ensuring the correctness of L2 to L1 withdrawals without relying on trusted third parties. To enable this functionality, chain operators must generate and maintain the necessary absolute prestate and preimage files. The absolute prestate is a commitment to the initial state of the fault proof program, and the preimage is the serialized binary representation of this program state. These files are essential for the op-challenger tool to participate in dispute games when challenging invalid claims.

## Prerequisites

Before starting, ensure you have:

* [Docker](https://docs.docker.com/engine/install/) running

## Official prestate hashes for superchain-registry chains

The superchain-registry maintains official absolute prestate hashes for chains that are part of the registry. These prestates include the configurations of chains that were in the superchain-registry at the time the prestate was created.

<Info>
  Important: A prestate listed in the superchain-registry may not be suitable for your chain if:

  * Your chain was added to the registry after the prestate was created
  * The configuration for your chain has been updated since the prestate was created

  Before using a prestate from the registry, verify that it contains the latest configuration for your chain.

  When in doubt, generating your own prestate with your specific chain configuration is the safest approach.
</Info>

You can find the latest prestate tags in the [Superchain registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml).

## Generating the absolute prestate

<Steps>
  <Step title="Clone and checkout the tagged version">
    First, clone the Optimism monorepo and check out the appropriate [release tag](https://github.com/ethereum-optimism/optimism/tags) for op-program:

    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism.git
    cd optimism
    # Check out the op-program version that matches the in-flight CANNON game you
    # need to resolve. Use the version the game's original prestate was generated with.
    git checkout op-program/v1.6.1
    ```
  </Step>

  <Step title="(Optional) Provide chain configuration and genesis files">
    For chains that are not included in the superchain-registry, you'll need to provide the chain rollup configuration file and the L2 genesis file. Add the `rollup.json` and `l2-genesis.json` to the monorepo at `optimism/op-program/chainconfig/configs/<L2_CHAIN_ID>-rollup.json` and `optimism/op-program/chainconfig/configs/<L2_CHAIN_ID>-genesis-l2.json` respectively.
  </Step>

  <Step title="Generate the absolute prestate">
    Run the following command from the root of the monorepo:

    ```bash theme={null}
    make reproducible-prestate
    ```

    You should see the following logs at the end of the command’s output:

    ```log theme={null}
    -------------------- Production Prestates --------------------

    Cannon64 Absolute prestate hash: 
    0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8

    -------------------- Experimental Prestates --------------------

    CannonInterop Absolute prestate hash: 
    0x03fc3b4d091527d53f1ff369ea8ed65e5e17cc7fc98ebf75380238151cdc949c

    Cannon64Next Absolute prestate hash: 
    0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8
    ```

    The output will display production and experimental prestate hashes:

    * **Production prestates**: Contains the `Cannon64` prestate, which is the current production absolute prestate hash for the 64-bit version of Cannon. This is the hash you should use for permissionless fault proofs.
    * **Experimental prestates**: These contain prestates for versions that are in development and not yet ready for production use.
  </Step>

  <Step title="Prepare the preimage file">
    After generating the prestate, the preimage file will be located in `op-program/bin/prestate-mt64.bin.gz`. The exact name might vary based on the version. Rename this file to include the prestate hash:

    ```bash theme={null}
    cd op-program/bin
    mv prestate-mt64.bin.gz <cannon64-prestate-hash>.bin.gz
    ```

    Replace `<cannon64-prestate-hash>` with the actual `Cannon64` absolute prestate hash value from the output. This file needs to be uploaded to a location that's accessible by your op-challenger instances.
  </Step>
</Steps>

## Deploying and configuring with the absolute prestate

After generating the absolute prestate and preimage files, you'll need to:

<Steps>
  <Step title="Upload preimage file">
    Upload the preimage file to a location accessible by your op-challenger instances
  </Step>

  <Step title="Configure op-challenger">
    Configure the op-challenger to use the generated prestate. There are two ways to provide prestates:
  </Step>
</Steps>

<Steps>
  <Step title="Option 1: Using HTTP URL">
    If your prestate files are hosted on a web server, you can simply provide the URL to the directory containing those files:

    ```bash theme={null}
    docker run -d --name op-challenger \
     -e OP_CHALLENGER_TRACE_TYPE=permissioned,cannon \
     -e OP_CHALLENGER_PRESTATES_URL=<HTTP_URL_PATH_TO_PRESTATE> \
     -e OP_CHALLENGER_L1_ETH_RPC=<YOUR_L1_RPC_URL> \
     -e OP_CHALLENGER_GAME_FACTORY_ADDRESS=<YOUR_DISPUTE_GAME_FACTORY> \
     -e OP_CHALLENGER_PRIVATE_KEY=<YOUR_PRIVATE_KEY_OR_USE_WALLET_SIGNER> \
     -e OP_CHALLENGER_NETWORK=<YOUR_NETWORK> \
     -e OP_CHALLENGER_CANNON_ROLLUP_CONFIG=<PATH_TO_ROLLUP_CONFIG> \
     -e OP_CHALLENGER_CANNON_L2_GENESIS=<PATH_TO_GENESIS_CONFIG> \
     us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:latest
    ```

    <Info>
      When using an HTTP URL, no volume mount is required. The challenger will download the prestate files as needed.
    </Info>
  </Step>

  <Step title="Option 2: Using local files">
    If you have prestate files stored locally, you'll need to mount them as a volume and use the `file://` protocol:

    ```bash theme={null}
    docker run -d --name op-challenger \
      -e OP_CHALLENGER_TRACE_TYPE=permissioned,cannon \
      -e OP_CHALLENGER_PRESTATES_URL=file:///prestates \
      -e OP_CHALLENGER_L1_ETH_RPC=<YOUR_L1_RPC_URL> \
      -e OP_CHALLENGER_GAME_FACTORY_ADDRESS=<YOUR_DISPUTE_GAME_FACTORY> \
      -e OP_CHALLENGER_PRIVATE_KEY=<YOUR_PRIVATE_KEY_OR_USE_WALLET_SIGNER> \
      -e OP_CHALLENGER_NETWORK=<YOUR_NETWORK> \
      -e OP_CHALLENGER_CANNON_ROLLUP_CONFIG=<PATH_TO_ROLLUP_CONFIG> \
      -e OP_CHALLENGER_CANNON_L2_GENESIS=<PATH_TO_GENESIS_CONFIG> \
      -v /path/to/local/prestates:/prestates \
      us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:latest
    ```

    <Info>
      When using local files, ensure your prestate files are in the mounted directory and properly named with their hash (e.g., `0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8.bin.gz`).
    </Info>
  </Step>
</Steps>

<Info>
  * Ensure you're using the latest op-challenger version, see the [release page](https://github.com/ethereum-optimism/optimism/releases).
  * If your chain uses interoperability features, you'll need to add a `depsets.json` file to the `op-program/chainconfig/configs` directory.
  * This file contains dependency set configurations. Use the same dependency set definition your interop-enabled chain is already configured with.
</Info>

## Next steps

* Check out the [migrating to permissionless fault proofs guide](/chain-operators/tutorials/migrating-permissionless).
* Read the [Fault proofs explainer](/op-stack/fault-proofs/explainer).


# L2 Rollup Code Examples
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/code-setup

Complete working code examples for the Create L2 Rollup tutorial

This page contains complete working code examples for the Create L2 Rollup tutorial. You can find all the code and configuration files in the [create-l2-rollup-example directory](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/).

<Info>
  For the complete working implementation, visit the [Create L2 Rollup code on GitHub](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/).
</Info>

## Quick Start

```bash theme={null}
# Copy and configure environment
cp .example.env .env
# Edit .env with your values

# Run the automated setup
make init    # Download tools
make setup   # Deploy and configure
make up      # Start services
```

## Files

* `.example.env` - Environment configuration template
* `docker-compose.yml` - Service orchestration
* `Makefile` - Automation commands
* `scripts/` - Setup and utility scripts
* `README.md` - Detailed documentation

## About This Code

This implementation provides:

* Automated deployment of OP Stack L2 contracts
* Complete Docker-based service orchestration
* Working examples of all OP Stack components
* Production-ready configuration patterns

For detailed setup instructions, see the [Create L2 Rollup tutorial](/chain-operators/tutorials/create-l2-rollup).


# Creating your own L2 rollup testnet
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/index

Learn how to deploy and orchestrate all OP Stack components for a complete testnet deployment.

<Info>
  **Learn the OP Stack — stop 5 of 13.**
  You've covered the foundations: what the stack is, how it differs from
  Ethereum, and which components make it up. In this first project you
  deploy a rollup testnet with op-deployer and start each component
  yourself. Work through every part of the series, then continue to
  [Transaction flow](/op-stack/transactions/transaction-flow).
</Info>

Welcome to the complete guide for deploying your own OP Stack L2 rollup testnet. This multi-part tutorial will walk you through each component step-by-step, from initial setup to a fully functioning rollup.

<Info>
  This tutorial requires **intermediate-level experience working with EVM chains**.
  You should be comfortable with concepts like smart contracts, private keys, RPC endpoints, gas fees, and command-line operations.
  Basic familiarity with Docker is also recommended.
</Info>

## What you'll build

By the end of this tutorial, you'll have a complete OP Stack testnet with:

* **L1 Smart Contracts** deployed on Sepolia testnet
* **Execution Client** (op-reth) processing transactions
* **Consensus Client** (op-node) managing rollup consensus
* **Batcher** (op-batcher) publishing transaction data to L1
* **Proposer** (op-proposer) submitting state root proposals
* **Challenger** (op-challenger) monitoring for disputes

## Before you start

Set up the following before you pick a setup path below. Both the automated and manual paths need these dependencies and resources.

### Software dependencies

| Dependency                                                    | Version                              | Version check command |
| ------------------------------------------------------------- | ------------------------------------ | --------------------- |
| [git](https://git-scm.com/)                                   | `^2`                                 | `git --version`       |
| [go](https://go.dev/)                                         | `^1.26`                              | `go version`          |
| [rust](https://rustup.rs/) (source builds only)               | pinned by `rust/rust-toolchain.toml` | `rustc --version`     |
| [just](https://github.com/casey/just) (source builds only)    | `^1`                                 | `just --version`      |
| [zip](https://infozip.sourceforge.net/) (source builds only)  | `^3`                                 | `zip --version`       |
| [node](https://nodejs.org/en/)                                | `^20`                                | `node --version`      |
| [pnpm](https://pnpm.io/installation)                          | `^8`                                 | `pnpm --version`      |
| [foundry](https://github.com/foundry-rs/foundry#installation) | `^0.2.0`                             | `forge --version`     |
| [make](https://linux.die.net/man/1/make)                      | `^3`                                 | `make --version`      |
| [jq](https://github.com/jqlang/jq)                            | `^1.6`                               | `jq --version`        |
| [direnv](https://direnv.net)                                  | `^2`                                 | `direnv --version`    |
| [Docker](https://docs.docker.com/get-docker/)                 | `^24`                                | `docker --version`    |

### Notes on specific dependencies

<Info>
  Expand each dependency below for details
</Info>

<Expandable title="node">
  We recommend using the latest LTS version of Node.js (currently v20).\
  [`nvm`](https://github.com/nvm-sh/nvm) is a useful tool that can help you manage multiple versions of Node.js on your machine.\
  You may experience unexpected errors on older versions of Node.js.
</Expandable>

<Expandable title="foundry">
  We will use cast to generate wallet addresses in this guide.
</Expandable>

<Expandable title="direnv">
  Parts of this tutorial use [`direnv`](https://direnv.net) as a way of loading environment variables from `.envrc` files into your shell.\
  This means you won't have to manually export environment variables every time you want to use them.\
  `direnv` only ever has access to files that you explicitly allow it to see.

  After [installing `direnv`](https://direnv.net/docs/installation.html), you will need to **make sure that [`direnv` is hooked into your shell](https://direnv.net/docs/hook.html)**.\
  Make sure you've followed [the guide on the `direnv` website](https://direnv.net/docs/hook.html), then **close your terminal and reopen it** so that the changes take effect (or `source` your config file if you know how to do that).

  <Info>
    Make sure that you have correctly hooked `direnv` into your shell by modifying your shell configuration file (like `~/.bashrc` or `~/.zshrc`).\
    If you haven't edited a config file then you probably haven't configured `direnv` properly (and things might not work later).
  </Info>
</Expandable>

<Expandable title="Docker">
  Docker is used extensively in this tutorial for running various OP Stack components.\
  Make sure you have both Docker and Docker Compose installed and running on your system.\
  On Linux, you may need to [configure Docker to run without sudo](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user).

  <Info>
    If you're using Docker Desktop, ensure it's running before starting the tutorial.\
    You can verify your installation with:

    ```bash theme={null}
    docker run hello-world
    ```
  </Info>
</Expandable>

### Get access to a sepolia node

Since you're deploying your OP Stack chain to Sepolia, you'll need to have access to a Sepolia node.
You can either use a node provider like [Alchemy](https://www.alchemy.com/) (easier) or run your own Sepolia node (harder).

### Required resources

* **Sepolia ETH** - You'll need about 2-3 ETH:
  * Start with [Superchain Faucet](https://console.optimism.io/faucet) (gives 0.05 ETH)
  * Get more from:
    * [Alchemy Faucet](https://sepoliafaucet.com/)
    * [Infura Faucet](https://www.infura.io/faucet/sepolia)
    * [Paradigm Faucet](https://faucet.paradigm.xyz/)

* **L1 RPC URL** - An RPC endpoint to connect to the Sepolia network. You can get this from node providers like [Alchemy](https://www.alchemy.com/), [Infura](https://www.infura.io/). This is required so `op-deployer` and other services can read from and send transactions to L1.

<Info>
  **Testnet Only**: This guide is for **testnet deployment only**.
</Info>

## Choose your path

With your dependencies and resources in place, pick the path that fits how you want to work:

* **[Automated setup](#automated-setup)** — the fastest way to a running rollup. Uses the complete working implementation in this repository and handles all configuration and deployment for you.
* **[Manual setup](#manual-setup)** — walks through each component step-by-step. Choose this if you want to understand each component in detail or need custom configurations.

## Automated setup

If you want to get started quickly, you can use the complete working implementation provided in this repository. This automated setup handles all the configuration and deployment steps for you.

<Info>
  **Complete working example**

  A complete, working implementation is available in the [`create-l2-rollup-example/`](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/) directory. This includes all necessary scripts, Docker Compose configuration, and example environment files.
</Info>

### Automated setup steps

1. **Clone and navigate to the code directory:**
   ```bash theme={null}
   git clone https://github.com/ethereum-optimism/optimism.git
   cd optimism/docs/public-docs/create-l2-rollup-example
   ```

2. **Configure your environment:**
   ```bash theme={null}
   cp .example.env .env
   # Edit .env with your L1_RPC_URL, PRIVATE_KEY, and other settings
   ```

3. **Run the automated setup:**
   ```bash theme={null}
   make init    # Download op-deployer
   make setup   # Deploy contracts and generate configs
   make up      # Start all services
   make test-l1 # Verify L1 connectivity
   make test-l2 # Verify L2 functionality
   ```

4. **Monitor your rollup:**
   ```bash theme={null}
   make logs     # View all service logs
   make status   # Check service health
   ```

The automated setup uses the standard OP Stack environment variable conventions (prefixed with `OP_*`) and handles all the complex configuration automatically.

## Manual setup

If you prefer to understand each component in detail or need custom configurations, follow the step-by-step guide below. Each step builds on the previous one, so complete them in order for the best experience.

### Directory structure

To keep your rollup deployment organized, we'll create a dedicated directory structure. All components will be set up within this structure:

```bash theme={null}
rollup/
├── deployer/        # op-deployer files and contracts
├── sequencer/  # op-reth and op-node
├── batcher/    # op-batcher configuration
├── proposer/   # op-proposer setup
└── challenger/ # op-challenger files
```

Each component's documentation will show you how the directory structure evolves as you add files and configurations.

<Info>
  Throughout this tutorial, all file paths will be relative to this `rollup` directory structure. Make sure to adjust any commands if you use different directory names.
</Info>

### Manual setup steps

The manual path is organized into sequential steps that build upon each other:

<Steps>
  <Step title="Spin up op-deployer">
    Install op-deployer, deploy L1 contracts, and prepare your environment

    [Go to op-deployer setup →](/chain-operators/tutorials/create-l2-rollup/op-deployer-setup)
  </Step>

  <Step title="Spin up sequencer">
    Set up and run op-reth and op-node (the execution and consensus layers)

    [Go to sequencer setup →](/chain-operators/tutorials/create-l2-rollup/op-reth-setup)
  </Step>

  <Step title="Spin up batcher">
    Configure and start op-batcher for L1 data publishing

    [Go to batcher setup →](/chain-operators/tutorials/create-l2-rollup/op-batcher-setup)
  </Step>

  <Step title="Spin up proposer">
    Set up op-proposer for state root submissions

    [Go to proposer setup →](/chain-operators/tutorials/create-l2-rollup/op-proposer-setup)
  </Step>

  <Step title="Spin up challenger">
    Configure op-challenger for dispute resolution monitoring

    [Go to challenger setup →](/chain-operators/tutorials/create-l2-rollup/op-challenger-setup)
  </Step>
</Steps>

<Card title="Spin up op-deployer" href="/chain-operators/tutorials/create-l2-rollup/op-deployer-setup">
  Already have your dependencies? Get started and spin up op-deployer
</Card>

***

## Need help?

* **Questions or issues**: Ask questions or report bugs and docs problems on the [Optimism monorepo issue tracker](https://github.com/ethereum-optimism/optimism/issues)
* **Code examples**: Browse the [complete working example](/chain-operators/tutorials/create-l2-rollup/code-setup) that accompanies this tutorial


# Spin up batcher
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-batcher-setup

Learn how to set up and configure an OP Stack batcher to submit L2 transaction batches to L1.

After you have spun up your sequencer, you need to configure a batcher to submit L2 transaction batches to L1.

<Info>
  **Step 3 of 5**: This tutorial is designed to be followed step-by-step. Each step builds on the [previous one](/chain-operators/tutorials/create-l2-rollup/op-reth-setup).
</Info>

<Info>
  **Automated Setup Available**

  For a complete working setup with all components, check out the [automated approach](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/) in the code directory.
</Info>

## Understanding the batcher's role

The batcher (`op-batcher`) serves as a crucial component that bridges your L2 chain data to L1. Its primary responsibilities include:

* **Batch submission**: Collecting L2 transactions and submitting them as batches to L1
* **Data availability**: Ensuring L2 transaction data is available on L1 for verification
* **Cost optimization**: Compressing and efficiently packing transaction data to minimize L1 costs
* **Channel management**: Managing data channels for optimal batch submission timing

The batcher reads transaction data from your sequencer and submits compressed batches to the `BatchInbox` contract on L1.

## Prerequisites

Before setting up your batcher, ensure you have:

**Running infrastructure:**

* An operational sequencer node
* Access to a L1 RPC endpoint

**Network information:**

* Your L2 chain ID and network configuration
* L1 network details (chain ID, RPC endpoints)
* `BatchInbox` contract address from your deployment

For setting up the batcher, we recommend using Docker as it provides a consistent and isolated environment. Building from source is also available for more advanced users.

<Tabs>
  <Tab title="Use docker">
    If you prefer containerized deployment, you can use the official Docker images and do the following:

    <Steps>
      <Step title="Set up directory structure and copy configuration files">
        ```bash theme={null}
        # Create your batcher directory inside rollup
        cd ../    # Go back to rollup directory if you're in sequencer
        mkdir batcher
        cd batcher

        # Copy configuration files from deployer
        cp ../deployer/.deployer/state.json .

        # Extract the BatchInbox address
        BATCH_INBOX_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].systemConfigProxyAddress')
        echo "BatchInbox Address: $BATCH_INBOX_ADDRESS"
        ```
      </Step>

      <Step title="Create environment variables file">
        <Info>
          **OP Stack Standard Variables**

          The batcher uses OP Stack standard environment variables following the OP Stack conventions. These are prefixed with `OP_BATCHER_` for batcher-specific settings.
        </Info>

        ```bash theme={null}
        # Create .env file with your actual values
        cat > .env << 'EOF'
        # L1 Configuration - Replace with your actual RPC URLs
        OP_BATCHER_L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY
        # Private key - Replace with your actual private key
        OP_BATCHER_PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY

        # L2 Configuration - Should match your sequencer setup
        OP_BATCHER_L2_ETH_RPC=http://op-reth:8545
        OP_BATCHER_ROLLUP_RPC=http://op-node:8547

        # Contract addresses - Extract from your op-deployer output
        OP_BATCHER_BATCH_INBOX_ADDR=YOUR_ACTUAL_BATCH_INBOX_ADDRESS

        # Batcher configuration
        OP_BATCHER_POLL_INTERVAL=1s
        OP_BATCHER_SUB_SAFETY_MARGIN=6
        OP_BATCHER_NUM_CONFIRMATIONS=1
        OP_BATCHER_SAFE_ABORT_NONCE_TOO_LOW_COUNT=3
        OP_BATCHER_MAX_CHANNEL_DURATION=1
        OP_BATCHER_DATA_AVAILABILITY_TYPE=calldata

        # RPC configuration
        OP_BATCHER_RPC_PORT=8548
        EOF
        ```

        **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values.
      </Step>

      <Step title="Create a docker-compose.yml file">
        <Info>
          This configuration assumes your sequencer is running in a Docker container named `sequencer-node` on the same `op-stack` network.
          Make sure your sequencer is running before starting the batcher.
        </Info>

        ```yaml theme={null}

        services:
          op-batcher:
            image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-batcher:v1.16.11
            volumes:
              - .:/workspace
            working_dir: /workspace
            ports:
              - "8548:8548"
            env_file:
              - .env
            networks:
              - sequencer-node_default
            command: >
              op-batcher
              --rpc.addr=0.0.0.0
              --rpc.enable-admin
              --resubmission-timeout=30s
              --log.level=info
              --log.format=json
            restart: unless-stopped

        networks:
          sequencer-node_default:
            external: false
        ```
      </Step>

      <Step title="Start the batcher service">
        ```bash theme={null}
        # Make sure your sequencer network exists
        # Start the batcher
        docker-compose up -d

        # View logs
        docker-compose logs -f op-batcher
        ```
      </Step>

      <Step title="Verify batcher is running">
        ```bash theme={null}
        # Check container status
        docker-compose ps
        ```
      </Step>

      <Step title="Final directory structure">
        ```bash theme={null}
        rollup/
        ├── deployer/            # From previous step
        │   └── .deployer/      # Contains genesis.json and rollup.json
        ├── sequencer/          # From previous step
        └── batcher/           # You are here
            ├── state.json     # Copied from deployer
            ├── .env           # Environment variables
            └── docker-compose.yml # Docker configuration
        ```
      </Step>
    </Steps>

    Your batcher is now operational and will continuously submit L2 transaction batches to L1!
  </Tab>

  <Tab title="Build from source">
    To ensure you're using the latest compatible versions of OP Stack components, always check the official [releases page](https://github.com/ethereum-optimism/optimism/releases).

    Look for the latest `op-batcher/v*` release that's compatible with your sequencer setup.

    <Info>
      This guide uses `op-batcher/v1.16.11`, the latest release at the time of writing, alongside op-node/v1.19.3 and op-reth/v2.4.0 from the sequencer setup.
      Always check the [release notes](https://github.com/ethereum-optimism/optimism/releases) for compatibility information.
    </Info>

    <Steps>
      <Step title="Clone and build op-batcher">
        ```bash theme={null}
        # If you don't already have the optimism repository from the sequencer setup
        git clone https://github.com/ethereum-optimism/optimism.git
        cd optimism

        # Checkout the latest release tag
        git checkout op-batcher/v1.16.11

        # Generate the embedded superchain config bundle (initializes the
        # superchain-registry submodule; op-batcher embeds this file at compile time)
        just build-superchain-go

        # Build op-batcher
        cd op-batcher
        just

        # Binary will be available at ./bin/op-batcher
        ```
      </Step>

      <Step title="Verify installation">
        Run this command to verify the installation:

        ```bash theme={null}
        ./bin/op-batcher --version
        ```
      </Step>

      <Step title="Configuration setup">
        <Info>
          For advanced configuration options and fine-tuning your batcher, including:

          * Batch submission policies
          * Channel duration settings
          * Data availability types (blobs vs calldata)
          * Transaction throttling
          * Network timeouts

          Check out the [Batcher configuration reference](/chain-operators/reference/batcher-configuration).
          This will help you optimize your batcher's performance and cost-efficiency.
        </Info>

        <Steps>
          <Step title="Organize your workspace">
            Create your batcher working directory:

            ```bash theme={null}
            # Create batcher directory inside rollup
            cd ../    # Go back to rollup directory
            mkdir batcher
            cd batcher

            # Create scripts directory
            mkdir scripts
            ```

            Your final directory structure should look like:

            ```bash theme={null}
            rollup/
            ├── deployer/              # From previous step
            │   └── .deployer/        # Contains state.json
            ├── optimism/             # Contains op-batcher binary
            ├── sequencer/           # From previous step
            └── batcher/            # You are here
                ├── state.json      # Copied from deployer
                ├── .env           # Environment variables
                └── scripts/       # Startup scripts
              └── start-batcher.sh
            ```
          </Step>

          <Step title="Extract BatchInbox address">
            Extract the `BatchInbox` contract address from your op-deployer output:

            ```bash theme={null}
            # Make sure you're in the rollup/batcher directory
            cd rollup/batcher

            # Copy the deployment state file from deployer
            cp ../deployer/.deployer/state.json .

            # Extract the BatchInbox address
            BATCH_INBOX_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].systemConfigProxyAddress')
            echo "BatchInbox Address: $BATCH_INBOX_ADDRESS"
            ```

            <Info>
              The batcher submits transaction batches to the `BatchInbox` contract on L1. This contract is responsible for accepting and storing L2 transaction data.
            </Info>
          </Step>

          <Step title="Set up environment variables">
            Create your `.env` file with the actual values:

            ```bash theme={null}
            # Create .env file with your actual values
            # L1 Configuration - Replace with your actual RPC URL
            L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY

            # L2 Configuration - Should match your sequencer setup
            L2_RPC_URL=http://localhost:8545
            ROLLUP_RPC_URL=http://localhost:8547

            # Contract addresses - Extract from your op-deployer output
            BATCH_INBOX_ADDRESS=YOUR_ACTUAL_BATCH_INBOX_ADDRESS

            # Private key - Replace with your actual private key
            BATCHER_PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY

            # Batcher configuration
            POLL_INTERVAL=1s
            SUB_SAFETY_MARGIN=6
            NUM_CONFIRMATIONS=1
            SAFE_ABORT_NONCE_TOO_LOW_COUNT=3
            RESUBMISSION_TIMEOUT=30s
            MAX_CHANNEL_DURATION=25

            # RPC configuration
            BATCHER_RPC_PORT=8548
            ```

            **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values!
          </Step>

          <Step title="Get your private key">
            Get a private key from your wallet that will be used for submitting batches to L1. This account needs sufficient ETH to pay for L1 gas costs.

            <Info>
              The batcher account needs to be funded with ETH on L1 to pay for batch submission transactions. Monitor this account's balance regularly as it will consume ETH for each batch submission.
            </Info>
          </Step>
        </Steps>

        ### Batcher configuration

        Create `scripts/start-batcher.sh` in the same directory:

        ```bash theme={null}
        #!/bin/bash

        source .env

        # Path to the op-batcher binary we built
        ../../optimism/op-batcher/bin/op-batcher \
          --l2-eth-rpc=$L2_RPC_URL \
          --rollup-rpc=$ROLLUP_RPC_URL \
          --poll-interval=$POLL_INTERVAL \
          --sub-safety-margin=$SUB_SAFETY_MARGIN \
          --num-confirmations=$NUM_CONFIRMATIONS \
          --safe-abort-nonce-too-low-count=$SAFE_ABORT_NONCE_TOO_LOW_COUNT \
          --resubmission-timeout=$RESUBMISSION_TIMEOUT \
          --rpc.addr=0.0.0.0 \
          --rpc.port=$BATCHER_RPC_PORT \
          --rpc.enable-admin \
          --max-channel-duration=$MAX_CHANNEL_DURATION \
          --l1-eth-rpc=$L1_RPC_URL \
          --private-key=$BATCHER_PRIVATE_KEY \
          --batch-type=1 \
          --data-availability-type=blobs \
          --log.level=info
        ```

        ### Batcher parameters explained

        * **`--poll-interval`**: How frequently the batcher checks for new L2 blocks to batch
        * **`--sub-safety-margin`**: Number of confirmations to wait before considering L1 transactions safe
        * **`--max-channel-duration`**: Maximum time (in L1 blocks) to keep a channel open
        * **`--batch-type`**: Type of batch encoding (1 for span batches, 0 for singular batches)
        * **`--data-availability-type`**: Whether to use blobs or calldata for data availability

        ### Starting the batcher

        ### Start the batcher

        ```bash theme={null}
        # Make the script executable
        chmod +x scripts/start-batcher.sh

        # Start the batcher
        ./scripts/start-batcher.sh
        ```

        <Info>
          For detailed cost analysis and optimization strategies, refer to the [Transaction fees documentation](/op-stack/transactions/fees).
        </Info>

        Your batcher is now operational and will continuously submit L2 transaction batches to L1!
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Info>
  **Understanding common startup messages**

  When starting your batcher, you might see various log messages:

  * `Added L2 block to local state`: Normal operation, shows the batcher processing blocks
  * `SetMaxDASize RPC method unavailable`: Expected if the execution client version used doesn't support this method.
  * `context canceled` errors during shutdown: Normal cleanup messages
  * `Failed to query L1 tip`: Can occur during graceful shutdowns

  Most of these messages are part of normal operation. For detailed explanations of configuration options and troubleshooting, see the [Batcher configuration reference](/chain-operators/reference/batcher-configuration).
</Info>

## What's Next?

Excellent! Your batcher is publishing transaction data to L1. The next step is to set up the proposer to submit state root proposals.

<Card title="Spin up proposer →" href="./op-proposer-setup">
  **Next**: Configure and start op-proposer to submit L2 state roots to L1 for withdrawal verification.
</Card>

***

## Need Help?

* **Batcher Configuration**: [Batcher configuration reference](/chain-operators/reference/batcher-configuration)
* **Monitoring Guide**: [Chain Monitoring](/chain-operators/tools/chain-monitoring)
* **Support**: Open an issue in the [Optimism monorepo](https://github.com/ethereum-optimism/optimism/issues)


# Spin up challenger
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-challenger-setup

Learn how to configure challenger for your OP Stack chain.

After you have spun up your sequencer, batcher, and proposer, the final step is to configure a challenger to monitor and respond to disputes.

<Info>
  **Step 5 of 5**: This tutorial is designed to be followed step-by-step.
  Each step builds on the previous one, and this is the last part of the tutorial.
</Info>

<Info>
  **Automated Setup Available**

  For a complete working setup with all components including automated prestate generation, check out the [automated approach](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/) in the code directory.
</Info>

The challenger is a critical fault proofs component that monitors dispute games and challenges invalid claims to protect your OP Stack chain. See the [op-challenger explainer](/op-stack/fault-proofs/challenger) for a general overview of this fault proofs feature.

The challenger is responsible for:

* Monitoring dispute games created by the fault proof system
* Challenging invalid claims in dispute games
* Defending valid state transitions
* Resolving games when possible

## Prerequisites

### Essential requirements

Complete these prerequisites before wiring up the challenger:

<Steps>
  <Step title="Deploy OP Stack chain with fault proofs enabled">
    <Expandable title="Generate absolute prestate (Required)">
      The challenger needs the absolute prestate to participate in dispute games. The prestate is the on-chain commitment to a specific build of `kona-client`, the maintained fault proof program. (`op-program`, which previously filled this role, has reached end-of-support; see [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation).) Here's how to generate it:

      1. **Clone and checkout the correct version**:
         ```bash theme={null}
         git clone https://github.com/ethereum-optimism/optimism.git
         cd optimism
         git checkout kona-node/v1.6.1  # Use the latest release
         ```

      2. **Stage your chain configuration**:

         Because your chain is not in the public Superchain Registry, the prestate build must embed your chain's configuration. Create the two staging files (`chainList.json` and `configs.json`) from your `rollup.json`, L2 genesis, and `op-deployer` state by following [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate), then point the build at them:

         ```bash theme={null}
         # Assuming you're in rollup/challenger/optimism directory
         export KONA_CUSTOM_CONFIGS_DIR="$PWD/rust/kona/crates/protocol/registry/etc/custom-configs/<YOUR-CHAIN-NAME>"
         ```

      3. **Generate the prestate**:
         ```bash theme={null}
         just reproducible-prestate-kona
         jq -r .pre rust/kona/prestate-artifacts-cannon/prestate-proof.json
         ```
         The build runs in Docker and writes artifacts to `rust/kona/prestate-artifacts-cannon/`, including a preimage file named by its hash (`0x<PRESTATE_HASH>.bin.gz`). The hash printed by the `jq` command is your chain's absolute prestate.

      4. **Verify your chain is embedded in the prestate**:
         ```bash theme={null}
         gunzip -c rust/kona/prestate-artifacts-cannon/prestate.bin.gz | strings | grep "<YOUR-CHAIN-NAME>"
         ```
         Zero matches means the custom configuration was not merged (the build silently produces the standard prestate instead); see the [custom prestate tutorial](/chain-operators/tutorials/kona-custom-prestate) for troubleshooting.

      <Info>
        * Keep the `0x<PRESTATE_HASH>.bin.gz` file accessible - you'll need it for the challenger setup
        * For Superchain registry chains, you can find official `cannon64-kona` prestates in the [registry](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml)
      </Info>
    </Expandable>
  </Step>

  <Step title="Set up required infrastructure access">
    Your sequencer stack from the previous steps already provides the L2 endpoints the challenger needs (op-reth and op-node). In addition, the challenger needs:

    * An L1 RPC endpoint for your settlement layer (Sepolia in this tutorial)
    * An L1 beacon API endpoint, used to fetch blobs
  </Step>

  <Step title="Prepare configuration files">
    * `0x<PRESTATE_HASH>.bin.gz` - The absolute prestate preimage file generated in step 1
    * `rollup.json` - Rollup configuration file from the `op-deployer` guide
  </Step>
</Steps>

## Software installation

For challenger deployment, we recommend using Docker as it provides a consistent and isolated environment. Building from source is also available for more advanced users.

<Tabs>
  <Tab title="Use docker">
    ### Docker Setup

    The Docker setup provides a containerized environment for running the challenger. This method uses the official Docker image that includes the embedded `kona` server and Cannon executable.

    <Steps>
      <Step title="Create challenger directory">
        ```bash theme={null}
        # Create your challenger directory inside rollup
        cd ../    # Go back to rollup directory if you're in proposer
        mkdir challenger
        cd challenger
        ```
      </Step>

      <Step title="Create environment file">
        <Info>
          **OP Stack Standard Variables**

          The challenger uses OP Stack standard environment variables following the OP Stack conventions. These are prefixed with `OP_CHALLENGER_` for challenger-specific settings.
        </Info>

        ```bash theme={null}
        # Create .env file with your actual values
        cat > .env << 'EOF'
        # Core configuration (required)
        OP_CHALLENGER_L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY
        OP_CHALLENGER_L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com
        OP_CHALLENGER_PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY

        # L2 Configuration - Replace with your actual node endpoints  
        OP_CHALLENGER_L2_ETH_RPC=http://op-reth:8545
        OP_CHALLENGER_ROLLUP_RPC=http://op-node:8547

        # OP Stack challenger configuration (optional - defaults provided)
        OP_CHALLENGER_GAME_FACTORY_ADDRESS=YOUR_GAME_FACTORY_ADDRESS
        OP_CHALLENGER_CANNON_KONA_L2_GENESIS=/workspace/genesis.json
        OP_CHALLENGER_CANNON_KONA_ROLLUP_CONFIG=/workspace/rollup.json


        # Prestate configuration - Replace with the file from 'just reproducible-prestate-kona'
        OP_CHALLENGER_CANNON_KONA_PRESTATE=/workspace/${PRESTATE_HASH}.bin.gz
        EOF
        ```

        **Important:** Replace every `YOUR_ACTUAL_*` placeholder with the real values from your deployment.
      </Step>

      <Step title="Set up Docker Compose">
        Define the challenger service in a `docker-compose.yml`. It mounts several important files:

        * `prestate-proof.json` and `${PRESTATE_HASH}.bin.gz`: Prestate files required for dispute games (the PRESTATE\_HASH comes from running `just reproducible-prestate-kona`), replace `PRESTATE_HASH` with the actual hash

        ```yaml theme={null}

        services:
          challenger:
            image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v1.9.4
            user: "1000"
            volumes:
              - ./challenger-data:/data
              - ./rollup.json:/workspace/rollup.json:ro
              - ./genesis-l2.json:/workspace/genesis-l2.json:ro
              - ./prestate-proof.json:/workspace/prestate-proof.json:ro
              - ./${PRESTATE_HASH}.bin.gz:/workspace/${PRESTATE_HASH}.bin.gz:ro
            command: >
              op-challenger run-trace
              --trace-type=cannon-kona
              --datadir=/data
              --log.level=info
              --log.format=json
            restart: unless-stopped
            networks:
              - sequencer-node_default

        networks:
          sequencer-node_default:
            external: false


        ```
      </Step>

      <Step title="Launch the challenger">
        Start the challenger service and follow its logs:

        ```bash theme={null}
        # Start the challenger service
        docker-compose up -d

        # View logs
        docker-compose logs -f challenger
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Build from source">
    The generic build-from-source walkthrough lives in the "Build from source" tab of the
    [challenger configuration guide](/chain-operators/guides/configuration/op-challenger-config-guide#software-installation):
    it covers picking the release, building `op-challenger`, Cannon, and `kona-host`,
    verifying the binaries, the environment file, and the startup script. Follow it end
    to end, then adapt it to this tutorial series as follows:

    * **Workspace**: create the working directory as `rollup/challenger`, next to the
      `deployer`, `sequencer`, `batcher`, and `proposer` directories from the previous
      steps. With the monorepo checkout at `rollup/optimism`, the binaries are then
      reachable from the startup script as `../../optimism/op-challenger/bin/op-challenger`
      and `CANNON_BIN=../../optimism/cannon/bin/cannon`.
    * **kona-host**: build it in the checkout you generated the prestate from in the
      prerequisites (`kona-node/v1.6.1`), so the server matches your chain's absolute
      prestate, and point `CANNON_KONA_SERVER` at the resulting binary.
    * **Configuration files**: copy `rollup.json` and `genesis-l2.json` from the
      op-deployer step into `rollup/challenger`, set `CANNON_ROLLUP_CONFIG=./rollup.json`
      and `CANNON_L2_GENESIS=./genesis-l2.json` (the guide's startup script passes these
      to `--cannon-kona-rollup-config` and `--cannon-kona-l2-genesis`), and set
      `CANNON_KONA_PRESTATE=./0x<PRESTATE_HASH>.bin.gz`, the preimage file generated
      in the prerequisites.
    * **Trace type and wallet**: this chain is not in the superchain-registry, so keep
      `GAME_FACTORY_ADDRESS` explicit, use `--trace-type cannon-kona`, and sign with the
      funded private key you used for the other components (`--private-key` instead of
      the guide's mnemonic example).
  </Tab>
</Tabs>

### Monitoring with op-dispute-mon

Consider running [`op-dispute-mon`](/chain-operators/tools/chain-monitoring#dispute-mon) for enhanced security monitoring:

* Provides visibility into all game statuses for the last 28 days
* Essential for production challenger deployments

## Congratulations

You've successfully completed the entire L2 rollup testnet tutorial! Your rollup is now fully operational with all components running:

* **op-deployer** - L1 contracts deployed
* **Sequencer** - Processing transactions
* **Batcher** - Publishing data to L1
* **Proposer** - Submitting state roots
* **Challenger** - Monitoring disputes

## Connect your wallet to your chain

You now have a fully functioning OP Stack Rollup with a Sequencer node running on `http://localhost:8545`. You can connect your wallet to this chain the same way you'd connect your wallet to any other EVM chain.

## Get ETH on your chain

Once you've connected your wallet, you'll probably notice that you don't have any ETH to pay for gas on your chain.

The easiest way to deposit Sepolia ETH into your chain is to send ETH directly to the `L1StandardBridge` contract.

### Get the L1StandardBridge address

The `L1StandardBridge` proxy address can be found in your deployment state file. To get it, run:

```bash theme={null}
# From your project root
jq -r .l1StandardBridgeProxyAddress <PATH_TO_YOUR_OP_DEPLOYER_FOLDER>/.deployer/state.json
```

This will output the `L1StandardBridge` proxy address that you should use for deposits. Make sure to use the proxy address, not the implementation address.

### Deposit ETH to your L2

Once you have the `L1StandardBridge` address, send a small amount of Sepolia ETH (0.1 or less) to that address from the wallet you want to use on L2.
This will trigger a deposit that will mint ETH into your wallet on L2.

<Info>
  It may take up to 5 minutes for the ETH to appear in your wallet on L2.
  This delay is due to the time needed for the deposit transaction to be processed and finalized.
</Info>

## See your rollup in action

You can interact with your Rollup the same way you'd interact with any other EVM chain.
Send some transactions, deploy some contracts, and see what happens!

You now have a working testnet. Here is what the distance to production looks like:

<Info>
  **Running this in production**

  <OpEnterpriseCalloutBody />
</Info>

## Need Help?

* **OP Challenger Explainer**: [Fault Proofs Overview](/op-stack/fault-proofs/challenger)
* **Technical Specs**: [Honest Challenger Specification](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html)


# Deploy L1 contracts with op-deployer
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-deployer-setup

Install op-deployer, prepare your environment, and deploy the L1 smart contracts for your rollup.

Welcome to the first step of creating your own L2 rollup testnet! In this section, you'll install the op-deployer tool and deploy the necessary L1 smart contracts for your rollup.

<Info>
  **Step 1 of 5**: This tutorial is designed to be followed step-by-step. Each step builds on the previous one.
</Info>

<Info>
  **Quick Setup Available**

  For a complete automated setup that includes op-deployer deployment, check out the [`code/`](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/) directory. The automated setup handles all contract deployment and configuration automatically.
</Info>

## About op-deployer

`op-deployer` simplifies the process of deploying the OP Stack. You define a declarative config file called an "**intent**," then run a command to apply it. `op-deployer` compares your chain's current state against the intent and makes the necessary changes to match.

## Installation

There are a couple of ways to install `op-deployer`:

<Tabs>
  <Tab title="Use binary">
    The recommended way to install `op-deployer` is to download the latest release from the monorepo's [release page](https://github.com/ethereum-optimism/optimism/releases).

    <Info>
      **Quick Setup Available**

      For automated installation, you can use the download script from the [code directory](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/). This script automatically downloads the latest version for your system.
    </Info>

    <Steps>
      <Step title="Download the correct binary">
        1. Go to the [release page](https://github.com/ethereum-optimism/optimism/releases)
        2. Find the **latest** release that includes `op-deployer` (look for releases tagged with `op-deployer/v*`)
        3. Under **assets**, download the binary that matches your system:

        * For Linux: `op-deployer-linux-amd64`
        * For macOS:
          * Apple Silicon (M1/M2): `op-deployer-darwin-arm64`
          * Intel processors: `op-deployer-darwin-amd64`
        * For Windows: `op-deployer-windows-amd64.exe`

        <Info>
          **Always download the latest version** to ensure you have the most recent features and bug fixes.
        </Info>

        <Info>
          Not sure which macOS version to use?

          * Open Terminal and run `uname -m`
          * If it shows `arm64`, use the arm64 version
          * If it shows `x86_64`, use the amd64 version
        </Info>
      </Step>

      <Step title="Create deployer directory and install binary">
        1. Create the rollup directory structure and enter the deployer directory:

        ```bash theme={null}
        # Create main rollup directory
        mkdir rollup && cd rollup

        # Create and enter the deployer directory
        mkdir deployer && cd deployer
        ```

        Your directory structure will now look like this:

        ```bash theme={null}
        rollup/
        └── deployer/    # You are here
        ```

        2. Move and rename the downloaded binary:

        <Info>
          The downloaded file is likely in your Downloads folder:

          * macOS/Linux: `/Users/YOUR_USERNAME/Downloads`
          * Windows WSL: `/mnt/c/Users/YOUR_USERNAME/Downloads`
        </Info>

        ```bash theme={null}
        # Step 1: Extract the downloaded archive in the deployer directory
        # Replace FILENAME with the actual downloaded file name (includes version and arch)
        tar -xvzf /Users/USERNAME/Downloads/FILENAME.tar.gz

        # Step 2: Make the binary executable
        # Replace FILENAME with the extracted binary name
        chmod +x FILENAME

        # Step 3: Remove macOS quarantine attribute (fixes "can't be opened" warning)
        sudo xattr -dr com.apple.quarantine FILENAME

        # Step 4: Move the binary to your PATH
        # For Intel Macs:
        sudo mv FILENAME /usr/local/bin/op-deployer
        # For Apple Silicon Macs:
        sudo mv FILENAME /opt/homebrew/bin/op-deployer

        # Step 5: Verify installation (should print version info)
        op-deployer --version
        ```

        <Info>
          **Pro Tip**: Use the automated download script from the [code directory](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/) to avoid manual version management. It automatically detects your platform and downloads the latest version.
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Build from source">
    To install from source, you will need [Go](https://go.dev/doc/install), `just`, and `git`.
    After installing all of that, run following:

    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism.git # you can skip this if you already have the repo
    cd optimism/op-deployer
    just build
    cp ./bin/op-deployer /usr/local/bin/op-deployer # or any other directory in your $PATH

    # Verify installation
    op-deployer --version
    ```
  </Tab>
</Tabs>

## L1 network requirements

Before deploying your L1 contracts, you'll need:

**L1 RPC URL**: An Ethereum RPC endpoint for your chosen L1 network

```bash theme={null}
# Examples:
# Sepolia (recommended for testing)
L1_RPC_URL=https://sepolia.infura.io/v3/YOUR-PROJECT-ID
# or https://eth-sepolia.g.alchemy.com/v2/YOUR-API-KEY

# Local network
L1_RPC_URL=http://localhost:8545
```

<Info>
  For testing, we recommend using Sepolia testnet. You can get free RPC access from:

  * [Infura](https://infura.io) (create account, get API key)
  * [Alchemy](https://alchemy.com) (create account, get API key)
  * [Ankr](https://ankr.com) (create account, get API key)
</Info>

## Generate deployment addresses

Your rollup needs several addresses for different roles. Let's generate them first:

<Steps>
  <Step title="Create address directory">
    ```bash theme={null}
    # Create a address directory inside the deployer directory
    mkdir -p address
    cd address
    ```

    Your directory structure will now look like this:

    ```bash theme={null}
    rollup/
    └── deployer/
        └── address/    # You are here
    ```
  </Step>

  <Step title="Generate address for each role">
    ```bash theme={null}
    # Generate 8 new wallet addresses
    for role in admin base_Fee_Vault_Recipient l1_Fee_Vault_Recipient sequencer_Fee_Vault_Recipient system_config unsafe_block_signer batcher proposer ; do
        wallet_output=$(cast wallet new)
        echo "$wallet_output" | grep "Address:" | awk '{print $2}' > ${role}_address.txt
        echo "Created wallet for $role"
    done
    ```

    This will save the various addresses for your intent file into files in your current directory. To view them later you can use `cat *_address.txt`.
  </Step>
</Steps>

<Info>
  **Important**:

  * Save these address - you'll need them to operate your chain
  * You can use any address for the purpose of testing, for production, use proper key management solutions (HSMs, multisigs addresses)
</Info>

## Create and configure intent file

The intent file defines your chain's configuration.

<Steps>
  <Step title="Initialize intent file">
    Inside the `deployer` folder, run this command:

    ```bash theme={null}
    #You can use a 2-7 digit random number for your `<YOUR_CHAIN_ID>` 
    op-deployer init \
      --l1-chain-id 11155111 \
      --l2-chain-ids <YOUR_CHAIN_ID> \
      --workdir .deployer \
      --intent-type standard-overrides
    ```

    <Expandable title="Understanding intent types">
      `op-deployer` supports three intent types:

      * `standard`: Uses default OP Stack configuration, minimal customization
      * `standard-overrides`: Recommended. Uses defaults but allows overriding specific values
      * `custom`: Full customization, requires manual configuration of all values

      For most users, `standard-overrides` provides the best balance of simplicity and flexibility.
    </Expandable>
  </Step>

  <Step title="Update the intent file">
    Edit `.deployer/intent.toml` with your generated addresses. The `op-deployer init` command automatically populates this file with sensible defaults. Update the addresses while keeping the auto-generated contract locator values:

    ```toml theme={null}
    configType = "standard-overrides"
    l1ChainID = 11155111  # Sepolia
    fundDevAccounts = false  # Set to false for production/testnet
    useInterop = false
    opcmAddress = "0x3bb6437aba031afbf9cb3538fa064161e2bf2d78"  # OPCM contract address on Sepolia

    # Contract locators - REQUIRED fields, automatically populated by op-deployer init
    # Keep these default values unless you need specific contract versions (advanced use case)
    l1ContractsLocator = "tag://op-contracts/v2.0.0"
    l2ContractsLocator = "tag://op-contracts/v1.7.0-beta.1+l2-contracts"

    # Shared contract roles - only define if creating a standalone chain not part of the OP Stack ecosystem
    # For standard OP Stack deployments, these are predefined and should not be set
    # [superchainRoles]
    #   proxyAdminOwner = "0x..."     # admin address
    #   guardian = "0x..."            # admin address

    [[chains]]
      id = "0x000000000000000000000000000000000000000000000000000000000016de8d"
      baseFeeVaultRecipient = "0x..."       # receives base fees
      l1FeeVaultRecipient = "0x..."         # receives L1 data fees
      sequencerFeeVaultRecipient = "0x..."  # receives priority fees (tips)
      operatorFeeVaultRecipient = "0x..."   # receives operator fees
      eip1559DenominatorCanyon = 250
      eip1559Denominator = 50
      eip1559Elasticity = 6
      [chains.roles]
        l1ProxyAdminOwner = "0x1eb2ffc903729a0f03966b917003800b145f56e2"
        l2ProxyAdminOwner = "0x2fc3ffc903729a0f03966b917003800b145f67f3"
        systemConfigOwner = "0x..."      # system_config address
        unsafeBlockSigner = "0x..."      # unsafe_block_signer address
        batcher = "0x..."               # batcher address
        proposer = "0x..."              # proposer address
        challenger = "0xfd1d2e729ae8eee2e146c033bf4400fe75284301"
    ```

    <Expandable title="Understanding the configuration values">
      **Global Settings:**

      * `l1ChainID`: The L1 network ID (11155111 for Sepolia)
      * `fundDevAccounts`: Creates test accounts with ETH if true (set to false for production)
      * `useInterop`: Enable interoperability features (false for standard deployments)
      * `opcmAddress`: OP Contracts Manager (OPCM) contract address on the L1 network (automatically populated for supported networks)

      **Contract Locators (Required):**

      These fields are **required** and automatically populated by `op-deployer init` with default values compatible with your `op-deployer` version.
      Removing them will cause the error: "Application failed: L1ContractsLocator undefined".
      Keep the auto-generated values unless you specifically need different contract versions.
      For version compatibility details, see the [op-deployer release notes](https://github.com/ethereum-optimism/optimism/releases).

      **Shared Contract Roles (Advanced):**

      These are commented out because for standard OP Stack deployments, shared contract roles are predefined by the protocol. Only uncomment and define custom roles if you're creating a standalone chain not part of the OP Stack ecosystem.

      **Chain Configuration:**

      * `id`: Unique identifier for your chain
      * `*FeeVaultRecipient`: Addresses receiving protocol fees (required — deployment fails if any are set to the zero address). See [fee vaults](/op-stack/transactions/fee-vaults) for details on each vault.
      * `eip1559*`: Parameters for dynamic gas price calculation

      **Fee Vault Optional Overrides:**

      Each vault also supports optional parameters that can be set via deploy overrides. If not specified, the following defaults apply:

      | Parameter                  | Default      |
      | -------------------------- | ------------ |
      | `*MinimumWithdrawalAmount` | 10 ETH       |
      | `*WithdrawalNetwork`       | `local` (L2) |

      **Chain Roles:**

      * `l1ProxyAdminOwner`: Can upgrade L1 contract implementations (usually same as superchain proxyAdminOwner)
      * `l2ProxyAdminOwner`: Can upgrade L2 contract implementations
      * `systemConfigOwner`: Manages system configuration parameters
      * `unsafeBlockSigner`: Signs pre-confirmation blocks (can be same as batcher)
      * `batcher`: Submits L2 transaction batches to L1
      * `proposer`: Submits L2 state roots to L1 for verification
      * `challenger`: Monitors dispute games and defends valid states
    </Expandable>
  </Step>
</Steps>

<Info>
  Replace all `0x...` with actual addresses from your `addresses.txt` file.
  Never use the default test mnemonic addresses in production or public testnets!
</Info>

## Create environment file

Before deploying, create a `.env` file in your `deployer` directory to store your environment variables:

```bash theme={null}
# Create .env file
cat << 'EOF' > .env
# Your L1 RPC URL (e.g., from Alchemy, Infura)
L1_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY

# Private key for deployment.
# Get this from your self-custody wallet, like Metamask.
PRIVATE_KEY=WALLET_PRIVATE_KEY
EOF
```

<Info>
  Never commit your `.env` file to version control. Add it to your `.gitignore`:

  ```bash theme={null}
  echo ".env" >> .gitignore
  ```
</Info>

Load the environment variables:

```bash theme={null}
source .env
```

## Deploy L1 Contracts

Now that your intent file and environment variables are configured, let's deploy the L1 contracts:

```bash theme={null}
op-deployer apply \
  --workdir .deployer \
  --l1-rpc-url $L1_RPC_URL \
  --private-key $PRIVATE_KEY
```

This will:

1. Deploy all required L1 contracts
2. Configure them according to your intent file
3. Save deployment information to `.deployer/state.json`

<Info>
  The deployment can take 10-15 seconds and requires multiple transactions.
</Info>

## Generate chain configuration

After successful deployment, generate your chain configuration files:

```bash theme={null}
# Generate genesis and rollup configs
op-deployer inspect genesis --workdir .deployer <YOUR_CHAIN_ID> > .deployer/genesis.json
op-deployer inspect rollup --workdir .deployer <YOUR_CHAIN_ID> > .deployer/rollup.json
```

## What's Next?

Great! You've successfully:

1. Installed `op-deployer` using the `init` and `apply` command.
2. Created and configured your intent file
3. Deployed L1 smart contracts
4. Generated chain artifacts

Your final directory structure should look like this:

```bash theme={null}
rollup/
└── deployer/
    ├── .deployer/           # Contains deployment state and configs
    │   ├── genesis.json     # L2 genesis configuration
    │   ├── intent.toml      # Your chain configuration
    │   ├── rollup.json      # Rollup configuration
    │   └── state.json       # Deployment state
    ├── .env                 # Environment variables
    └── address/             # Generated address pairs
        ├── admin_address.txt
        ├── base_Fee_Vault_Recipient_address.txt
        ├── batcher_address.txt
        ├── l1_Fee_Vault_Recipient_address.txt
        ├── proposer_address.txt
        ├── sequencer_Fee_Vault_Recipient_address.txt
        ├── system_config_address.txt
        └── unsafe_block_signer_address.txt

```

Now you can move on to setting up your sequencer node.

<Card title="Spin up sequencer →" href="./op-reth-setup">
  **Next**: Set up op-reth and op-node, essential building blocks of the execution and consensus layers in your rollup.
</Card>

***

## Need Help?

* **op-deployer Documentation**: [op-deployer overview](/chain-operators/tools/op-deployer/overview)
* **op-deployer Repository**: [GitHub](https://github.com/ethereum-optimism/optimism/tree/develop/op-deployer)
* **OPCM Documentation**: [OP Contracts Manager](/chain-operators/reference/opcm)
* **Support**: Open an issue in the [Optimism monorepo](https://github.com/ethereum-optimism/optimism/issues)


# Spin up proposer
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-proposer-setup

Learn how to set up and configure an OP Stack proposer to post L2 state roots.

After you have spun up your sequencer and batcher, you need to attach a proposer to post your L2 state roots data back onto L1 so we can prove withdrawal validity. The proposer is a critical component that enables trustless L2-to-L1 messaging and creates the authoritative view of L2 state from L1's perspective.

<Info>
  **Step 4 of 5**: This tutorial is designed to be followed step-by-step. Each step builds on the previous one.
</Info>

<Info>
  **Automated Setup Available**

  For a complete working setup with all components, check out the [automated approach](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs/create-l2-rollup-example/) in the code directory.
</Info>

This guide assumes you already have a functioning sequencer, batcher, and the necessary L1 contracts deployed using [`op-deployer`](./op-deployer-setup). If you haven't set up your sequencer and batcher yet, please refer to the [sequencer guide](./op-reth-setup) and [batcher guide](./op-batcher-setup) first.

To see configuration info for the proposer, check out the [configuration page](/chain-operators/guides/configuration/proposer).

## Understanding the proposer's role

The proposer (`op-proposer`) serves as a crucial bridge between your L2 chain and L1. Its primary responsibilities include:

* **State commitment**: Proposing L2 state roots to L1 at regular intervals
* **Withdrawal enablement**: Providing the necessary commitments for users to prove and finalize withdrawals

The proposer creates dispute games via the `DisputeGameFactory` contract.

## Prerequisites

Before setting up your proposer, ensure you have:

**Running infrastructure:**

* An operational sequencer node
* Access to a L1 RPC endpoint

**Network information:**

* Your L2 chain ID and network configuration
* L1 network details (chain ID, RPC endpoints)

For setting up the proposer, we recommend using Docker as it provides a consistent and isolated environment. Building from source is also available as an option.

<Tabs>
  <Tab title="Use docker">
    If you prefer containerized deployment, you can use the official Docker images and do the following:

    <Steps>
      <Step title="Set up directory structure and copy configuration files">
        ```bash theme={null}
        # Create a proposer directory inside rollup
        cd ../    # Go back to rollup directory if you're in batcher
        mkdir proposer
        cd proposer
        # inside the proposer directory, copy the state.json file from the op-deployer setup
        # Copy configuration files from deployer
        cp ../deployer/.deployer/state.json .

        # Extract the DisputeGameFactory address
        GAME_FACTORY_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].DisputeGameFactoryProxy')
        echo "DisputeGameFactory Address: $GAME_FACTORY_ADDRESS"
        ```
      </Step>

      <Step title="Create environment variables file">
        <Info>
          **OP Stack Standard Variables**

          The proposer uses OP Stack standard environment variables following the OP Stack conventions. These are prefixed with `OP_PROPOSER_` for proposer-specific settings.
        </Info>

        ```bash theme={null}
        # Create .env file with your actual values
        cat > .env << 'EOF'
        #  L1 Configuration - Replace with your actual RPC URLs
        OP_PROPOSER_L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY

        # L2 Configuration - Should match your sequencer setup
        OP_PROPOSER_ROLLUP_RPC=http://op-node:8547

        # Contract addresses - Extract from your op-deployer output
        OP_PROPOSER_GAME_FACTORY_ADDRESS=YOUR_ACTUAL_GAME_FACTORY_ADDRESS

        # Private key - Replace with your actual private key
        OP_PROPOSER_PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY

        # OP Stack proposer configuration (optional - defaults provided)
        OP_PROPOSER_PROPOSAL_INTERVAL=3600s
        OP_PROPOSER_GAME_TYPE=0
        OP_PROPOSER_POLL_INTERVAL=20s
        OP_PROPOSER_ALLOW_NON_FINALIZED=true
        OP_PROPOSER_WAIT_NODE_SYNC=true
        EOF
        ```

        **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values.
      </Step>

      <Step title="Create docker-compose.yml">
        <Info>
          If you get "failed to dial address" errors, ensure your proposer is in the same Docker network as your sequencer.

          Common fixes:

          * Add `networks: - sequencer-node_default` to your proposer's docker-compose.yml
          * Use service names like `op-reth:8545` and `op-node:8547` in your `.env` file
          * Verify your sequencer network name with `docker network ls`
        </Info>

        ```yaml theme={null}

        services:
          op-proposer:
            image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-proposer:v1.16.3
            volumes:
              - .:/workspace
            working_dir: /workspace
            ports:
              - "8560:8560"
            env_file:
              - .env
            command: >
              op-proposer
              --rpc.port=8560
              --log.level=info
              --log.format=json
            restart: unless-stopped
            networks:
              - sequencer-node_default

        networks:
          sequencer-node_default:
            external: false

        ```
      </Step>

      <Step title="Start the proposer service">
        ```bash theme={null}
        # Make sure your sequencer network exists
        docker network create op-stack 2>/dev/null || true

        # Start the proposer
        docker-compose up -d

        # View logs
        docker-compose logs -f op-proposer
        ```
      </Step>

      <Step title="Verify proposer is running">
        ```bash theme={null}
        # Check container status
        docker-compose ps
        ```
      </Step>

      <Step title="Final directory structure">
        ```bash theme={null}
        rollup/
        ├── deployer/            # From previous step
        │   └── .deployer/      # Contains state.json
        ├── sequencer/          # From previous step
        ├── batcher/           # From previous step
        └── proposer/         # You are here
            ├── state.json    # Copied from deployer
            ├── .env          # Environment variables
            └── docker-compose.yml # Docker configuration
        ```
      </Step>
    </Steps>

    <Expandable title="Understanding proposer startup logs">
      When you first start your proposer, you'll see several types of log messages:

      1. **Initialization messages** (normal):
         ```
         lvl=info msg="Initializing L2Output Submitter"
         lvl=info msg="Connected to DisputeGameFactory"
         lvl=info msg="Starting JSON-RPC server"
         ```

      2. **Sync status messages** (expected during startup):
         ```
         msg="rollup current L1 block still behind target, retrying"
         current_l1=...:9094035 target_l1=9132815
         ```
         This is normal! It means:
         * Your rollup is still syncing with L1 (e.g., Sepolia)
         * The proposer is waiting until sync is closer to L1 tip
         * You'll see the `current_l1` number increasing as it catches up
         * Once caught up, the proposer will start submitting proposals

      Don't worry about the "retrying" messages - they show healthy progress as your rollup catches up to the latest L1 blocks.

      **Common log patterns:**

      * Startup: You'll see initialization messages as services start
      * Sync: "block still behind target" messages while catching up
      * Normal operation: Regular proposal submissions once synced
      * Network: Connection messages to L1/L2 endpoints

      If you see errors about "failed to dial" or connection issues:

      * For source build: Verify your localhost ports and services
    </Expandable>

    Your proposer is now operational and will continuously submit state roots to L1!
  </Tab>

  <Tab title="Build from source">
    ### Finding the current stable releases

    To ensure you're using the latest compatible versions of OP Stack components, always check the official [releases page](https://github.com/ethereum-optimism/optimism/releases).

    Look for the latest `op-proposer/v*` release that's compatible with your sequencer setup.

    <Info>
      This guide uses `op-proposer/v1.16.3`, the latest release at the time of writing, alongside op-node/v1.19.3 and op-reth/v2.4.0 from the sequencer setup.
      Always check the [release notes](https://github.com/ethereum-optimism/optimism/releases) for compatibility information.
    </Info>

    Building from source gives you full control over the binaries.

    <Steps>
      <Step title="Clone and build op-proposer">
        ```bash theme={null}
        # If you don't already have the optimism repository from the sequencer setup
        git clone https://github.com/ethereum-optimism/optimism.git
        cd optimism

        # Checkout the latest release tag
        git checkout op-proposer/v1.16.3

        # Build op-proposer
        cd op-proposer
        just

        # Binary will be available at ./bin/op-proposer
        ```
      </Step>

      <Step title="Verify installation">
        Run this command to verify the installation:

        ```bash theme={null}
        ./bin/op-proposer --version
        ```
      </Step>
    </Steps>

    ## Configuration setup

    <Info>
      The rest of this guide assumes you're using the **build-from-source** approach.
      If you chose Docker, all the necessary configuration was covered in the Docker tab above.
    </Info>

    <Steps>
      <Step title="Organize your workspace">
        Create your proposer working directory at the same level as your sequencer:

        ```bash theme={null}
        # Create proposer directory inside rollup
        cd ../    # Go back to rollup directory
        mkdir proposer
        cd proposer

        # Create scripts directory
        mkdir scripts
        ```
      </Step>

      <Step title="Extract DisputeGameFactory address">
        Extract the `DisputeGameFactory` contract address from your op-deployer output:

        ```bash theme={null}
        # Make sure you're in the rollup/proposer directory
        cd rollup/proposer

        # Copy the state.json from deployer
        cp ../deployer/.deployer/state.json .

        # Extract the DisputeGameFactory address
        GAME_FACTORY_ADDRESS=$(cat state.json | jq -r '.opChainDeployments[0].disputeGameFactoryProxyAddress')
        echo "DisputeGameFactory Address: $GAME_FACTORY_ADDRESS"
        ```

        <Info>
          The proposer only needs the `DisputeGameFactory` address to submit proposals.
          The `GAME_TYPE=0` represents the standard fault proof game type.
        </Info>
      </Step>

      <Step title="Set up environment variables">
        Create your `.env` file with the actual values:

        ```bash theme={null}
        # Create .env file with your actual values
        # L1 Configuration - Replace with your actual RPC URL
        L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY

        # L2 Configuration - Should match your sequencer setup
              L2_RPC_URL=http://localhost:8545
            ROLLUP_RPC_URL=http://localhost:8547

        # Contract addresses - Extract from your op-deployer output
        GAME_FACTORY_ADDRESS=YOUR_ACTUAL_GAME_FACTORY_ADDRESS

        # Private key - Replace with your actual private key
        PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY

        # Proposer configuration
        PROPOSAL_INTERVAL=3600s
        GAME_TYPE=0
        POLL_INTERVAL=20s

        # RPC configuration
        PROPOSER_RPC_PORT=8560
        ```

        **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values!
      </Step>

      <Step title="Get your private key">
        Get a private key from your wallet that will be used for submitting proposals to L1. This account needs sufficient ETH to pay for L1 gas costs.

        <Info>
          The proposer account needs to be funded with ETH on L1 to pay for proposal submission transactions. Monitor this account's balance regularly as it will consume ETH for each proposal submission.
        </Info>
      </Step>
    </Steps>

    ## Proposer configuration

    Create `scripts/start-proposer.sh`:

    ```bash theme={null}
    #!/bin/bash

    source .env

    # Path to the op-proposer binary we built
    ../../optimism/op-proposer/bin/op-proposer \
      --poll-interval=$POLL_INTERVAL \
      --rpc.port=$PROPOSER_RPC_PORT \
      --rpc.enable-admin \
      --rollup-rpc=$ROLLUP_RPC_URL \
      --l1-eth-rpc=$L1_RPC_URL \
      --private-key=$PRIVATE_KEY \
      --game-factory-address=$GAME_FACTORY_ADDRESS \
      --game-type=$GAME_TYPE \
      --proposal-interval=$PROPOSAL_INTERVAL \
      --num-confirmations=1 \
      --resubmission-timeout=30s \
      --wait-node-sync=true \
      --log.level=info
    ```

    Your final directory structure should look like:

    ```bash theme={null}
    rollup/
    ├── deployer/              # From previous step
    │   └── .deployer/        # Contains state.json
    ├── optimism/             # Contains op-proposer binary
    ├── sequencer/           # From previous step
    ├── batcher/            # From previous step
    └── proposer/          # You are here
        ├── state.json     # Copied from deployer
        ├── .env          # Environment variables
        └── scripts/      # Startup scripts
            └── start-proposer.sh
    ```

    ## Starting the proposer

    <Steps>
      <Step title="Start the proposer">
        ```bash theme={null}
        # Make the script executable
        chmod +x scripts/start-proposer.sh

        # Start the proposer
        ./scripts/start-proposer.sh
        ```
      </Step>
    </Steps>

    <Expandable title="Understanding proposer startup logs">
      When you first start your proposer, you'll see several types of log messages:

      1. **Initialization messages** (normal):
         ```
         lvl=info msg="Initializing L2Output Submitter"
         lvl=info msg="Connected to DisputeGameFactory"
         lvl=info msg="Starting JSON-RPC server"
         ```

      2. **Sync status messages** (expected during startup):
         ```
         msg="rollup current L1 block still behind target, retrying"
         current_l1=...:9094035 target_l1=9132815
         ```
         This is normal! It means:
         * Your rollup is still syncing with L1 (e.g., Sepolia)
         * The proposer is waiting until sync is closer to L1 tip
         * You'll see the `current_l1` number increasing as it catches up
         * Once caught up, the proposer will start submitting proposals

      Don't worry about the "retrying" messages - they show healthy progress as your rollup catches up to the latest L1 blocks.

      **Common log patterns:**

      * Startup: You'll see initialization messages as services start
      * Sync: "block still behind target" messages while catching up
      * Normal operation: Regular proposal submissions once synced
      * Network: Connection messages to L1/L2 endpoints

      If you see errors about "failed to dial" or connection issues:

      * For Docker: Check your network configuration and service names
    </Expandable>

    Your proposer is now operational!
  </Tab>
</Tabs>

## What's Next?

Perfect! Your proposer is submitting state roots to L1. The final step is to set up the challenger to monitor and respond to disputes.

<Card title="Spin up challenger →" href="./op-challenger-setup">
  **Next**: Configure and start op-challenger to monitor disputes and maintain your rollup's security.
</Card>

***

## Need Help?

* **Proposer Configuration**: [op-proposer Configuration Reference](/chain-operators/guides/configuration/proposer)
* **Dispute Games**: [Deploying Dispute Games with OPCM](/chain-operators/tutorials/dispute-games)


# Spin up sequencer
Source: https://docs.optimism.io/chain-operators/tutorials/create-l2-rollup/op-reth-setup

Set up and run op-reth and op-node, the execution and consensus layers for your rollup.

Now that you have op-deployer configured, it's time to spin up the sequencer for your rollup. This involves running both `op-reth` and `op-node` to create a functioning sequencer.

<Info>
  **Step 2 of 5**: This tutorial builds on [Spin up op-deployer](./op-deployer-setup). Make sure you've completed that first.
</Info>

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

This tutorial previously taught `op-geth` as the execution client; this page now uses `op-reth` throughout.

## What you'll set up

The sequencer node consists of two core components:

* `op-reth`: Execution layer that processes transactions and maintains state
* `op-node`: Consensus layer that orders transactions and creates L2 blocks

The sequencer is responsible for:

* Ordering transactions from users
* Building L2 blocks
* Signing blocks on the P2P network

## Software installation

For spinning up a sequencer, we recommend using Docker, as it provides a simpler setup and consistent environment. In this guide, building from source is also provided as an alternative for those who need more control and easier debugging.

<Info>
  The versions used in this guide (**op-node/v1.19.3** and **op-reth/v2.4.0**) were the latest releases at the time of writing.
  Check the [op-node releases](https://github.com/ethereum-optimism/optimism/releases?q=op-node) and [op-reth releases](https://github.com/ethereum-optimism/optimism/releases?q=op-reth) for the current versions, and always read the release notes for compatibility information.
</Info>

<Tabs>
  <Tab title="Use docker">
    <Steps>
      <Step title="Set up directory structure and copy configuration files">
        If you prefer containerized deployment, you can use the official Docker images, and do the following:

        ```bash theme={null}
        # Create your sequencer directory inside rollup
        cd ../    # Go back to rollup directory if you're in deployer
        mkdir sequencer
        cd sequencer

        # Copy configuration files from deployer
        cp ../deployer/.deployer/genesis.json .
        cp ../deployer/.deployer/rollup.json .

        # Generate JWT secret
        openssl rand -hex 32 > jwt.txt
        chmod 600 jwt.txt
        ```
      </Step>

      <Step title="Create environment variables file">
        ```bash theme={null}
        # Create .env file with your actual values
        cat > .env << 'EOF'
        # L1 Configuration - Replace with your actual RPC URLs
        L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY
        L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com

        # Private keys - Replace with your actual private key
        PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY

        # P2P configuration - Replace with your actual public IP
        # Run `curl ifconfig.me` in a separate shell to obtain the value, then paste it below 
        P2P_ADVERTISE_IP=YOUR_ACTUAL_PUBLIC_IP

        EOF
        ```

        **Important**: Replace ALL placeholder values (`YOUR_ACTUAL_*`) with your real configuration values.
      </Step>

      <Step title="Make sure your docker application is running">
        Create a `docker-compose.yml` file in the same directory:

        ```yaml theme={null}
        services:
          op-reth:
            image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-reth:v2.4.0
            volumes:
              # Mount entire directory to avoid file mounting issues
              - .:/workspace
            working_dir: /workspace
            ports:
              - "8545:8545"
              - "8546:8546"
              - "8551:8551"
            command:
              - "node"
              - "--chain=/workspace/genesis.json"
              - "--datadir=/workspace/op-reth-data"
              - "--http"
              - "--http.addr=0.0.0.0"
              - "--http.port=8545"
              - "--http.corsdomain=*"
              - "--http.api=admin,debug,eth,net,txpool,web3"
              - "--ws"
              - "--ws.addr=0.0.0.0"
              - "--ws.port=8546"
              - "--ws.origins=*"
              - "--ws.api=admin,debug,eth,net,txpool,web3"
              - "--authrpc.addr=0.0.0.0"
              - "--authrpc.port=8551"
              - "--authrpc.jwtsecret=/workspace/jwt.txt"
              - "--rollup.disable-tx-pool-gossip"
              - "--builder.deadline=2"
              - "--builder.interval=100ms"

          op-node:
            image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.19.3
            depends_on:
              - op-reth
            volumes:
              - .:/workspace
            working_dir: /workspace
            ports:
              - "8547:8547"
              - "9222:9222"
            environment:
              - L1_RPC_URL=${L1_RPC_URL}
              - L1_BEACON_URL=${L1_BEACON_URL}
              - PRIVATE_KEY=${PRIVATE_KEY}
              - P2P_ADVERTISE_IP=${P2P_ADVERTISE_IP}
            command:
              - "op-node"
              - "--l1=${L1_RPC_URL}"
              - "--l1.beacon=${L1_BEACON_URL}"
              - "--l2=http://op-reth:8551"
              - "--l2.jwt-secret=/workspace/jwt.txt"
              - "--l2.enginekind=reth"
              - "--rollup.config=/workspace/rollup.json"
              - "--sequencer.enabled=true"
              - "--sequencer.stopped=false"
              - "--sequencer.max-safe-lag=3600"
              - "--verifier.l1-confs=4"
              - "--p2p.listen.ip=0.0.0.0"
              - "--p2p.listen.tcp=9222"
              - "--p2p.listen.udp=9222"
              - "--p2p.advertise.ip=${P2P_ADVERTISE_IP}"
              - "--p2p.advertise.tcp=9222"
              - "--p2p.advertise.udp=9222"
              - "--p2p.sequencer.key=${PRIVATE_KEY}"
              - "--rpc.addr=0.0.0.0"
              - "--rpc.port=8547"
              - "--rpc.enable-admin"
              - "--log.level=info"
              - "--log.format=json"
        ```

        <Info>
          A few flags worth understanding:

          * `--chain=/workspace/genesis.json` points op-reth at the genesis file generated by op-deployer. Unlike op-geth, op-reth needs no separate `init` step — it initializes its database from the chain spec on first startup.
          * `--l2.enginekind=reth` tells op-node it is driving a reth-based execution client.
          * `--rollup.disable-tx-pool-gossip` is the op-reth equivalent of op-geth's `--rollup.disabletxpoolgossip=true`.
          * `--builder.deadline=2` and `--builder.interval=100ms` tune op-reth's block builder for the 2-second L2 block time (the defaults target Ethereum's 12-second slots).
          * op-reth runs as an archive node by default, so there is no `--gcmode=archive` equivalent to set.
        </Info>
      </Step>

      <Step title="Start the services">
        ```bash theme={null}
        # Start both services
        docker-compose up -d

        # View logs
        docker-compose logs -f
        ```
      </Step>

      <Step title="Final directory structure">
        ```bash theme={null}
        rollup/
        ├── deployer/              # From previous step
        │   └── .deployer/         # Contains genesis.json and rollup.json
        └── sequencer/             # You are here
            ├── jwt.txt            # Generated JWT secret
            ├── genesis.json       # Copied from deployer
            ├── rollup.json        # Copied from deployer
            ├── .env               # Environment variables
            ├── docker-compose.yml # Docker configuration
            ├── opnode_discovery_db/ # Created by Docker
            ├── opnode_peerstore_db/ # Created by Docker
            └── op-reth-data/      # Created by Docker (op-reth database)
        ```

        Your sequencer node is now operational and ready to process transactions.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Build from source">
    To ensure you're using the latest compatible versions of OP Stack components, always check the official [release page](https://github.com/ethereum-optimism/optimism/releases).

    The main components you'll need for sequencer deployment are:

    * `op-node`: Look for the latest `op-node/v*` [release](https://github.com/ethereum-optimism/optimism/releases?q=op-node)
    * `op-reth`: Look for the latest `op-reth/v*` [release](https://github.com/ethereum-optimism/optimism/releases?q=op-reth)

    Both components live in the [optimism monorepo](https://github.com/ethereum-optimism/optimism). Building op-node requires [Go](https://go.dev/dl/) and [just](https://github.com/casey/just); building op-reth requires a [Rust toolchain](https://rustup.rs/) (the build picks up the version pinned in `rust/rust-toolchain.toml` automatically).

    Building from source gives you full control over the binaries.

    <Steps>
      <Step title="Clone and build op-node">
        ```bash theme={null}
        # Clone the optimism monorepo
        git clone https://github.com/ethereum-optimism/optimism.git
        cd optimism

        # Checkout the latest op-node release tag
        git checkout op-node/v1.19.3

        # Generate the embedded superchain config bundle (initializes the
        # superchain-registry submodule; op-node embeds this file at compile time)
        just build-superchain-go

        # Build op-node
        cd op-node
        just

        # Binary will be available at ./bin/op-node
        cd ..
        ```
      </Step>

      <Step title="Build op-reth">
        ```bash theme={null}
        # Still inside the optimism monorepo:
        # checkout the latest op-reth release tag
        git checkout op-reth/v2.4.0

        # Sync the superchain-registry submodule to this tag
        # (the op-reth build generates its chain configs from it)
        just update-superchain-registry-submodule

        # Build op-reth (release build; this can take a while)
        cd rust
        cargo build --release --bin op-reth

        # Binary will be available at ./target/release/op-reth
        cd ..
        ```

        <Info>
          op-node and op-reth release from the same repository on different tags, so the two builds check out different tags in sequence. The `--version` checks below confirm what you actually built. If you prefer, use two separate clones of the monorepo instead.
        </Info>
      </Step>

      <Step title="Verify installation">
        Check that you have properly installed the needed components.

        ```bash theme={null}
        # From the optimism monorepo root
        ./op-node/bin/op-node --version
        ./rust/target/release/op-reth --version
        ```
      </Step>
    </Steps>

    ## Configuration setup

    <Steps>
      <Step title="Organize your workspace">
        After building the binaries, you should have the following directory structure:

        ```bash theme={null}
        rollup/
        ├── deployer/              # From previous step
        │   └── .deployer/         # Contains genesis.json and rollup.json
        └── optimism/              # Optimism monorepo
            ├── op-node/
            │   └── bin/
            │       └── op-node
            └── rust/
                └── target/
                    └── release/
                        └── op-reth
        ```

        Now create your sequencer working directory:

        ```bash theme={null}
        cd ../
        mkdir sequencer
        cd sequencer
        ```
      </Step>

      <Step title="Generate JWT secret">
        ```bash theme={null}
        openssl rand -hex 32 > jwt.txt
        chmod 600 jwt.txt
        ```
      </Step>

      <Step title="Set up directory structure and copy files">
        ```bash theme={null}
        mkdir scripts
        cp ../deployer/.deployer/genesis.json .
        cp ../deployer/.deployer/rollup.json .
        ```
      </Step>

      <Step title="Environment variables">
        You'll need to gather several pieces of information before creating your configuration.
      </Step>

      <Step title="Get L1 network access">
        You need access to the L1 network (Ethereum mainnet or Sepolia testnet) and its beacon node.

        **L1 RPC URL options:**

        * **Infura**: [infura.io](https://infura.io)
        * **Alchemy**: [alchemy.com](https://alchemy.com)

        **L1 Beacon URL options:**

        * `https://ethereum-sepolia-beacon-api.publicnode.com`
        * `https://ethereum-beacon-api.publicnode.com`
      </Step>

      <Step title="Get private key from your wallet">
        For this basic sequencer setup, you only need a private key during op-node initialization.
      </Step>

      <Step title="Get your public IP address">
        ```bash theme={null}
        curl ifconfig.me
        curl ipinfo.io/ip
        ```
      </Step>

      <Step title="Choose your ports">
        * `8545`: op-reth HTTP RPC
        * `8546`: op-reth WebSocket RPC
        * `8551`: op-reth Auth RPC (Engine API)
        * `8547`: op-node RPC
        * `9222`: P2P networking
      </Step>
    </Steps>

    <Expandable title=".env template">
      ```bash theme={null}
      L1_RPC_URL=https://sepolia.infura.io/v3/YOUR_ACTUAL_INFURA_KEY
      L1_BEACON_URL=https://ethereum-sepolia-beacon-api.publicnode.com
      SEQUENCER_ENABLED=true
      SEQUENCER_STOPPED=false
      PRIVATE_KEY=YOUR_ACTUAL_PRIVATE_KEY
      P2P_LISTEN_PORT=9222
      P2P_ADVERTISE_IP=YOUR_ACTUAL_PUBLIC_IP
      OP_NODE_RPC_PORT=8547
      OP_RETH_HTTP_PORT=8545
      OP_RETH_WS_PORT=8546
      OP_RETH_AUTH_PORT=8551
      JWT_SECRET=./jwt.txt
      ```
    </Expandable>

    ## Sequencer specific configuration

    ### op-reth configuration for sequencer

    Create `scripts/start-op-reth.sh`:

    ```bash theme={null}
    #!/bin/bash
    source .env

    ../optimism/rust/target/release/op-reth node \
      --chain=./genesis.json \
      --datadir=./op-reth-data \
      --http \
      --http.addr=0.0.0.0 \
      --http.port=$OP_RETH_HTTP_PORT \
      --http.corsdomain="*" \
      --http.api=admin,debug,eth,net,txpool,web3 \
      --ws \
      --ws.addr=0.0.0.0 \
      --ws.port=$OP_RETH_WS_PORT \
      --ws.origins="*" \
      --ws.api=admin,debug,eth,net,txpool,web3 \
      --authrpc.addr=0.0.0.0 \
      --authrpc.port=$OP_RETH_AUTH_PORT \
      --authrpc.jwtsecret=$JWT_SECRET \
      --rollup.disable-tx-pool-gossip \
      --builder.deadline=2 \
      --builder.interval=100ms
    ```

    <Info>
      op-reth initializes its database from the genesis file on first startup — there is no separate `geth init`-style step. It also runs as an archive node by default.
    </Info>

    ### op-node configuration for sequencer

    Create `scripts/start-op-node.sh`:

    ```bash theme={null}
    #!/bin/bash
    source .env

    ../optimism/op-node/bin/op-node \
      --l1=$L1_RPC_URL \
      --l1.beacon=$L1_BEACON_URL \
      --l2=http://localhost:$OP_RETH_AUTH_PORT \
      --l2.jwt-secret=$JWT_SECRET \
      --l2.enginekind=reth \
      --rollup.config=./rollup.json \
      --sequencer.enabled=$SEQUENCER_ENABLED \
      --sequencer.stopped=$SEQUENCER_STOPPED \
      --sequencer.max-safe-lag=3600 \
      --verifier.l1-confs=4 \
      --p2p.listen.ip=0.0.0.0 \
      --p2p.listen.tcp=$P2P_LISTEN_PORT \
      --p2p.listen.udp=$P2P_LISTEN_PORT \
      --p2p.advertise.ip=$P2P_ADVERTISE_IP \
      --p2p.advertise.tcp=$P2P_LISTEN_PORT \
      --p2p.advertise.udp=$P2P_LISTEN_PORT \
      --p2p.sequencer.key=$PRIVATE_KEY \
      --rpc.addr=0.0.0.0 \
      --rpc.port=$OP_NODE_RPC_PORT \
      --rpc.enable-admin \
      --log.level=info \
      --log.format=json
    ```

    ## Starting the sequencer

    <Steps>
      <Step title="Start op-reth">
        ```bash theme={null}
        cd rollup/sequencer
        chmod +x scripts/start-op-reth.sh
        chmod +x scripts/start-op-node.sh
        ./scripts/start-op-reth.sh
        ```
      </Step>

      <Step title="Start op-node">
        In a second terminal:

        ```bash theme={null}
        ./scripts/start-op-node.sh
        ```
      </Step>

      <Step title="Verify sequencer is running">
        ```bash theme={null}
        curl -X POST -H "Content-Type: application/json" \
          --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
          http://localhost:8545

        curl -X POST -H "Content-Type: application/json" \
          --data '{"jsonrpc":"2.0","method":"admin_sequencerActive","params":[],"id":1}' \
          http://localhost:8547
        ```
      </Step>
    </Steps>

    Your sequencer node is now operational and ready to process transactions.
  </Tab>
</Tabs>

## What's Next?

Great! Your sequencer is running and processing transactions. The next step is to set up the batcher to publish transaction data to L1.

<Card title="Spin up batcher →" href="./op-batcher-setup">
  **Next**: Configure and start op-batcher to publish L2 transaction data to L1 for data availability.
</Card>

***

## Need Help?

* **Running op-reth**: [Execution client configuration](/node-operators/guides/configuration/execution-clients)
* **op-reth CLI reference**: [op-reth node command](/node-operators/op-reth/cli/op-reth/node)
* **Best Practices**: [Chain Operator Best Practices](/chain-operators/guides/management/best-practices)
* **Support**: [Report an issue or ask a question](https://github.com/ethereum-optimism/optimism/issues) in the Optimism monorepo


# Deploying new dispute games with OPCM
Source: https://docs.optimism.io/chain-operators/tutorials/dispute-games

Learn how to deploy new dispute games to an OP Stack chain using OPCM

This guide provides instructions on how to deploy new dispute games to an OP Stack chain using the [OPCM (OP Contracts Manager)](/chain-operators/reference/opcm). This process is particularly relevant for teams looking to upgrade their chains to support permissionless dispute games.

## Prerequisites

Before you begin, ensure that:

* Run op-contracts/v2.0.0 or higher on your chain
* Own the chain's L1 `ProxyAdmin` contract
* Install the Forge toolkit (see [Foundry docs](https://getfoundry.sh/))

## Understanding dispute games

The OP Stack uses two types of dispute games:

* **Permissioned dispute game**: Limited to specific proposer and challenger addresses
* **Permissionless dispute game**: Open to anyone to propose or challenge

<Info>
  In the Permissioned dispute game (PDG), the [challenger role](/op-stack/protocol/privileged-roles) is a protocol-level permission assigned to specific addresses, allowing them to initiate or respond to disputes. This role is distinct from the op-challenger service, which is an off-chain monitoring service responsible for automatically detecting discrepancies and submitting challenges.
  While the op-challenger service typically operates using an address that has been assigned the challenger role, the protocol-level role itself can be independently assigned, regardless of whether the op-challenger service is in use.
  Refer to the [OP Stack configurability spec](https://specs.optimism.io/protocol/configurability.html) for more details.
</Info>

All chains deployed with `op-deployer` only initially include the permissioned dispute game.
This guide explains how to add the permissionless game.

## The `addGameType` function

The OPCM contract contains an `addGameType` function that handles the deployment of new dispute games. This function:

1. Deploys a new dispute game implementation
2. Optionally deploys a new [`DelayedWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/DelayedWETH.sol) contract
3. Registers the game with the `DisputeGameFactory`
4. Sets the initial bond amount

### 1. Finding the correct OPCM instance

Each OP Contracts release has its own OPCM instance. You must use the OPCM corresponding exactly to your chain's contract version. For example, if your system uses contracts version **v3.0.0**, you must use the OPCM for **v3.0.0**.

To find the correct OPCM address:

* For **Mainnet**, refer to the [standard-versions-mainnet.toml](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml) file in the superchain-registry.
* For **Sepolia**, refer to the [standard-versions-sepolia.toml](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-sepolia.toml) file in the superchain-registry.

These registry files contain mappings between OP contract versions and their corresponding OPCM addresses.

### 2. Preparing the `addGameType` Call

The `addGameType` function expects an array of `AddGameInput` structs. Here is the structure:

```solidity theme={null}
struct AddGameInput {
    string saltMixer;
    ISystemConfig systemConfig;
    IProxyAdmin proxyAdmin;
    IDelayedWETH delayedWETH;
    GameType disputeGameType;
    Claim disputeAbsolutePrestate;
    uint256 disputeMaxGameDepth;
    uint256 disputeSplitDepth;
    Duration disputeClockExtension;
    Duration disputeMaxClockDuration;
    uint256 initialBond;
    IBigStepper vm;
    bool permissioned;
}
```

**Key parameters explained:**

* **saltMixer:** A string used to create unique contract addresses
* **systemConfig:** The address of your chain's `SystemConfig` contract
* **proxyAdmin:** The Address of your chain's `ProxyAdmin` contract
* **delayedWETH:** The Address of the `DelayedWETH` contract (use zero address to deploy a new one)
* **disputeGameType:** For permissionless games, use `GameTypes.CANNON`
* **disputeAbsolutePrestate:** The absolute prestate hash for the game
* **permissioned:** Set to `false` for a permissionless game

For a permissionless game, you'll generally want to mirror most parameters from your existing permissioned game, but set permissioned to `false` and use the GameType `CANNON`.

3. Execute the addGameType function
   The following is a template for calling the addGameType function using Forge's cast:

<Info>
  The most recommended way is to use a script to execute this call, rather than manual execution.
</Info>

```bash theme={null}
# Retrieve existing values from chain for reference
# Get permissioned game implementation
PERMISSIONED_GAME=$(cast call --rpc-url $RPC_URL $DISPUTE_GAME_FACTORY "gameImpls(uint32)" $PERMISSIONED_GAME_TYPE)

# Retrieve parameters from existing permissioned game
ABSOLUTE_PRESTATE=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "absolutePrestate()")
MAX_GAME_DEPTH=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "maxGameDepth()")
SPLIT_DEPTH=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "splitDepth()")
CLOCK_EXTENSION=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "clockExtension()")
MAX_CLOCK_DURATION=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "maxClockDuration()")
VM=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "vm()")
ANCHOR_STATE_REGISTRY=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "anchorStateRegistry()")
L2_CHAIN_ID=$(cast call --rpc-url $RPC_URL $PERMISSIONED_GAME "l2ChainId()")

# Create call data for addGameType function
# Note: Set delayedWETH to 0x0 to deploy a new one
CALLDATA=$(cast calldata "addGameType((string,address,address,address,uint32,bytes32,uint256,uint256,uint64,uint64,uint256,address,bool)[])" \
"[(\
\"unique_salt_mixer\",\
$SYSTEM_CONFIG,\
$PROXY_ADMIN,\
0x0000000000000000000000000000000000000000,\
$CANNON_GAME_TYPE,\
$ABSOLUTE_PRESTATE,\
$MAX_GAME_DEPTH,\
$SPLIT_DEPTH,\
$CLOCK_EXTENSION,\
$MAX_CLOCK_DURATION,\
$INITIAL_BOND,\
$VM,\
false\
)]")

# Execute the transaction
cast send --rpc-url $RPC_URL --private-key $PRIVATE_KEY $OPCM_ADDRESS $CALLDATA
```

4. Setting the respected game type
   After deploying the permissionless dispute game, you'll need to update the respectedGameType in the OptimismPortal to start using it.
   For detailed instructions on setting the respected game type and migrating your chain from permissioned to permissionless fault proofs, refer to the [migrating to permissionless fault proofs guide](/chain-operators/tutorials/migrating-permissionless).

## Next Steps

* For more detail on deploying new dispute games with OPCM, [see the docs](/chain-operators/tutorials/dispute-games).
* Learn about [absolute prestate](/chain-operators/tutorials/absolute-prestate)
* checkout the [migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless) guide
* [Fault proofs explainer](/op-stack/fault-proofs/explainer)


# Integrating a new DA layer with Alt-DA
Source: https://docs.optimism.io/chain-operators/tutorials/integrating-da-layer

Learn how to add support for a new DA Layer within the OP Stack.

<Info>
  The Alt-DA Mode feature is currently in <strong>Beta</strong>  within the MIT-licensed OP Stack. Beta features are built and reviewed by Optimism Collective core contributors, and provide developers with early access to highly requested configurations.
  These features may experience stability issues, and we encourage feedback from our early users.
</Info>

[Alt-DA Mode](/op-stack/features/experimental/alt-da-mode) enables seamless integration of any DA Layer, regardless of their commitment type, into the OP Stack. After a DA Server is built for a DA Layer, any chain operator can launch an OP Stack chain using that DA Layer for sustainably low costs.

## Build your DA server

Our suggestion is for every DA Layer to build and maintain their own DA Server, with support from the OP Labs team along the way. The DA Server will need to be run by every node operator, so we highly recommend making your DA Server open source and MIT licensed.

<Steps>
  <Step title="Design your commitment binary encoding">
    * It must point to the data on your layer (like block height / hash).
    * It must be able to validate the data returned from the data (i.e., include a cryptographic commitment to the data like a hash, merkle proof, or polynomial commitment, this could be done against the block hash with a complex proof).

    <Info>
      See the [specs](https://specs.optimism.io/experimental/alt-da.html?highlight=input-commitment-submission?utm_source=op-docs\&utm_medium=docs#input-commitment-submission) for more info on commitment submission.
    </Info>
  </Step>

  <Step title="Claim your da\_layer byte">
    * Claim your [byte](https://github.com/ethereum-optimism/specs/discussions/135)
  </Step>

  <Step title="Implement the DA server">
    * Write a simple HTTP server which supports `get` and `put`
    * `put` is used by the batcher and can return the commitment to the batcher in the body. It should not return until the data is known to be submitted to your DA layer.
    * `get` should fetch the data. If the data is not available, it should return a `404` not found. If there are other errors, a different error should be returned.
  </Step>
</Steps>

## Run Alt-DA

Follow our guide on [how to operate an Alt-DA Mode chain](/chain-operators/guides/features/alt-da-mode-guide), except instead of using the S3 DA server, use the DA server that you built.

## Next steps

* For more detail on implementing the DA Server, [see the specification](https://specs.optimism.io/experimental/alt-da.html?utm_source=op-docs\&utm_medium=docs#da-server).


# Generating a custom kona-client absolute prestate
Source: https://docs.optimism.io/chain-operators/tutorials/kona-custom-prestate

How to build a kona-client absolute prestate that embeds a chain configuration not yet in the public Superchain Registry.

# Overview

For chains that are part of the public [`superchain-registry`](https://github.com/ethereum-optimism/superchain-registry), the standard `kona-client` absolute prestate published in [`standard-prestates.toml`](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml) already embeds your chain configuration. No custom build is needed.

This tutorial is for the rarer case: a partner chain whose `RollupConfig` is not yet in the public registry but which still needs to run permissionless fault proofs (`cannon-kona` game type). In that case you must build a custom `kona-client` that embeds your chain's configuration, generate the absolute prestate hash from that build, and host the resulting binary at a URL `op-challenger` can fetch.

<Info>
  Most chains are in the Superchain Registry and should use the standard prestate; follow [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate) instead. Only follow this tutorial if your chain is **not yet** in the registry. Once the chain is added to the public registry, future releases will cover it via the standard prestate and you can stop maintaining a custom build.
</Info>

## Prerequisites

Before starting, ensure you have:

* [Docker](https://docs.docker.com/engine/install/) running
* [`just`](https://github.com/casey/just) installed
* Your chain's `rollup.json`, L2 genesis, and deployment artifacts (typically produced by `op-deployer`)

## How kona-client picks up custom chain configurations

`kona-client` reads its embedded chain registry from the [`kona-registry` crate](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/protocol/registry). At build time, the crate's `build.rs` can merge additional chains on top of the canonical Superchain Registry snapshot. The merge is gated by two environment variables:

```bash theme={null}
KONA_CUSTOM_CONFIGS=true
KONA_CUSTOM_CONFIGS_DIR=/absolute/path/to/your/configs
```

When set, the build script reads two files from `KONA_CUSTOM_CONFIGS_DIR`:

* `chainList.json` — light-weight `Chain` entries for your custom chains
* `configs.json` — full `ChainConfig` + `RollupConfig` entries grouped under a `Superchain` bucket

The full schema and an end-to-end example are documented in the [`kona-registry` README](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/protocol/registry#custom-chain-configurations).

The compiled `kona-client` binary embeds the merged registry via `include_str!()`, so the resulting absolute prestate hash differs from the standard one. Any honest challenger participating in your chain's dispute games will need to run this same binary.

## Generating the custom prestate

<Steps>
  <Step title="Check out a kona-node release tag">
    Use the same `kona-node/v<VERSION>` tag that your chain's nodes are running. The native `KONA_CUSTOM_CONFIGS_DIR` support documented below requires **`kona-node/v1.5.2` or later**; on older tags, additional justfile patches are needed.

    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism.git
    cd optimism
    git checkout kona-node/v<VERSION>
    ```
  </Step>

  <Step title="Stage your chain configuration">
    Create a directory for your custom configs:

    ```bash theme={null}
    mkdir -p rust/kona/crates/protocol/registry/etc/custom-configs/<chain-name>
    ```

    Add two files inside it — `chainList.json` (lightweight chain entry) and `configs.json` (full rollup config). Replace every `<PLACEHOLDER>` with your chain's value. Notes:

    * **`<CHAIN_GROUP>`**: `mainnet` if your L1 is Ethereum mainnet, `sepolia` if your L1 is Sepolia. The bucket groups chains by L1 network, not by governance — your custom-chain status is expressed via `governedByOptimism: false` and `superchainLevel: 0`.
    * **`faultProofs.status`**: `permissionless` for chains running the `cannon-kona` game type publicly, `permissioned` for chains that only allow whitelisted challengers.

    <Tabs>
      <Tab title="chainList.json">
        ```json theme={null}
        [
          {
            "name": "<YOUR_CHAIN_NAME>",
            "identifier": "<CHAIN_GROUP>/<YOUR_CHAIN_NAME>",
            "chainId": <YOUR_L2_CHAIN_ID>,
            "rpc": [],
            "explorers": [],
            "superchainLevel": 0,
            "governedByOptimism": false,
            "dataAvailabilityType": "eth-da",
            "parent": { "type": "L2", "chain": "<CHAIN_GROUP>" },
            "faultProofs": { "status": "<permissionless | permissioned>" }
          }
        ]
        ```
      </Tab>

      <Tab title="configs.json">
        ```json theme={null}
        {
          "superchains": [
            {
              "name": "<CHAIN_GROUP>",
              "config": {
                "name": "<CHAIN_GROUP_DISPLAY_NAME>",
                "l1": {
                  "chain_id": <L1_CHAIN_ID>,
                  "public_rpc": "<L1_PUBLIC_RPC>",
                  "explorer": "<L1_EXPLORER>"
                },
                "hardforks": {
                  "canyon_time": 0,
                  "delta_time": 0,
                  "ecotone_time": 0,
                  "fjord_time": 0,
                  "granite_time": 0,
                  "holocene_time": 0,
                  "isthmus_time": 0,
                  "jovian_time": 0
                },
                "superchain_config_addr": null,
                "op_contracts_manager_proxy_addr": null
              },
              "chains": [
                {
                  "Name": "<YOUR_CHAIN_NAME>",
                  "PublicRPC": "",
                  "SequencerRPC": "",
                  "Explorer": "",
                  "SuperchainLevel": 0,
                  "GovernedByOptimism": false,
                  "SuperchainTime": 0,
                  "DataAvailabilityType": "eth-da",
                  "l2_chain_id": <YOUR_L2_CHAIN_ID>,
                  "batch_inbox_address": "<BATCH_INBOX_ADDRESS>",
                  "block_time": 2,
                  "seq_window_size": 3600,
                  "max_sequencer_drift": 600,
                  "GasPayingToken": null,
                  "hardfork_configuration": {
                    "canyon_time": 0,
                    "delta_time": 0,
                    "ecotone_time": 0,
                    "fjord_time": 0,
                    "granite_time": 0,
                    "holocene_time": 0,
                    "isthmus_time": 0,
                    "jovian_time": 0
                  },
                  "optimism": {
                    "eip1559Elasticity": 6,
                    "eip1559Denominator": 50,
                    "eip1559DenominatorCanyon": 250
                  },
                  "alt_da": null,
                  "genesis": {
                    "l1": {
                      "number": <L1_GENESIS_BLOCK>,
                      "hash": "<L1_GENESIS_HASH>"
                    },
                    "l2": {
                      "number": 0,
                      "hash": "<L2_GENESIS_HASH>"
                    },
                    "l2_time": <L2_GENESIS_TIMESTAMP>,
                    "system_config": {
                      "batcherAddr": "<BATCHER_ADDRESS>",
                      "overhead": "0x0000000000000000000000000000000000000000000000000000000000000000",
                      "scalar": "<SCALAR_HEX>",
                      "gasLimit": 60000000
                    }
                  },
                  "Roles": {
                    "SystemConfigOwner": "<SYSTEM_CONFIG_OWNER>",
                    "ProxyAdminOwner": "<PROXY_ADMIN_OWNER>",
                    "Guardian": "<GUARDIAN>",
                    "Challenger": "<CHALLENGER>",
                    "Proposer": "<PROPOSER>",
                    "UnsafeBlockSigner": "<UNSAFE_BLOCK_SIGNER>",
                    "BatchSubmitter": "<BATCH_SUBMITTER>"
                  },
                  "Addresses": {
                    "AddressManager": "<ADDRESS_MANAGER>",
                    "L1CrossDomainMessengerProxy": "<L1_CROSS_DOMAIN_MESSENGER_PROXY>",
                    "L1Erc721BridgeProxy": "<L1_ERC721_BRIDGE_PROXY>",
                    "L1StandardBridgeProxy": "<L1_STANDARD_BRIDGE_PROXY>",
                    "L2OutputOracleProxy": "0x0000000000000000000000000000000000000000",
                    "OptimismMintableErc20FactoryProxy": "<OPTIMISM_MINTABLE_ERC20_FACTORY_PROXY>",
                    "OptimismPortalProxy": "<OPTIMISM_PORTAL_PROXY>",
                    "SystemConfigProxy": "<SYSTEM_CONFIG_PROXY>",
                    "ProxyAdmin": "<PROXY_ADMIN>",
                    "AnchorStateRegistryProxy": "<ANCHOR_STATE_REGISTRY_PROXY>",
                    "DelayedWethProxy": "<DELAYED_WETH_PROXY>",
                    "DisputeGameFactoryProxy": "<DISPUTE_GAME_FACTORY_PROXY>",
                    "FaultDisputeGame": "<FAULT_DISPUTE_GAME>",
                    "PermissionedDisputeGame": "<PERMISSIONED_DISPUTE_GAME>"
                  }
                }
              ]
            }
          ]
        }
        ```
      </Tab>
    </Tabs>

    Source the values from your chain's existing artifacts:

    * `genesis.*`, `block_time`, `seq_window_size`, `max_sequencer_drift`, `batch_inbox_address`, hardfork timestamps → your chain's `rollup.json`
    * `Addresses.*` → your `op-deployer` state (`opChainDeployments[<i>]`)
    * `Roles.*` → your `op-deployer` state's per-chain `roles` block

    Cross-check each L1 contract address onchain (`cast call`) before committing.
  </Step>

  <Step title="Generate the absolute prestate">
    From the root of the monorepo, point `KONA_CUSTOM_CONFIGS_DIR` at the directory you created in Step 2, then run the canonical build:

    ```bash theme={null}
    export KONA_CUSTOM_CONFIGS_DIR="$PWD/rust/kona/crates/protocol/registry/etc/custom-configs/<chain-name>"
    just reproducible-prestate-kona
    jq -r .pre rust/kona/prestate-artifacts-cannon/prestate-proof.json
    ```

    The hash printed is your chain's custom kona absolute prestate. The build also writes a hash-named gzipped binary at `rust/kona/prestate-artifacts-cannon/0x<hash>.bin.gz` — this is the file `op-challenger` needs to fetch at dispute time.
  </Step>

  <Step title="Verify your chain is embedded in the prestate">
    A custom-config build that silently fails to merge your chain produces the *standard* prestate hash — and an `op-challenger` pointed at it will never agree with your games. Always confirm your chain actually made it in:

    ```bash theme={null}
    # 1. The build log must list every custom chain that was merged:
    #    cargo:warning=...: inserting new custom chain <bucket>: [chain-a,chain-b]
    #    (or "merging custom chains <bucket>: [...]" if the bucket already exists)
    #
    # 2. The chain name must appear inside the prestate image itself:
    gunzip -c rust/kona/prestate-artifacts-cannon/prestate.bin.gz | strings | grep "<chain-name>"
    ```

    Run the `grep` once per chain in your `chainList.json` and confirm at least one match for **every** chain — a build that embeds chain A but drops chain B still produces a valid-looking hash. Zero matches means `KONA_CUSTOM_CONFIGS=true` was not set in the build shell, or `KONA_CUSTOM_CONFIGS_DIR` was a relative path.
  </Step>

  <Step title="Verify reproducibility">
    From a fresh checkout of the same tag with the same custom-configs files in place, repeat the build and confirm the hash is bit-identical. Anyone who wants to participate as an honest challenger on your chain must be able to reproduce this hash from the same inputs.
  </Step>
</Steps>

## Deploying and configuring with the custom prestate

<Steps>
  <Step title="Host the prestate binary">
    Upload `0x<hash>.bin.gz` to wherever you serve preimage files for `op-challenger` — typically a GCS bucket or HTTP endpoint. Files must be named by their absolute prestate hash so the challenger can resolve them on demand.
  </Step>

  <Step title="Register the custom prestate as game type 8">
    On the current (v2.4+) dispute-game contracts the absolute prestate is **not** a constructor argument — it lives in the `DisputeGameFactory`'s per-game-type `gameArgs`, appended to each game via clones-with-immutable-args. So you do **not** deploy a new implementation for a new prestate. Reuse the existing permissionless `FaultDisputeGame` implementation (a fresh op-deployer chain deploys one but leaves it unregistered) and register it for game type 8 with `gameArgs` that carry your prestate.

    `gameArgs` for a permissionless game is the packed encoding (124 bytes):

    ```
    abi.encodePacked(absolutePrestate, vm, anchorStateRegistry, weth, l2ChainId)
    ```

    Reuse `vm` / `anchorStateRegistry` / `weth` / `l2ChainId` from an existing registered game type (e.g. read `gameArgs(1)` and swap in your prestate), then register from the `DisputeGameFactory` owner:

    ```solidity theme={null}
    // GAME_TYPE_CANNON_KONA == 8
    DisputeGameFactory.setImplementation(8, faultDisputeGameImpl, gameArgs);
    DisputeGameFactory.setInitBond(8, initBond);            // 0 is fine for a dev/test chain
    ```

    Then make game type 8 the respected type from the Guardian role — `respectedGameType` lives on the `AnchorStateRegistry`, not the `OptimismPortal` (the portal proxies to it):

    ```solidity theme={null}
    AnchorStateRegistry.setRespectedGameType(8);
    ```

    See [Migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless) for the full role/transaction walkthrough. (On older, pre-v2.4 contracts where `absolutePrestate` was a constructor immutable, each prestate did require a fresh implementation deployment instead.)
  </Step>

  <Step title="Configure op-challenger">
    Add the kona-specific env vars to your existing challenger config:

    ```bash theme={null}
    OP_CHALLENGER_TRACE_TYPE=cannon-kona,permissioned
    OP_CHALLENGER_CANNON_KONA_PRESTATES_URL=<HTTP_URL_PATH_TO_PRESTATES>
    ```

    The challenger appends `/0x<hash>.bin.gz` to `*_PRESTATES_URL` to resolve the right binary per dispute. Your existing `OP_CHALLENGER_ROLLUP_CONFIG`, `OP_CHALLENGER_L2_GENESIS`, and `OP_CHALLENGER_GAME_FACTORY_ADDRESS` continue to apply unchanged.
  </Step>
</Steps>

## Next Steps

* [Upgrade 19 notice](/notices/archive/upgrade-19) — the `cannon-kona` game type promotion and reference build commands for the standard prestate.
* [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate): the standard `kona-client` prestate flow for chains in the Superchain Registry.
* [Generating an op-program absolute prestate (archived)](/chain-operators/tutorials/archive/op-program-prestate): the legacy `op-program` flow, kept only for resolving in-flight `CANNON` (game type `0`) disputes created before [Upgrade 19](/notices/archive/upgrade-19). `op-program` has reached end-of-support; see [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation).


# Upgrade L1 contracts using op-deployer
Source: https://docs.optimism.io/chain-operators/tutorials/l1-contract-upgrades/op-deployer-upgrade

Version availability and migration paths for the op-deployer upgrade command, which supports L1 contract upgrades up to op-contracts/v5.0.0.

<Warning>
  The `op-deployer upgrade` command can be used for upgrades up to `op-contracts/v5.0.0`. It does **not** support
  upgrading from `op-contracts/v5.0.0` to `op-contracts/v6.0.0`. For upgrades beyond v5.0.0, use
  [superchain-ops](/chain-operators/tutorials/l1-contract-upgrades/superchain-ops-guide) or interact with the
  OPCM directly. See the [deprecation notice](/notices/archive/op-deployer-upgrade-deprecation) for details.
</Warning>

## Version availability

The `op-deployer upgrade` command supports the following contract upgrade paths (upgrades must be performed in steps):

| Upgrade path                               | op-deployer version | Status    |
| ------------------------------------------ | ------------------- | --------- |
| op-contracts/v1.8.0 to op-contracts/v2.0.0 | v0.2.x              | Available |
| op-contracts/v2.0.0 to op-contracts/v3.0.0 | v0.3.x              | Available |
| op-contracts/v3.0.0 to op-contracts/v4.0.0 | v0.4.x              | Available |
| op-contracts/v4.0.0 to op-contracts/v5.0.0 | v0.5.x              | Available |

Each minor version of `op-deployer` supported a single release of the governance-approved smart contracts. See the [releases guide](/chain-operators/tools/op-deployer/reference/releases) for more information on versioning.

## Migration

For L1 contract upgrades beyond `op-contracts/v5.0.0`, use [superchain-ops](/chain-operators/tutorials/l1-contract-upgrades/superchain-ops-guide). For non-Optimism governed chains, you can interact with the OPCM directly using your own tooling.


# Upgrade using superchain-ops
Source: https://docs.optimism.io/chain-operators/tutorials/l1-contract-upgrades/superchain-ops-guide

Upgrade your chain's L1 contracts with superchain-ops by creating a task from a template, configuring and simulating it, then executing it or submitting it for review.

This guide outlines the process for upgrading Optimism chains using the `superchain-ops` repository. It's intended primarily for OP Stack chains managed by the Security Council, those with the Foundation or Security Council as signers, and/or chains requiring a highly secure process.

For chains that don't require the enhanced security of superchain-ops or security council signing, alternative upgrade tooling may be used. Note that the `op-deployer upgrade` command only supports upgrades [up to `op-contracts/v5.0.0`](/notices/archive/op-deployer-upgrade-deprecation).

For non-Optimism governed chains, you can use your own tooling to interact with the OPCM directly to upgrade your chain.

`superchain-ops` is a highly secure service designed for Optimism chains. It provides a structured and security-focused approach to chain upgrades. The process involves creating tasks that use predefined templates to generate the necessary upgrade transactions.

## Who should use `superchain-ops`

`superchain-ops` is primarily intended for:

1. **OP Stack chains managed by the Security Council**: For standard chains managed by the Optimism Security Council, upgrades are typically handled through `superchain-ops`.

2. **Chains with Foundation or Security Council as signers**: If your chain has the Foundation multi-sig or Security Council as signers, your upgrade tasks should go through `superchain-ops`.

3. **Chains requiring a highly secure process**: For chains that prioritize security over automation, `superchain-ops` provides an intentionally manual workflow with thorough verification steps (e.g. EVM state diff inspection).

For chains that don't fall into these categories, you'll need to generate appropriate call data for upgrades through other means or develop your own upgrade process for non-OPCM upgrades.

## Understanding templates and tasks

`superchain-ops` uses two key concepts:

* **Templates**: Define what the upgrade is and contain the code for specific upgrade paths (e.g., [`op-contracts/v1.8.0` to `op-contracts/v2.0.0`](https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/template/OPCMUpgradeV200.sol)). Templates are version-specific and live in the [/src/improvements/template](https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/template) directory.

* **Tasks**: Use a template to define a specific upgrade transaction for a chain. Multiple tasks can use the same template. Tasks are organized by network (`eth` or `sep`) in the [/src/improvements/tasks](https://github.com/ethereum-optimism/superchain-ops/tree/main/src/improvements/tasks) directory.

## General upgrade process

The following process outlines how to upgrade a chain using `superchain-ops`, using the [`op-contracts/v1.8.0` to `op-contracts/v2.0.0`](https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/template/OPCMUpgradeV200.sol) upgrade as an example. This same pattern applies to other OPCM-based upgrades (like [`op-contracts/v2.0.0` to `op-contracts/v3.0.0`](https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/template/OPCMUpgradeV300.sol)).

### Step 1: Clone the `superchain-ops` repository

```bash theme={null}
git clone https://github.com/ethereum-optimism/superchain-ops.git
cd superchain-ops/src/improvements
```

### Step 1a: One-time Install Dependencies Setup

Follow the 'Install Dependencies' instructions in the ['Quick Start'](https://github.com/ethereum-optimism/superchain-ops/blob/main/README.md#quick-start) section of the `README.md` file.

### Step 2: Create a new task using the quick start

```bash theme={null}
just new task
```

Follow the prompts to select the appropriate template (e.g., `OPCMUpgradeV200` for a `op-contracts/v1.8.0` to `op-contracts/v2.0.0` upgrade) and provide the necessary details.

This will create a new task directory containing a `config.toml` and `README` file. The config file will look like this:

```bash theme={null}
l2chains = [] # e.g. [{name = "OP Mainnet", chainId = 10}]
templateName = "OPCMUpgradeV200"
```

### Step 3: Configure the task

You'll have to add additional properties to your `config.toml` file to fully configure your task. For example, when upgrading from `op-contracts/v1.8.0` to `op-contracts/v2.0.0`, you can look at a previous task for reference: [src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml](https://github.com/ethereum-optimism/superchain-ops/blob/main/src/improvements/tasks/eth/002-opcm-upgrade-v200/config.toml):

<Info>
  This is an example task. You must figure out which values you'll need for your own specific task. Ensure you replace all addresses and other values in the example below.
</Info>

```bash theme={null}
l2chains = [
    {name = "Unichain", chainId = 130}
]

templateName = "OPCMUpgradeV200"

[opcmUpgrades]
absolutePrestates = [
    {absolutePrestate = "0x039facea52b20c605c05efb0a33560a92de7074218998f75bcdf61e8989cb5d9", chainId = 130},
]

[addresses]
OPCM = "0x026b2F158255Beac46c1E7c6b8BbF29A4b6A7B76"
StandardValidatorV200 = "0xecabaeaa1d58261f1579232520c5b460ca58a164"
```

### Step 5: Simulate the task

Before executing the upgrade, simulate it to ensure everything is configured correctly:

```bash theme={null}
just --dotenv-path $(pwd)/.env simulate [child-safe-name-depth-1] [child-safe-name-depth-2]
# Both [child-safe-name-depth-1] and [child-safe-name-depth-2] are optional. You'll only need to specify
# [child-safe-name-depth-2] if it's a nested safe and [child-safe-name-depth-2] if it has multiple levels of nesting.
# Omit both arguments if it's a single safe.
```

This will run through the upgrade process without actually executing the transaction.
For more information on the simulate command, please reference the [README](https://github.com/ethereum-optimism/superchain-ops/blob/main/README.md#quick-start).

### Step 6: Execute or submit for review

For OP Stack chains managed by the Security Council, submit a pull request to have your task reviewed. If your chain is not managed by the Security Council, execute the transaction yourself.


# Upgrading Smart Contracts from v1.3.0 to v1.8.0
Source: https://docs.optimism.io/chain-operators/tutorials/l1-contract-upgrades/upgrade-op-contracts-1-3-1-8

Upgrade your OP Stack chain's L1 contracts from op-contracts/v1.3.0 to v1.8.0, moving from the L2 Output Oracle to the permissioned Fault Proof System.

This guide provides specific instructions for upgrading the OP Stack's Layer 1 contracts from `op-contracts/v1.3.0` to `op-contracts/v1.8.0`. This upgrade includes important changes to the system configuration and introduces the Fault Proof System.

## Overview of the Holocene upgrade

The Holocene upgrade is a protocol upgrade. Learn more about it in the [Holocene notice page](https://docs.optimism.io/notices/holocene-changes). This guide shows you how to take your OP Stack chain from the L2 Output Oracle System to a permissioned Fault Proof System contract version associated with the Holocene upgrade.

After upgrading to OP Stack contracts v1.8.0 and enabling permissioned fault proofs, all pending (unfinalized) withdrawal proofs created on L1 are invalidated. This means that withdrawals must be manually reproven by users after the upgrade; the process is not automatic.

### Formatting config files

You need your chain's `deployments.json` and `deploy-config.json`

Ensure both files are correctly formatted, using the exact field names shown in the below examples, with **ALL** values - particularly the relevant ones - updated for **your specific chain**:

`deployments.json`:

```json theme={null}
{
  "AddressManager": "0xEF8115F2733fb2033a7c756402Fc1deaa56550Ef",
  "L2OutputOracleProxy": "0x9E6204F750cD866b299594e2aC9eA824E2e5f95c",
  "OptimismMintableERC20FactoryProxy": "0xc52BC7344e24e39dF1bf026fe05C4e6E23CfBcFf",
  "L1StandardBridgeProxy": "0x3e2Ea9B92B7E48A52296fD261dc26fd995284631",
  "ProxyAdmin": "0xD4ef175B9e72cAEe9f1fe7660a6Ec19009903b49",
  "L1CrossDomainMessengerProxy": "0xdC40a14d9abd6F410226f1E6de71aE03441ca506",
  "L1ERC721BridgeProxy": "0x83A4521A3573Ca87f3a971B169C5A0E1d34481c3",
  "OptimismPortalProxy": "0x1a0ad011913A150f69f6A19DF447A0CfD9551054",
  "SystemConfigProxy": "0xA3cAB0126d5F504B071b81a3e8A2BBBF17930d86"
}
```

`deploy-config.json`:

```json theme={null}
{
  "l1StartingBlockTag": "0x10aa183",
  "l1ChainID": 1,
  "l2ChainID": 7777777,
  "l2BlockTime": 2,
  "finalizationPeriodSeconds": 604800,
  "controller": "0xEe729F57F0111FD0F660867d0F522f983202a5aF",
  "baseFeeVaultRecipient": "0xe900b3Edc1BA0430CFa9a204A1027B90825ac951",
  "l1FeeVaultRecipient": "0xe900b3Edc1BA0430CFa9a204A1027B90825ac951",
  "sequencerFeeVaultRecipient": "0xe900b3Edc1BA0430CFa9a204A1027B90825ac951",
  "l2GenesisBlockBaseFeePerGas": "0x3b9aca00",
  "governanceTokenOwner": "0xC72aE5c7cc9a332699305E29F68Be66c73b60542",
  "governanceTokenSymbol": "OP",
  "governanceTokenName": "Optimism",
  "maxSequencerDrift": 600,
  "sequencerWindowSize": 3600,
  "channelTimeout": 300,
  "p2pSequencerAddress": "0x3Dc8Dfd0709C835cAd15a6A27e089FF4cF4C9228",
  "optimismL2FeeRecipient": "0x63AA492609175d1824dD668BDadF0042E74b0fC8",
  "batchInboxAddress": "0x6F54Ca6F6EdE96662024Ffd61BFd18f3f4e34DFf",
  "batchSenderAddress": "0x625726c858dBF78c0125436C943Bf4b4bE9d9033",
  "l2GenesisRegolithTimeOffset": "0x0",
  "l2OutputOracleSubmissionInterval": 180,
  "l2OutputOracleStartingTimestamp": -1,
  "l2OutputOracleStartingBlockNumber": "0x0",
  "l2GenesisBlockGasLimit": "0x1c9c380",
  "fundDevAccounts": false,
  "gasPriceOracleOverhead": 188,
  "gasPriceOracleScalar": 684000,
  "eip1559Denominator": 50,
  "eip1559Elasticity": 6,
  "optimismBaseFeeRecipient": "0xea4591A6e5a31CF0b822A4f563163CeeBeEe4eb1",
  "optimismL1FeeRecipient": "0xdD7aCF916c3E3Fb959CA3bB29beFffcAD2e90be6",
  "l2CrossDomainMessengerOwner": "0xA53EF9bBec25fdA4b6Da7EF5617565794369A2A5",
  "gasPriceOracleOwner": "0x9c3651E0B3CE47A0b17d775077E3d9B712582be0",
  
- RELEVANT VALUES
  "systemConfigOwner": "0xC72aE5c7cc9a332699305E29F68Be66c73b60542",
  "finalSystemOwner": "0xC72aE5c7cc9a332699305E29F68Be66c73b60542",
  "superchainConfigGuardian": "0x9BA6e03D8B90dE867373Db8cF1A58d2F7F006b3A",
  "portalGuardian": "0xC72aE5c7cc9a332699305E29F68Be66c73b60542",
  "l2OutputOracleProposer": "0x48247032092e7b0ecf5dEF611ad89eaf3fC888Dd",
  "l2OutputOracleOwner": "0xDA1F62857EA7f10444725c6c435235243D623540",
  "proxyAdmin": "0x027860cA56cF779371461C14c3a483c94e1aA8a0",
  "proxyAdminOwner": "0xb0cCdbD6fe09D2199171BE19450aF249250518A0",
  "l2OutputOracleChallenger": "0xcA4571b1ecBeC86Ea2E660d242c1c29FcB55Dc72",

- add the below default values, if you expect different values for your chain reach out to OP Labs support for clarification before proceeding
  "useFaultProofs": true,
  "faultGameMaxDepth": 73,
  "faultGameSplitDepth": 30,
  "faultGameWithdrawalDelay": 604800,
  "faultGameMaxClockDuration": 302400,
  "faultGameClockExtension": 10800,
  
- You can update this to the latest absolute prestate hash in the superchain-registry; however, the permissioned Fault Proof System doesn't use this. This comes into play when you upgrade your chain to the permissionless Fault Proof System.
  "faultGameAbsolutePrestate": "0x03925193e3e89f87835bbdf3a813f60b2aa818a36bbe71cd5d8fd7e79f52bafe",
  
- add the below default values, if you expect different values for your chain, reach out to OP Labs support for clarification before proceeding  
  "faultGameGenesisBlock": 0,
  "faultGameGenesisOutputRoot": "0xdead000000000000000000000000000000000000000000000000000000000000",
  "respectedGameType": 1,
  "preimageOracleMinProposalSize": 126000,
  "preimageOracleChallengePeriod": 86400,
  "proofMaturityDelaySeconds": 604800,
  "disputeGameFinalityDelaySeconds": 302400,
  "enableGovernance": false,
  "systemConfigStartBlock": 0,
  "requiredProtocolVersion": "0x0000000000000000000000000000000000000003000000010000000000000000",
  "recommendedProtocolVersion": "0x0000000000000000000000000000000000000003000000010000000000000000",
  
- make sure to add the below if not present already, these values won't matter but the script needs them to be present in the config  
  "sequencerFeeVaultWithdrawalNetwork": 0,
  "baseFeeVaultWithdrawalNetwork": 0,
  "l1FeeVaultWithdrawalNetwork": 0,
  "baseFeeVaultMinimumWithdrawalAmount": "0x8ac7230489e80000",
  "l1FeeVaultMinimumWithdrawalAmount": "0x8ac7230489e80000",
  "sequencerFeeVaultMinimumWithdrawalAmount": "0x8ac7230489e80000"
}
```

Make sure that important addresses (like the `ProxyAdmin`, `ProxyAdminOwner`, all L1 addresses, `L2OO`) are actually up to date by cross checking the superchain-registry and on-chain (you can do this easily with [`op-fetcher`](https://github.com/ethereum-optimism/optimism/tree/develop/op-fetcher), especially for the `deployments.json`.

## Step-by-step upgrade process

### 1. Create your working directory

Create a working directory:

```shell theme={null}
mkdir upgrade-dir
cd upgrade-dir
```

And then create an outputs directory:

```shell theme={null}
mkdir outputs
```

### 2. Copy config files

Copy your `deployments.json` and `deploy-config.json` into the working directory

### 3. Configure and deploy environment

Create and update an `.env` file with the required information:

```json theme={null}
##############################################
#               ↓  Required  ↓               #
##############################################

# Can be "mainnet" or "sepolia"
NETWORK=

# Etherscan API key used to verify contract bytecode
ETHERSCAN_API_KEY=

# RPC URL for the L1 network that matches $NETWORK
ETH_RPC_URL=

# Private key used to deploy the new contracts for this upgrade
PRIVATE_KEY=

# Base fee scalar for the SystemConfig
BASE_FEE_SCALAR=

# Blob base fee scalar for the SystemConfig
BLOB_BASE_FEE_SCALAR=

# Check if required files and folders exist
if [ ! -f "./deploy_config.json" ]; then
    echo "Error: deploy_config.json not found"
fi
if [ ! -f "./deployments.json" ]; then
    echo "Error: deployments.json not found"
fi
if [ ! -d "./outputs" ]; then
    echo "Error: outputs folder not found"
fi
```

### 4. Run the deployment process

Run the deployment process with the following command:

```docker theme={null}
    docker run -t
    --env-file .env
    -v ./deploy_config.json:/deploy_config.json
    -v ./deployments.json:/deployments.json
    -v ./outputs:/outputs
    kfoplabs/upgrade-v1.3.0-v1.8.0-permissioned /deploy_config.json /deployments.json
```

The source code for the `kfoplabs/upgrade-v1.3.0-v1.8.0-permissioned` image is available in the [`perm/op-contracts/v1.8.0` branch of the Optimism monorepo](https://github.com/ethereum-optimism/optimism/tree/perm/op-contracts/v1.8.0). If you need to fork or customize the upgrade script (e.g. to support L3s), start from that branch.

### 5. Verify outputs

The deployment should output four files:

* `deploy.log` is a log of the deployment process
* `deployments.json` includes the newly deployed contract addresses
* `bundle.json` is the safe transaction bundle
* `transactions.json` is the summary of the executed deployment transactions
* `standard-addresses.json` is the addresses of `SystemConfigImpl`, `OptimismPortal2Impl`, `L1CrossDomainMessengerImpl`, `L1StandardBridgeImpl`, `L1ERC721BridgeImpl`, and `OptimismMintableERC20FactoryImpl`
* `validation.txt` is used for Tenderly state diff validation. Some info needed for the superchain-ops task might be missing from this file, and will instead be generated during the Tenderly simulation.

### 6. Verify outputs

Now you have the calldata that can be executed onchain to perform the L1 contract upgrade. You should simulate this upgrade and make sure the changes are expected. You can reference the validation files of previously executed upgrade tasks in the [superchain-ops repo](https://github.com/ethereum-optimism/superchain-ops/blob/main/tasks/eth/022-holocene-fp-upgrade/NestedSignFromJson.s.sol) to see what the expected changes are. Once you're confident the state changes are expected, you can sign and execute the upgrade.

## Additional Resources

* [superchain-ops Repository](https://github.com/ethereum-optimism/superchain-ops)
* [Optimism Monorepo](https://github.com/ethereum-optimism/optimism)
* [Upgrade script source code (`perm/op-contracts/v1.8.0` branch)](https://github.com/ethereum-optimism/optimism/tree/perm/op-contracts/v1.8.0)


# Merging Two Chains Into a Shared Dispute Game
Source: https://docs.optimism.io/chain-operators/tutorials/merge-shared-dispute-game

Merge two pre-interop OP Stack chains into a shared DisputeGameFactory and AnchorStateRegistry with opcm.migrate, then cut over op-proposer, op-challenger, and op-dispute-mon to the shared factory.

# Merging Two Chains Into a Shared Dispute Game

<Warning>This guide depends on the interop feature, which is still in development. Do not follow it on production chains.</Warning>

This runbook walks you through merging two existing OP Stack chains into a shared dispute game by calling `OPContractsManagerMigrator.migrate` (`opcm.migrate`). After migration, both chains share a newly deployed `DisputeGameFactory`, `AnchorStateRegistry`, and `ETHLockbox`. New proposals are super-root claims defended on the shared factory; the per-chain dispute game factories are emptied of implementations and exist only to let still-in-flight games resolve so their bonds can be reclaimed.

By the end you will have one `op-proposer` proposing super-root claims to the shared factory against an `op-supernode` that derives both chains, one `op-challenger` defending super-root games on the shared factory, one `op-dispute-mon` watching it, and per-chain `op-challenger` and `op-dispute-mon` "drain" instances — each using that shared op-supernode's `/<chainID>/` endpoint — winding down the retired games on the old per-chain factories.

<Warning>`opcm.migrate` is a one-way operation that invalidates every withdrawal proof submitted but not finalized on either chain. Affected users must re-prove against a new super-root game after migration. Announce the migration window to users at least seven days in advance—long enough for a withdrawal proven just before the announcement to mature past `PROOF_MATURITY_DELAY_SECONDS` and finalize.</Warning>

If you instead want to swap a single chain's proof method from output roots to super roots without merging chains, follow [Upgrading a Chain From Output Roots to Super Roots](/chain-operators/tutorials/upgrade-chain-to-super-roots). This runbook is for two chains that are merging into a shared interop set.

## Before You Begin

<SuperchainOpsPrereqs />

This runbook assumes:

* Exactly two chains, referred to below as `chainA` and `chainB`, are being merged.
* Neither chain has activated interop yet.
* Both chains run permissionless fault proofs with `SUPER_CANNON_KONA` (game type `9`) as the respected game type today.
* The per-chain `op-proposer`, `op-challenger`, and `op-dispute-mon` instances stood up by the [single-chain super-roots upgrade](/chain-operators/tutorials/upgrade-chain-to-super-roots) are running for both chains. The per-chain challengers and monitors keep running through migration cutover and the subsequent drain window.
* A separate `op-supernode` instance is in sync and derives **exactly `chainA` and `chainB`** (and no other chains) in the same process. This is the supernode the new shared `op-proposer`, `op-challenger`, and `op-dispute-mon` point at after migration; it must not double as a multi-chain supernode for any other chain or interop cluster.
* Both chains have already been upgraded to a release that exposes `OPContractsManagerMigrator.migrate` and have `Features.INTEROP` and `Features.ETH_LOCKBOX` enabled on their `SystemConfig`. These features are turned on automatically by `OPContractsManagerV2.upgrade()` when the OPCM container has the `OPTIMISM_PORTAL_INTEROP` dev feature set; that pre-upgrade is a prerequisite for this runbook.

### Install Required Tooling

The versions below are the ones the optimism repo's `mise.toml` pins; older versions of `cast` in particular may not parse the function-selector syntax used in this runbook.

| Tool                        | Minimum version |
| --------------------------- | --------------- |
| `foundry` (`cast`, `forge`) | `1.2.3`         |
| `just`                      | `1.46.0`        |
| `jq`                        | `1.7.1`         |
| `go`                        | `1.26.5`        |
| `curl`                      | any             |

### Gather the Required Inputs

Collect everything below before you start. Replace `<chainA>` and `<chainB>` placeholders with the actual values for each chain. Anywhere this runbook says `<X>` it means a value you must capture.

**Per-chain identity, addresses, and roles.** For each chain, open the entry under `superchain/configs/<network>/<chain-name>.toml` in `superchain-registry` and read `chain_id`, `addresses.SystemConfigProxy`, and `addresses.L1StandardBridgeProxy`. Pass those two proxies to [`op-fetcher`](https://github.com/ethereum-optimism/optimism/tree/develop/op-fetcher) to resolve the rest in a single L1 call, writing the JSON to a file you can reference later:

```bash theme={null}
op-fetcher fetch \
  --l1-rpc-url $L1_RPC \
  --system-config <SystemConfigProxy> \
  --l1-standard-bridge <L1StandardBridgeProxy> \
  --output-file <chainX>.json
```

The portal-derived lookups return the chain's current `DisputeGameFactory`, `AnchorStateRegistry`, and `ETHLockbox` while migration has not yet run; after migration, the same selectors return the new shared addresses, so capture both chains' values now. Capture the following fields from each chain's JSON output:

| Item                                                     | Source                                                         |
| -------------------------------------------------------- | -------------------------------------------------------------- |
| L2 chain ID                                              | `chain_id` in the chain's registry TOML                        |
| `SystemConfig` proxy                                     | `addresses.SystemConfigProxy` in the chain's registry TOML     |
| `L1StandardBridge` proxy                                 | `addresses.L1StandardBridgeProxy` in the chain's registry TOML |
| `OptimismPortal2` proxy                                  | `addresses.OptimismPortalProxy` in `<chainX>.json`             |
| Existing `AnchorStateRegistry` proxy (`<oldASR_chainX>`) | `addresses.AnchorStateRegistryProxy` in `<chainX>.json`        |
| Existing `DisputeGameFactory` proxy (`<oldDGF_chainX>`)  | `addresses.DisputeGameFactoryProxy` in `<chainX>.json`         |
| Existing `ETHLockbox` proxy                              | `addresses.EthLockboxProxy` in `<chainX>.json`                 |
| `SuperchainConfig` proxy                                 | `addresses.SuperchainConfigProxy` in `<chainX>.json`           |
| `ProxyAdmin` owner Safe                                  | `roles.OpChainProxyAdminOwner` in `<chainX>.json`              |

`migrate` reads each chain's `DelayedWETH` directly from `SystemConfig.delayedWETH()` at execution time, so there is nothing to capture for it here.

**Init bonds.** The migration registers two super game types on the new shared factory. `SUPER_PERMISSIONED` (game type `5`) is bondless and must use an `initBond` of `0`. `SUPER_CANNON_KONA` (game type `9`) uses `0.08 ether` (`80000000000000000` wei).

**Release artifacts and infrastructure.**

| Item                                             | Source                                                                                                                                                                                                                                                                                                                 |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPCM` address for the migrate-feature container | The same OPCM the chains ran for the prerequisite `OPCMv2.upgrade()`. The container has `OPTIMISM_PORTAL_INTEROP` set in `devFeatureBitmap`, which is what enables both `Features.INTEROP` and `Features.ETH_LOCKBOX` on each `SystemConfig`.                                                                          |
| `SUPER_CANNON_KONA` absolute prestate hash       | `validation/standard/standard-prestates.toml` in `superchain-registry`. Use the entry with `type="interop"` for the OPCM release version.                                                                                                                                                                              |
| Prestate artifact URL                            | The `cannon-kona-prestates-url` server, with the kona-interop prestate uploaded ahead of the migration.                                                                                                                                                                                                                |
| Shared `op-supernode` RPC URL                    | Your infrastructure team. The instance must derive **exactly `chainA` and `chainB`** (and no other chains). The shared `op-proposer`, `op-challenger`, and `op-dispute-mon` for the merged factory all point at this same instance. The per-chain services will be pointed to chain-specific endpoints under this URL. |
| Privileged `proposer` for `SUPER_PERMISSIONED`   | The address authorized to post proposals to the permissioned super game. `op-proposer` is configured to sign with this key.                                                                                                                                                                                            |

### Verify the Preconditions

Run every check below. Each one corresponds to an invariant the migrator enforces; resolve any failure before proceeding.

* **Confirm the same `ProxyAdmin` owner across both chains.** `migrate` reverts with `OPContractsManagerMigrator_ProxyAdminOwnerMismatch` otherwise. Each chain's `ProxyAdmin` proxy may differ as long as the owner Safe is identical on both.

  ```bash theme={null}
  diff <(jq -r '.roles.OpChainProxyAdminOwner' <chainA>.json) <(jq -r '.roles.OpChainProxyAdminOwner' <chainB>.json)
  # Expect: no output (identical).
  ```

* **Confirm the same `SuperchainConfig` across both chains.** `migrate` reverts with `OPContractsManagerMigrator_SuperchainConfigMismatch` otherwise.

  ```bash theme={null}
  diff <(jq -r '.addresses.SuperchainConfigProxy' <chainA>.json) <(jq -r '.addresses.SuperchainConfigProxy' <chainB>.json)
  # Expect: no output (identical).
  ```

* **Confirm both chains have `Features.INTEROP` and `Features.ETH_LOCKBOX` enabled.** `_migratePortal` reverts with `OPContractsManagerMigrator_InteropFeatureNotEnabled` or `OPContractsManagerMigrator_EthLockboxFeatureNotEnabled` if either is missing. These flip automatically during the prerequisite `OPCMv2.upgrade()` against an `OPTIMISM_PORTAL_INTEROP`-enabled OPCM container; if any of the four checks below returns `false`, run that prerequisite upgrade first. `Features` constants are short-string `bytes32` values, so feed them through `cast format-bytes32-string`.

  ```bash theme={null}
  for SC in <SystemConfig_chainA> <SystemConfig_chainB>; do
      for F in INTEROP ETH_LOCKBOX; do
          echo "$SC $F = $(cast call $SC 'isFeatureEnabled(bytes32)(bool)' "$(cast format-bytes32-string $F)" --rpc-url $L1_RPC)"
      done
  done
  # Expect: every line ends in true.
  ```

* **Confirm neither chain runs in Custom Gas Token mode.** `_migratePortal` reverts with `OPContractsManagerMigrator_CustomGasTokenNotSupported` for any CGT chain.

  ```bash theme={null}
  cast call <SystemConfig_chainA> 'isCustomGasToken()(bool)' --rpc-url $L1_RPC
  cast call <SystemConfig_chainB> 'isCustomGasToken()(bool)' --rpc-url $L1_RPC
  # Expect: both false.
  ```

* **Confirm the current respected game type on both chains is `SUPER_CANNON_KONA` (`9`).**

  ```bash theme={null}
  cast call <oldASR_chainA> 'respectedGameType()(uint32)' --rpc-url $L1_RPC
  cast call <oldASR_chainB> 'respectedGameType()(uint32)' --rpc-url $L1_RPC
  # Expect: 9 for both.
  ```

* **Confirm the shared supernode derives exactly the two merging chains.** Verify with your infrastructure team that the instance behind `$SUPERNODE_RPC` has `chainA` and `chainB` in its dependency set and **no** other chains. A supernode that also tracks an unrelated chain (or an interop cluster that includes one) computes super roots over that broader set, and those roots will not match what the shared `SUPER_CANNON_KONA` and `SUPER_PERMISSIONED` games verify.

* **Confirm the shared supernode is in sync.** It must report a finalized L2 head within both chains' expected finality windows:

  ```bash theme={null}
  cast rpc supernode_syncStatus --rpc-url $SUPERNODE_RPC | jq -r '.finalized_timestamp'
  ```

  If the supernode is materially behind either chain, postpone the migration.

* **Confirm the prestate server serves the `SUPER_CANNON_KONA` prestate.**

  ```bash theme={null}
  curl -fI "$PRESTATE_URL/$SUPER_CANNON_KONA_PRESTATE.bin.gz"
  ```

* **Note the chain B `DelayedWETH` divergence.** `migrate` reuses chain A's `DelayedWETH` for the new shared super games and does not touch chain B's. After migration, chain B's `SystemConfig.delayedWETH()` still references chain B's old `DelayedWETH`, which is no longer attached to any super game. Future `OPCMv2.upgrade()` calls against chain B that read `SystemConfig.delayedWETH()` will therefore reference a different contract than the shared games use. Track this in your operational runbook so future upgrades do not surprise you. The bonds posted by chain B's still-in-flight pre-migration games continue to claim out of chain B's old `DelayedWETH`, so the divergence does not block the drain described in [Drain Pre-Migration Games and Reclaim Bonds](#drain-pre-migration-games-and-reclaim-bonds).

## Stage the Off-Chain Configuration

Apply these changes before you submit the on-chain migration. The pre-migration `op-challenger` and `op-dispute-mon` instances per chain must keep running to defend and watch in-flight games on the per-chain factories until those games resolve. Add a third instance of each component for the shared factory. Stop both per-chain `op-proposer` instances at cutover time, in [Execute the Migration](#execute-the-migration).

### Point Per-Chain Services at the Shared op-supernode

Before migration, point every existing per-chain service at its chain's RPC namespace on the shared op-supernode:

| Service flag                     | chainA value                      | chainB value                      |
| -------------------------------- | --------------------------------- | --------------------------------- |
| `op-proposer --superroot-rpcs`   | `$SUPERNODE_RPC/$CHAIN_A_CHAINID` | `$SUPERNODE_RPC/$CHAIN_B_CHAINID` |
| `op-challenger --supernode-rpc`  | `$SUPERNODE_RPC/$CHAIN_A_CHAINID` | `$SUPERNODE_RPC/$CHAIN_B_CHAINID` |
| `op-dispute-mon --supernode-rpc` | `$SUPERNODE_RPC/$CHAIN_A_CHAINID` | `$SUPERNODE_RPC/$CHAIN_B_CHAINID` |

Do not point these per-chain instances at `$SUPERNODE_RPC` without the chain ID suffix; the root endpoint returns a two-chain super root. Restart each service and confirm it connects successfully before continuing. This removes the operational dependency on separate single-chain op-node or op-supernode processes before interop activation.

### Stand Up a Shared op-challenger

A single `op-challenger` process can only watch one `DisputeGameFactory`, so the existing per-chain instances cannot also cover the new shared factory. Run a third `op-challenger` instance dedicated to the shared factory in addition to the existing per-chain instances.

Configure the new shared instance with the flags below.

| Flag (env var)                                                            | Value                                                                                                                                                                                                                                                                                           |
| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--game-factory-address` (`OP_CHALLENGER_GAME_FACTORY_ADDRESS`)           | The new shared `<DGF>` (capture from chain A's portal after [Execute the Migration](#execute-the-migration))                                                                                                                                                                                    |
| `--superroot-rpc` (`OP_CHALLENGER_SUPERNODE_RPC`)                         | `$SUPERNODE_RPC`                                                                                                                                                                                                                                                                                |
| `--l2-eth-rpc` (`OP_CHALLENGER_L2_ETH_RPC`)                               | `<chainA-EL>,<chainB-EL>` (comma-separated)                                                                                                                                                                                                                                                     |
| `--game-types` (`OP_CHALLENGER_GAME_TYPES`)                               | `super-cannon-kona`. Do not add `super-permissioned`; the simplified `SUPER_PERMISSIONED` game does not require `op-challenger` to post claims. `op-challenger` is still required by permissioned only networks and will automatically update the `AnchorStateRegistry` as games are finalized. |
| `--network` (`OP_CHALLENGER_NETWORK`)                                     | `<chainA-network>,<chainB-network>` (the registry chain names; the challenger loads the depset from `superchain-registry` the same way `op-supernode` does)                                                                                                                                     |
| `--cannon-kona-prestates-url` (`OP_CHALLENGER_CANNON_KONA_PRESTATES_URL`) | The prestate server URL validated in the preconditions                                                                                                                                                                                                                                          |

If either chain is not in `superchain-registry`, omit `--network` and instead pass each chain's rollup config and L2 genesis as comma-separated paths via `--rollup-config` (`OP_CHALLENGER_ROLLUP_CONFIG`) and `--l2-genesis` (`OP_CHALLENGER_L2_GENESIS`), plus the shared depset via `--depset-config` (`OP_CHALLENGER_DEPSET_CONFIG`).

The shared instance's `--game-factory-address` is the new shared factory, which only exists once `migrate` has been broadcast. Stage the deployment now with every other flag set; the address is filled in and the process is started in [Start the Shared op-challenger and op-dispute-mon](#start-the-shared-op-challenger-and-op-dispute-mon) after the migration is verified on-chain.

Keep the per-chain `op-challenger` instances running with the namespaced RPC configuration for the duration of the drain window.

### Stand Up a Shared op-dispute-mon

`op-dispute-mon` is also single-factory per process. Run a third instance pointed at the new shared factory in addition to the two per-chain instances.

| Flag (env var)                                                   | Value                                                                                                      |
| ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `--game-factory-address` (`OP_DISPUTE_MON_GAME_FACTORY_ADDRESS`) | The new shared `<DGF>`                                                                                     |
| `--superroot-rpc` (`OP_DISPUTE_MON_SUPERNODE_RPC`)               | `$SUPERNODE_RPC` or a comma-separated list of high-availability root endpoints for the same dependency set |
| `--l1-eth-rpc` (`OP_DISPUTE_MON_L1_ETH_RPC`)                     | unchanged                                                                                                  |

As with the shared `op-challenger`, stage the deployment now with every flag except `--game-factory-address`; the address is filled in and the process is started in [Start the Shared op-challenger and op-dispute-mon](#start-the-shared-op-challenger-and-op-dispute-mon) after the migration is verified on-chain.

Keep both per-chain `op-dispute-mon` instances running with the namespaced RPC configuration so they continue to track in-flight pre-migration games to resolution.

### Leave Other op-proposer Settings Unchanged for Now

After switching the per-chain `op-proposer` RPC endpoints above, leave their other settings unchanged until [Execute the Migration](#execute-the-migration). Stop both per-chain proposers at cutover and replace them with a single shared one; see [Cut Over to a Single Shared op-proposer](#cut-over-to-a-single-shared-op-proposer).

## Generate the Starting Anchor Super Root

The new shared `AnchorStateRegistry` is initialized with a starting anchor super root. Compute the value from the supernode using `superroot_atTimestamp`. Pick the supernode's current finalized timestamp (or any recent finalized timestamp), then ask the supernode for the super root at that timestamp:

```bash theme={null}
# .finalized_timestamp is a JSON number (decimal unix seconds).
TS=$(cast rpc supernode_syncStatus --rpc-url $SUPERNODE_RPC | jq -r '.finalized_timestamp')
# superroot_atTimestamp expects a hex-encoded JSON string (hexutil.Uint64); cast 2h handles the conversion.
cast rpc superroot_atTimestamp "$(cast 2h $TS)" --rpc-url $SUPERNODE_RPC | jq -r '.data.super_root'
echo "timestamp=$TS"
```

Capture two values:

* `super_root` (a `bytes32` hash from `.data.super_root`)—passed as `Proposal.root` in `startingAnchorRoot`.
* `timestamp` (the uint64 you passed in)—passed as `Proposal.l2SequenceNumber`. For super games this field is the timestamp itself, not a block number.

## Build the superchain-ops Task

Author a new task directory under `superchain-ops/src/tasks/<network>/<NNN-name>/` using the `OPCMMigrateInterop` template, which wraps `OPContractsManagerMigrator.migrate(MigrateInput)` and runs `OPContractsManagerMigrationValidator` over the resulting state.

### Configure config.toml

```toml theme={null}
l2chains = [
    {name = "<chainA name>t stat", chainId = <chainA id>},
    {name = "<chainB name>", chainId = <chainB id>},
]

templateName = "OPCMMigrateInterop"

[addresses]
OPCM = "0x<OPCM address with OPTIMISM_PORTAL_INTEROP enabled>"

# One stanza per chain, both required.
[[migrateChains]]
chainId = <chainA id>
systemConfigProxy = "0x<SystemConfig_chainA>"

[[migrateChains]]
chainId = <chainB id>
systemConfigProxy = "0x<SystemConfig_chainB>"

# Starting anchor for the new shared AnchorStateRegistry, computed in the previous step.
[startingAnchorRoot]
root = "0x<super root hash>"
l2SequenceNumber = <timestamp>

# 9 = SUPER_CANNON_KONA. Required because both chains run permissionless fault proofs today.
startingRespectedGameType = 9

# Both super game types must be registered. The migration validator requires it.
# The template assembles the on-chain DisputeGameConfig.gameArgs bytes from these
# fields: abi.encode(absolutePrestate) for game type 9, and
# abi.encode(proposer) for game type 5.

[[disputeGameConfigs]]
gameType = 9                             # SUPER_CANNON_KONA
enabled = true
initBond = 80000000000000000             # match the value gathered in the inputs
absolutePrestate = "0x<super-cannon-kona prestate>"

[[disputeGameConfigs]]
gameType = 5                             # SUPER_PERMISSIONED
enabled = true
initBond = 0                             # SUPER_PERMISSIONED does not charge init bonds
proposer = "0x<privileged proposer>"

expectedValidationErrors = ""            # fill in after the dry run if any structurally expected codes appear
```

### Capture expectedValidationErrors

Run the task in simulation mode against an L1 fork from inside the task directory:

```bash theme={null}
cd superchain-ops/src/tasks/<network>/<NNN-name>
just simulate
```

The validator behind `OPContractsManagerMigrationValidator` returns a comma-separated string of error codes when something is structurally wrong. The default expectation is no errors—`expectedValidationErrors = ""` and a clean simulation. The codes you may see fall into the families below. Resolve every code rather than copy-pasting it into `expectedValidationErrors`; a code added to that field must have an inline TOML comment explaining why it is structurally expected for this migration.

| Code                          | Meaning                                                                                                                                                                                                                                                                    |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MIG-DGF-10`                  | `SUPER_PERMISSIONED` is not registered on the shared factory.                                                                                                                                                                                                              |
| `MIG-DGF-20`                  | `SUPER_CANNON_KONA` is not registered on the shared factory.                                                                                                                                                                                                               |
| `MIG-DGF-30`                  | `CANNON` is still registered on the shared factory.                                                                                                                                                                                                                        |
| `MIG-DGF-40`                  | `PERMISSIONED_CANNON` is still registered on the shared factory.                                                                                                                                                                                                           |
| `MIG-DGF-50`                  | `CANNON_KONA` is still registered on the shared factory.                                                                                                                                                                                                                   |
| `MIG-SDGF-10` to `-40`        | Shared factory version, proxy implementation pointer, owner, or `ProxyAdmin` does not match the expected configuration.                                                                                                                                                    |
| `MIG-SASR-RGT`                | Shared `AnchorStateRegistry.respectedGameType()` is not a super game type.                                                                                                                                                                                                 |
| `MIG-SLOCKBOX-10` to `-30`    | Shared lockbox version, proxy implementation pointer, or `ProxyAdmin` mismatch.                                                                                                                                                                                            |
| `MIG-CHAIN-EMPTY`             | The validator received an empty chain list.                                                                                                                                                                                                                                |
| `MIG-LOCKBOX-MISSING`         | Chain A's portal does not point at the shared lockbox.                                                                                                                                                                                                                     |
| `MIG-CHAIN-{i}-10`            | Chain `i`'s portal does not reference the shared `AnchorStateRegistry`.                                                                                                                                                                                                    |
| `MIG-CHAIN-{i}-20`            | Chain `i`'s per-chain factory still has `CANNON` registered.                                                                                                                                                                                                               |
| `MIG-CHAIN-{i}-30`            | Chain `i`'s per-chain factory still has `PERMISSIONED_CANNON` registered.                                                                                                                                                                                                  |
| `MIG-CHAIN-{i}-40`            | Chain `i`'s per-chain factory still has `CANNON_KONA` registered.                                                                                                                                                                                                          |
| `MIG-CHAIN-{i}-60`            | Chain `i`'s per-chain factory still has `SUPER_PERMISSIONED` registered.                                                                                                                                                                                                   |
| `MIG-CHAIN-{i}-70`            | Chain `i`'s per-chain factory still has `SUPER_CANNON_KONA` registered.                                                                                                                                                                                                    |
| `MIG-CHAIN-{i}-80`            | Shared lockbox does not list chain `i`'s portal as authorized.                                                                                                                                                                                                             |
| `MIG-CHAIN-{i}-90`            | Chain `i`'s portal `ethLockbox` does not equal the shared lockbox.                                                                                                                                                                                                         |
| `MIG-CHAIN-{i}-100`           | Chain `i`'s `SystemConfig` does not have `Features.INTEROP` enabled.                                                                                                                                                                                                       |
| `MIG-CHAIN-{i}-110`           | Chain `i`'s `SystemConfig` does not have `Features.ETH_LOCKBOX` enabled.                                                                                                                                                                                                   |
| `MIG-SPDG-*` or `MIG-SCKDG-*` | Super game drill-down. The first prefix covers `SUPER_PERMISSIONED` and the second covers `SUPER_CANNON_KONA`. `MIG-SPDG-*` subcodes cover the simplified permissioned game's args, proposer, and `AnchorStateRegistry`; `MIG-SCKDG-*` covers the fault-proof game checks. |

## Execute the Migration

<Warning>Verify that the user announcement has gone out and at least seven days have elapsed since the announcement before broadcasting. Withdrawals proven against either chain's old games will not finalize against the new shared registry; users must re-prove or finalize ahead of cutover.</Warning>

1. Stop both per-chain `op-proposer` processes. Once the migration broadcasts, the per-chain factories no longer have `SUPER_CANNON_KONA` registered, so `DisputeGameFactory.create` reverts. Stopping the proposers first prevents wasted gas.
2. Leave both per-chain `op-challenger` and `op-dispute-mon` instances running. They continue to defend and observe in-flight pre-migration games on the per-chain factories.
3. Sign and broadcast the task using your team's standard `superchain-ops` signing workflow.
4. Wait for the L1 transaction to confirm.

The on-chain effect:

* `OPCM` deploys and initializes new `ETHLockbox`, `DisputeGameFactory`, and `AnchorStateRegistry` proxies. The new `AnchorStateRegistry` binds to the new factory and sets `retirementTimestamp` to `block.timestamp` at initialization.
* `OPCM` calls `OptimismPortal2.migrateToSharedDisputeGame` on each chain to repoint the portal at the new lockbox and the new `AnchorStateRegistry`. It also authorizes each chain's existing portal on the shared lockbox, authorizes each chain's existing lockbox to forward liquidity, and migrates that liquidity into the shared lockbox.
* `OPCM` zeroes every implementation pointer on each chain's existing per-chain `DisputeGameFactory`. Already-deployed game proxies on those factories are unaffected and continue to resolve.

Capture the new shared addresses by re-running op-fetcher against each chain. After migration, `optimismPortal().anchorStateRegistry()`, `disputeGameFactory()`, and `ethLockbox()` all return the new shared proxies, so the same op-fetcher inputs you used in [Gather the Required Inputs](#gather-the-required-inputs) now resolve the post-migration addresses. Write the post-migration output to new files (do not overwrite the pre-migration ones — you still need them to reference the per-chain `<oldASR>` and `<oldDGF>` during the drain).

```bash theme={null}
op-fetcher fetch \
  --l1-rpc-url $L1_RPC \
  --system-config <SystemConfig_chainA> \
  --l1-standard-bridge <L1StandardBridge_chainA> \
  --output-file <chainA>-postmigrate.json

op-fetcher fetch \
  --l1-rpc-url $L1_RPC \
  --system-config <SystemConfig_chainB> \
  --l1-standard-bridge <L1StandardBridge_chainB> \
  --output-file <chainB>-postmigrate.json
```

Capture the shared addresses from chain A's post-migration output:

```bash theme={null}
SHARED_ASR=$(jq -r '.addresses.AnchorStateRegistryProxy' <chainA>-postmigrate.json)
SHARED_DGF=$(jq -r '.addresses.DisputeGameFactoryProxy' <chainA>-postmigrate.json)
SHARED_LOCKBOX=$(jq -r '.addresses.EthLockboxProxy' <chainA>-postmigrate.json)
```

Confirm chain B's portal resolves to the same shared proxies:

```bash theme={null}
diff <(jq -r '.addresses.AnchorStateRegistryProxy, .addresses.DisputeGameFactoryProxy, .addresses.EthLockboxProxy' <chainA>-postmigrate.json) \
     <(jq -r '.addresses.AnchorStateRegistryProxy, .addresses.DisputeGameFactoryProxy, .addresses.EthLockboxProxy' <chainB>-postmigrate.json)
# Expect: no output (identical).
```

## Verify the Migration On-Chain

Run every check below before you start the new `op-proposer`. If any check fails, stop and escalate via your standard incident-response channel; recovery from a half-cut state with a misbehaving proposer is materially harder than recovery from one that is paused.

### Verify the Shared Registry and Factory

```bash theme={null}
# Respected game type on the new ASR
cast call $SHARED_ASR 'respectedGameType()(uint32)' --rpc-url $L1_RPC
# Expect: 9 (SUPER_CANNON_KONA)

# Anchor root and timestamp on the new ASR
cast call $SHARED_ASR 'getAnchorRoot()(bytes32,uint256)' --rpc-url $L1_RPC
# Expect: (<super root hash>, <timestamp>) from "Generate the Starting Anchor Super Root"

# Retirement timestamp on the new ASR
cast call $SHARED_ASR 'retirementTimestamp()(uint64)' --rpc-url $L1_RPC
# Expect: equal to the migration block's timestamp

# Game implementations registered on the shared factory
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 5 --rpc-url $L1_RPC   # SUPER_PERMISSIONED
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 9 --rpc-url $L1_RPC   # SUPER_CANNON_KONA
# Expect both: non-zero

# Init bonds match each game type's configuration
cast call $SHARED_DGF 'initBonds(uint32)(uint256)' 5 --rpc-url $L1_RPC
# Expect: 0
cast call $SHARED_DGF 'initBonds(uint32)(uint256)' 9 --rpc-url $L1_RPC
# Expect: 80000000000000000

# No legacy implementations registered on the shared factory
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 0 --rpc-url $L1_RPC   # CANNON
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 1 --rpc-url $L1_RPC   # PERMISSIONED_CANNON
cast call $SHARED_DGF 'gameImpls(uint32)(address)' 8 --rpc-url $L1_RPC   # CANNON_KONA
# Expect each: 0x0000000000000000000000000000000000000000
```

### Confirm Per-Chain Factories Are Cleared

```bash theme={null}
for OLD_DGF in <oldDGF_chainA> <oldDGF_chainB>; do
    for GT in 0 1 5 8 9; do
        echo "$OLD_DGF gameImpls($GT)= $(cast call $OLD_DGF 'gameImpls(uint32)(address)' $GT --rpc-url $L1_RPC)"
    done
done
# Expect every entry: 0x0000000000000000000000000000000000000000
```

### Confirm the Shared Lockbox Is Authorized

```bash theme={null}
cast call $SHARED_LOCKBOX 'authorizedPortals(address)(bool)' <OptimismPortal2_chainA> --rpc-url $L1_RPC
cast call $SHARED_LOCKBOX 'authorizedPortals(address)(bool)' <OptimismPortal2_chainB> --rpc-url $L1_RPC
# Expect both: true
```

## Start the Shared op-challenger and op-dispute-mon

Both shared instances were staged in [Stage the Off-Chain Configuration](#stage-the-off-chain-configuration) with every flag except `--game-factory-address` set. Now that `$SHARED_DGF` is known and the migration is verified on-chain, fill in the address on both and start the processes as soon as practical.

`SUPER_CANNON_KONA` is a permissionless game type, so the moment the shared factory is live anyone can create a game against it — not just `op-proposer`. Once a game is created, its clock runs and it resolves whether or not anyone challenges. `op-challenger` must be running to defend invalid claims before their game clocks expire, and `op-dispute-mon` must be running to observe and alert. This is independent of [Cut Over to a Single Shared op-proposer](#cut-over-to-a-single-shared-op-proposer) below — complete it first regardless of when the proposer cutover happens.

1. **Set the shared `op-challenger`'s `--game-factory-address` (`OP_CHALLENGER_GAME_FACTORY_ADDRESS`) to `$SHARED_DGF` and start the process.** Confirm the startup log lists `super-cannon-kona` as a registered trace type and shows no errors connecting to the shared supernode root RPC endpoint.
2. **Set the shared `op-dispute-mon`'s `--game-factory-address` (`OP_DISPUTE_MON_GAME_FACTORY_ADDRESS`) to `$SHARED_DGF` and start the process.** Confirm the supernode root connection is healthy and the metrics endpoint is serving.

Healthy startup logs and a quiet error stream are the bar for proceeding. Both instances discover existing games on startup, so it does not matter whether a super-root game already exists in the shared factory by the time they come up.

## Cut Over to a Single Shared op-proposer

Start one new `op-proposer` process for the shared factory. A single proposer replaces both per-chain ones because the supernode produces one super root per timestamp covering both chains.

Configure the new instance with the flags below.

| Flag (env var)                                                            | Value                                                                            |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `--game-factory-address` (`OP_PROPOSER_GAME_FACTORY_ADDRESS`)             | the new shared `<DGF>`                                                           |
| `--superroot-rpcs` (`OP_PROPOSER_SUPERROOT_RPCS`)                         | `$SUPERNODE_RPC` or high-availability root endpoints for the same dependency set |
| `--game-type` (`OP_PROPOSER_GAME_TYPE`)                                   | `9` (SUPER\_CANNON\_KONA)                                                        |
| `--l1-eth-rpc` (`OP_PROPOSER_L1_ETH_RPC`)                                 | as for the existing proposers                                                    |
| `--proposal-interval`, `--poll-interval`, `--mnemonic` or `--private-key` | as for the existing proposers                                                    |

After start-up, verify:

* The logs show the proposer polling the supernode and writing to the shared factory.

* Within one `--proposal-interval`, the proposer submits a new game on the shared factory. Inspect it:

  ```bash theme={null}
  COUNT=$(cast call $SHARED_DGF 'gameCount()(uint256)' --rpc-url $L1_RPC)
  echo "gameCount=$COUNT"

  read -r GAME_TYPE CREATED_AT GAME_PROXY < <(cast call $SHARED_DGF 'gameAtIndex(uint256)(uint32,uint64,address)' $((COUNT-1)) --rpc-url $L1_RPC)
  # Expect: GAME_TYPE=9 and GAME_PROXY non-zero.
  echo "gameType=$GAME_TYPE createdAt=$CREATED_AT gameProxy=$GAME_PROXY"

  cast call $GAME_PROXY 'rootClaim()(bytes32)'        --rpc-url $L1_RPC
  cast call $GAME_PROXY 'l2SequenceNumber()(uint256)' --rpc-url $L1_RPC
  ```

* Recompute the super root for the proposed timestamp and confirm it matches the proposal:

  ```bash theme={null}
  cast rpc superroot_atTimestamp "$(cast 2h <l2SequenceNumber from above>)" \
    --rpc-url $SUPERNODE_RPC | jq -r '.data.super_root'
  # Expect: equals rootClaim from above.
  ```

Once the proposer is stable, do not stop the per-chain `op-challenger` or `op-dispute-mon` instances—they are still needed for the drain window described next.

## Drain Pre-Migration Games and Reclaim Bonds

The migration cleared the per-chain factories' implementation pointers so no new pre-migration games can be created, but every game proxy that already existed on those factories at migration time continues to function. Each game's implementation, `AnchorStateRegistry`, and `DelayedWETH` references were captured as immutable arguments on the proxy when it was created, so the cleared factory pointer does not affect resolution. Bond claims through `FaultDisputeGame.claimCredit` flow into the same `DelayedWETH` the bonds were posted into, independent of the portal or the new shared factory.

Concretely:

* The two per-chain `op-challenger` instances continue to play retired games to `DEFENDER_WINS` or `CHALLENGER_WINS` and schedule bond claims as games finalize.
* Bond claims succeed without operator intervention. Chain A's retired games claim through chain A's `DelayedWETH` (which is also the one used by the new shared games); chain B's retired games claim through chain B's `DelayedWETH`, which is otherwise unused after migration.
* The two per-chain `op-dispute-mon` instances keep observing those games. The per-game-type metric `op_dispute_mon_games{game_type="super-cannon-kona"}` and the equivalent for `super-permissioned` should monotonically decrease toward zero across the drain window.
* `op-challenger`'s default `--game-window` is 28 days, sized to cover up to 16 days of game play plus a seven-day `DelayedWETH` withdrawal delay plus a five-day buffer. Do not shrink it on the per-chain instances; doing so risks dropping games before their bonds are claimable.

Pick a still-in-flight pre-migration game and watch it through to resolution and bond claim:

```bash theme={null}
cast call <gameProxy> 'status()(uint8)' --rpc-url $L1_RPC
# 0 = IN_PROGRESS, 1 = CHALLENGER_WINS, 2 = DEFENDER_WINS

cast call <gameProxy> 'resolvedAt()(uint64)' --rpc-url $L1_RPC
# Non-zero once the game has resolved.
```

Once a game is resolved and the `DelayedWETH` finality window has elapsed, the challenger schedules `claimCredit`. Confirm bonds reach the configured claimant by watching the `op_challenger_bonds_total` metric on the per-chain instance, alongside `op_challenger_claim_failures_total` staying flat.

## Verify After the Migration

Run these checks once the new proposer is stable.

* **Confirm the shared `op-challenger` is defending super-root games.** The challenger does not break metrics down by game type, so verify by way of the startup log (every configured trace type, including `super-cannon-kona` and `super-permissioned`, must be listed as registered) and by ongoing logs (no scheduler or game-poll errors as super games appear on the shared factory). The aggregate `op_challenger_tracked_games{status="in_progress"}` becomes non-zero as super games are created and remains non-zero while games are in progress.
* **Confirm the shared `op-dispute-mon` reports super-root games.** On the shared instance, `op_dispute_mon_games{game_type="super-cannon-kona"}` and `op_dispute_mon_games{game_type="super-permissioned"}` are non-zero once games are created. `op_dispute_mon_failed_games` stays near zero; a non-zero value typically points at missing `--supernode-rpc` or supernode unavailability.
* **Confirm new pre-migration games cannot be created.** Optionally call `DisputeGameFactory.create` with one of the cleared game types on either per-chain factory and confirm it reverts.
* **Watch for the first super-game finalization.** The first anchor update typically lands roughly seven days after the first super-root game is created (game duration plus `DISPUTE_GAME_FINALITY_DELAY_SECONDS`). Do not block the rollout on this—schedule a follow-up to re-run `getAnchorRoot()` after that window and confirm it returns the new game's claim instead of the starting anchor.

## Tear Down After the Drain

A per-chain instance is safe to retire when its `op_dispute_mon_games{game_type="super-cannon-kona"}` and `op_dispute_mon_games{game_type="super-permissioned"}` have been zero for at least one full `--game-window` (default 28 days) and `op_challenger_tracked_games{status="in_progress"}` on the matching per-chain `op-challenger` is zero with bond-claim metrics stable.

For each chain when both conditions hold, stop the per-chain `op-challenger` and `op-dispute-mon` instances.

Once both chains are drained, the steady-state operational footprint is one `op-proposer`, one `op-challenger`, and one `op-dispute-mon`, all pointed at the shared factory and a single supernode that derives both chains.

## Next Steps

* Plan the full interop activation milestone—`migrate` joins the chains under a shared dispute game, but turning on cross-chain messaging is a separate step. See [Interop Explainer](/op-stack/interop/explainer) when you are ready.
* Schedule a follow-up to verify the anchor advances on the first super-game finalization, roughly seven days after the new proposer's first proposal. Re-run `cast call $SHARED_ASR 'getAnchorRoot()(bytes32,uint256)' --rpc-url $L1_RPC` and confirm it returns the new game's claim.


# Migrating to permissionless fault proofs on OP Stack
Source: https://docs.optimism.io/chain-operators/tutorials/migrating-permissionless

Migrate your OP Stack chain from permissioned to permissionless fault proofs: configure the dispute components, deploy the contracts with OPCM, test the off-chain agents, and switch the respected game type.

This guide shows you how to transition your OP Stack chain from permissioned to permissionless fault proofs.
It walks chain operators through the four migration phases: configuring the dispute components, deploying the smart contracts with OPCM, testing the off-chain agents, and switching the respected game type.

## Overview

The OP Stack architecture uses Fault Proofs to ensure the validity of withdrawals from L2 to L1.
Transitioning from permissioned to permissionless proofs represents a significant security upgrade, allowing any participant to propose and challenge state output roots.
Permissioned games previously relied on a single trusted validator, this is typically the proposer which is configured in the PermissionedDisputeGame, and is usually the network's only sequencer.

This migration involves several key components:

* Configuring security-critical dispute [monitoring services](/chain-operators/tools/chain-monitoring)
* Deploying and configuring smart contracts using [op-deployer](/chain-operators/tools/op-deployer/overview)
* Testing the new system before activation
* Setting the respected game type to permissionless fault proofs, specifically using the [`FaultDisputeGame`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/FaultDisputeGame.sol)

## Prerequisites

Before beginning this transition, your chain should:

* Be running a standard OP Stack implementation
* It's recommended to use the latest contracts version, minimum required [**v5.0.0**](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv5.0.0).
* Be operating with the required infrastructure services including [`op-challenger`](/op-stack/fault-proofs/challenger) and [`op-dispute-mon`](/chain-operators/tools/chain-monitoring#dispute-mon).

## Migration steps

The process of migrating from permissioned to permissionless fault proofs involves four main phases: configuring off-chain dispute components, deploying the necessary smart contracts, testing the system thoroughly, and finally switching the chain to use permissionless proofs. Each step builds on the previous one to ensure a smooth and secure transition.

Let's begin with configuring the dispute components that will interact with the new permissionless game.

## 1. Configure the dispute components

The `op-challenger` and `op-dispute-mon` services are critical security components that participate in the dispute game process to challenge invalid proposals and monitor active games.

### Upgrade to the latest `op-challenger`

Upgrade to the [latest release](https://github.com/ethereum-optimism/optimism/releases), which contains important improvements to simplify the upgrade process.

You can use the official Docker image for reliability and ease of deployment:

```bash theme={null}
# Pull a specific stable release version
docker pull us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:<latest_version>
```

Then run the image, for example:

```bash theme={null}
# Run with all required flags
docker run -d --name op-challenger \
  -e OP_CHALLENGER_GAME_TYPES=permissioned,cannon-kona \
  -e OP_CHALLENGER_PRESTATES_URL=<YOUR_PRESTATES_URL> \
  -e OP_CHALLENGER_L1_ETH_RPC=<YOUR_L1_RPC_URL> \
  -e OP_CHALLENGER_GAME_FACTORY_ADDRESS=<YOUR_DISPUTE_GAME_FACTORY> \
  -e OP_CHALLENGER_PRIVATE_KEY=<YOUR_PRIVATE_KEY_OR_USE_WALLET_SIGNER> \
  -e OP_CHALLENGER_NETWORK=<YOUR_NETWORK> \
  -v /path/to/local/prestates:/prestates \
  us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:latest

# Replace all placeholder values with your actual configuration

```

Replace `<YOUR_PRESTATES_URL>` with your actual prestates URL.

If your deployment requires building from source, you can alternatively use:

```bash theme={null}
git clone https://github.com/ethereum-optimism/optimism -b op-challenger/<latest_version> --recurse-submodules
cd optimism
make op-challenger
```

### Update network configuration

Configure `op-challenger` to load your chain configuration.
Even if your chain is not included in the [superchain-registry](/op-stack/protocol/superchain-registry), you can specify a custom configuration:

```bash theme={null}
# For chains in the registry
--network <chain-name>

# For chains not in the registry, provide a path to your rollup configuration
- `rollup.json` - Your rollup configuration
- `genesis-l2.json` - Your L2 genesis file
```

### Enable the cannon-kona game type

From the Karst upgrade, `cannon-kona` (the kona-client program run inside the Cannon VM) is the respected permissionless game type, replacing op-program. Configure `op-challenger` to support both permissioned and permissionless games by setting:

```bash theme={null}
--game-types permissioned,cannon-kona
```

Or by setting the environment variable:

```bash theme={null}
OP_CHALLENGER_GAME_TYPES=permissioned,cannon-kona
```

### Configure prestates access

Replace the `--cannon-kona-prestate` flag with `--prestates-url`, which points to a source containing all required prestates:

```bash theme={null}
--prestates-url <URL_TO_PRESTATES_DIRECTORY>
```

The URL can use `http`, `https`, or `file` protocols. Each prestate should be named as `<PRESTATE_HASH>.bin.gz`.

### Building required prestates for chains not in the superchain-registry

You'll need a new absolute prestate to register with the `FaultDisputeGame` and `PermissionedDisputeGame` (see [Section 2](#2-deploy-and-configure-smart-contracts-using-opcm)).

<Info>
  The initial prestate used for permissioned games doesn't include the necessary chain configuration for the Fault Proof System. The assumption is that the chain operator, the single permissioned actor, will not challenge their own games. So the absolute prestate on the initial `PermissionedDisputeGame` will never be used.
  When deploying a new chain, you must first deploy the L1 contracts and then generate the chain genesis file and rollup configuration files.
  These are inputs to the creation of the absolute prestate and this circular dependency is the reason chains cannot be deployed directly to the permissionless Fault Proof System.
</Info>

For chains not in the superchain-registry, you need to build custom prestates with your chain's configuration:

Build the kona-client absolute prestate with `just reproducible-prestate-kona` (see the [absolute prestate tutorial](/chain-operators/tutorials/absolute-prestate)). The artifacts are written to:

* `rust/kona/prestate-artifacts-cannon/prestate-proof.json` — the proof file; its `pre` field is the absolute prestate hash (`jq -r .pre ...`)
* `rust/kona/prestate-artifacts-cannon/<PRESTATE_HASH>.bin.gz` — the preimage file `op-challenger` loads

<Info>
  Register the kona-client absolute prestate with your `FaultDisputeGame` and `PermissionedDisputeGame`. The challenger refuses to interact with games whose on-chain absolute prestate doesn't match the one it has, so the hash must match exactly.
</Info>

### Ensure sufficient funds for bonds

Bonds are required for both permissioned and permissionless games.
However, with permissioned games, you typically don't post claims regularly, making bond requirements less noticeable.
In contrast, the challenger in permissionless games will frequently need to post bonds with each claim it makes.
Therefore, ensure your challenger has sufficient funds available.

As a general guideline:

* Maintain a minimum balance of 50 ETH
* Have access to a large pool of ETH for potential attack scenarios
* Implement monitoring to ensure sufficient funds are always available

### Ensure there is disk space for the challenger to use

`op-challenger`, particularly in permissionless mode, should have access to disk. About 50GB is enough to cover a couple of `invalid_ games`. Though the storage requirements will increase if the challenger needs to respond to more invalid dispute games.
Nominally, the challenger does not use disk space as long as there aren’t any invalid proposals being made.

One way to gain more confidence that the op-challenger was configured correctly is to operate the op-challenger in “runner” mode.
Using the same op-challenger configuration, invoke the `op-challenger run-trace --run cannon-kona` subcommand.
This will run op-challenger in a mode where it runs the kona-client program in a Cannon VM on live L2 blocks to ensure those were configured correctly.
This command runs forever, checking every couple of L2 blocks. But it suffices to let it run until it has completed one loop and kill it.
Wait you see `Successfully verified output root` in the logs before shutting it down.
Any errors indicate a misconfiguration.

### Set up `op-dispute-mon`

Ensure `op-dispute-mon` is properly configured by following the [steps](/chain-operators/tools/chain-monitoring#dispute-mon) in the documentation.

## 2. Deploy and configure smart contracts using OPCM

This section requires privileged actions by the `ProxyAdminOwner` and the `Guardian` role.

### Understanding ProxyAdmin Owner and Guardian roles

This migration requires actions by privileged roles in your system:

* The **ProxyAdmin Owner** has the authority to upgrade proxy contracts.
* The **Guardian** has emergency powers like pausing withdrawals and changing the respected game type.

For detailed information about privileged roles and their security implications, refer to the [privileged roles documentation](/op-stack/protocol/privileged-roles).

### Adding the PermissionlessDisputeGame to a chain

To enable the permissionless dispute game, call the `upgrade()` function on the `OPContractsManagerV2` (OPCM) contract with the appropriate `DisputeGameConfig` entries. This is typically done via `op-deployer manage add-game-type-v2`.

The upgrade will:

1. Register the `FaultDisputeGame` implementation on the `DisputeGameFactory` with the correct game arguments (absolute prestate, VM, anchor state registry, delayed WETH, chain ID).
2. Set the initial bond for the new game type.

See a high‐level implementation from this [docs](/chain-operators/tutorials/dispute-games) or [this superchain-ops template](https://github.com/ethereum-optimism/superchain-ops/blob/main/src/template/AddGameTypeTemplate.sol).

## 3. Testing off-chain agents

After you've set the permissionless `FaultDisputeContract` implementations on the `DisputeGameFactory` and before you set the respected game type to it (game type 0), you can test `op-challenger` and `op-dispute-mon` to ensure they are working correctly with permissionless games.

There are a number of useful `op-challenger` subcommands that can be used for testing, particularly `list-games`, `list-claims` and `create-game`.  See the [README](https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger#subcommands) and `op-challenger --help` output for further details. The two tests below are basic sanity tests:

### Test defending valid proposals

Create a valid proposal using the permissionless game type `0`:

1. Ensure the proposal is from a block at or before the `safe` head:

   ```bash theme={null}
   cast block --rpc-url <OP_GETH_ENDPOINT> safe

   ```

2. Get a valid output root (from op-node):

   ```bash theme={null}
   cast rpc --rpc-url <OP_NODE_ENDPOINT> optimism_outputAtBlock \
     $(cast 2h <BLOCK_NUMBER>) | jq -r .outputRoot

   ```

3. Create a test game:

   ```bash theme={null}
   ./op-challenger/bin/op-challenger create-game \
     --l1-eth-rpc=<L1_RPC_ENDPOINT> \
     --game-factory-address <DISPUTE_GAME_FACTORY_ADDR> \
     --l2-block-num <BLOCK_NUMBER> \
     --output-root <OUTPUT_ROOT> \
     <SIGNER_OPTIONS>

   ```

4. Verify:
   * `op-challenger` logs a message showing the game is in progress
   * `op-challenger` doesn't post a counter claim (as this is a valid proposal)
   * `dispute-mon` includes the new game with `status="agree_defender_ahead"`

### Test countering invalid claims

Post an invalid counter claim to the valid proposal created above:

```bash theme={null}
./op-challenger/bin/op-challenger move \
  --l1-eth-rpc <L1_RPC_ENDPOINT> \
  --game-address <GAME_ADDR> \
  --attack \
  --parent-index 0 \
  --claim 0x0000000000000000000000000000000000000000000000000000000000000000 \
  <SIGNER_OPTIONS>

```

Verify that `op-challenger` posts a counter-claim to the invalid claim. You can view claims using:

```bash theme={null}
./op-challenger/bin/op-challenger list-claims \
  --l1-eth-rpc <L1_RPC_ENDPOINT> \
  --game-address <GAME_ADDR>

```

There should be 3 claims in the game after this test.

## Switch to permissionless proofs

After completing all previous steps and verifying their successful operation, you need to update the `respectedGameType` in the `AnchorStateRegistry`. This requires execution through the appropriate privileged role (typically the Guardian).

You have two main options for executing this step:

### Option 1: Execute using a multisig

If your privileged role (such as the Guardian) is controlled by a multisig or DAO governance system, use the provided JSON payload (`input.json`):

<Expandable title="Create an `input.json` file with the transaction to update the `respectedGameType`: ">
  ```json theme={null}
  {
    "chainId": "<YOUR_L1_CHAIN_ID>",
    "metadata": {
      "name": "Deputy Guardian - Enable Permissionless Dispute Game",
      "description": "This task updates the `respectedGameType` in the `AnchorStateRegistry` to `CANNON` (game type 0), enabling users to permissionlessly propose outputs as well as for anyone to participate in the dispute of these proposals. This action requires all in-progress withdrawals to be re-proven against a new `FaultDisputeGame` that was created after this update occurs."
    },
    "transactions": [
      {
        "metadata": {
          "name": "Update `respectedGameType` in the `AnchorStateRegistry`",
          "description": "Updates the `respectedGameType` to `CANNON` in the `AnchorStateRegistry`, enabling permissionless proposals and challenging."
        },
        "to": "<ASR_ADDRESS>",
        "value": "0x0",
        "data": "0x7fc485040000000000000000000000000000000000000000000000000000000000000000",
        "contractMethod": {
          "type": "function",
          "name": "setRespectedGameType",
          "inputs": [
            {
              "name": "_gameType",
              "type": "uint32"
            }
          ],
          "outputs": [],
          "stateMutability": "nonpayable"
        },
        "contractInputsValues": {
          "_gameType": "0"
        }
      }
    ]
  }

  ```
</Expandable>

* **Submit this JSON payload** through your interface (e.g., Safe transaction builder).
* **Simulate** this transaction using Tenderly before execution to ensure the expected state changes:
  * The `respectedGameType` in the `AnchorStateRegistry` should change from `1` (PERMISSIONED) to `0` (CANNON).

***

### Option 2: Direct execution via `cast` (Forge CLI)

Alternatively, if you're executing directly from a single-privileged wallet or want quicker execution, use the following `cast` commands:

1. First, encode the transaction calldata using `cast calldata`:

```bash theme={null}
CALLDATA=$(cast calldata "setRespectedGameType(uint32)" 0)
```

2. Send the transaction:

```bash theme={null}
# Execute the transaction
cast send --rpc-url <YOUR_RPC_URL> --private-key <YOUR_PRIVATE_KEY> <ASR_ADDRESS> "$CALLDATA"
```

3. After execution, verify the respected game type:

```bash theme={null}
cast call --rpc-url <YOUR_RPC_URL> <ASR_ADDRESS> "respectedGameType()(uint32)"
# The value should now be 0 (CANNON)

```

### Post-execution configuration:

After updating, configure `op-proposer` to create proposals using the permissionless `CANNON` game type:

Via command-line argument:

```bash theme={null}
--game-type 0
```

Or via environment variable:

```bash theme={null}
OP_PROPOSER_GAME_TYPE=0
```

<Info>
  This action requires all in-progress withdrawals to be re-proven against a new `FaultDisputeGame` created after this update occurs.
</Info>

## Next steps

* For more detail on deploying new dispute games with OPCM, [see the docs](/chain-operators/tutorials/dispute-games).
* Deploy new dispute games with OPCM via [this tutorial](/chain-operators/tutorials/dispute-games).
* Generate an absolute prestate using the [absolute prestate guide](/chain-operators/tutorials/absolute-prestate).
* Understand fault proofs in the [Fault proofs explainer](/op-stack/fault-proofs/explainer).


# Modifying predeployed contracts
Source: https://docs.optimism.io/chain-operators/tutorials/modifying-predeploys

Learn how to modify predeployed contracts for an OP Stack chain by upgrading the proxy.

<Info>
  OP Stack Hacks are explicitly things that you can do with the OP Stack that are *not* currently intended for production use.

  OP Stack Hacks are not for the faint of heart. You will not be able to receive significant developer support for OP Stack Hacks. Be prepared to get your hands dirty and to work without support.
</Info>

OP Stack blockchains have a number of [predeployed contracts](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/libraries/Predeploys.sol) that provide important functionality.
Most of those contracts are proxies that can be upgraded using the `proxyAdminOwner` which was configured when the network was initially deployed.

## Before you begin

In this tutorial, you learn how to modify predeployed contracts for an OP Stack chain by upgrading the proxy. The predeploys are controlled from a predeploy called [`ProxyAdmin`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/ProxyAdmin.sol), whose address is `0x4200000000000000000000000000000000000018`.
The function to call is [`upgrade(address,address)`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/ProxyAdmin.sol#L152-L168).
The first parameter is the proxy to upgrade, and the second is the address of a new implementation.

## Modify the legacy `L1BlockNumber` contract

For example, the legacy `L1BlockNumber` contract is at `0x420...013`.
To disable this function, we'll set the implementation to `0x00...00`.
We do this using the [Foundry](https://book.getfoundry.sh/) command `cast`.

<Steps>
  <Step title="We'll need several constants.">
    * Set these addresses as variables in your terminal.

      ```sh theme={null}
      L1BLOCKNUM=0x4200000000000000000000000000000000000013
      PROXY_ADMIN=0x4200000000000000000000000000000000000018
      ZERO_ADDR=0x0000000000000000000000000000000000000000
      ```

    * Set `PRIVKEY` to the private key of your ADMIN address.

    * Set `ETH_RPC_URL`. If you're on the computer that runs the blockchain, use this command.

      ```sh theme={null}
      export ETH_RPC_URL=http://localhost:8545
      ```
  </Step>

  <Step title="Verify `L1BlockNumber` works correctly.">
    See that when you call the contract you get a block number, and twelve seconds later you get the next one (block time on L1 is twelve seconds).

    ```sh theme={null}
    cast call $L1BLOCKNUM 'number()' | cast --to-dec
    sleep 12 && cast call $L1BLOCKNUM 'number()' | cast --to-dec
    ```
  </Step>

  <Step title="Get the current implementation for the contract.">
    ```sh theme={null}
      L1BLOCKNUM_IMPLEMENTATION=`cast call $L1BLOCKNUM "implementation()" | sed 's/000000000000000000000000//'`
      echo $L1BLOCKNUM_IMPLEMENTATION 
    ```
  </Step>

  <Step title="Change the implementation to the zero address">
    ```sh theme={null}
      cast send --private-key $PRIVKEY $PROXY_ADMIN "upgrade(address,address)" $L1BLOCKNUM $ZERO_ADDR
    ```
  </Step>

  <Step title="See that the implementation is address zero, and that calling it fails.">
    ```sh theme={null}
      cast call $L1BLOCKNUM 'implementation()'
      cast call $L1BLOCKNUM 'number()'
    ```
  </Step>

  <Step title="Fix the predeploy by returning it to the previous implementation, and verify it works.">
    ```sh theme={null}
      cast send --private-key $PRIVKEY $PROXY_ADMIN "upgrade(address,address)" $L1BLOCKNUM $L1BLOCKNUM_IMPLEMENTATION
      cast call $L1BLOCKNUM 'number()' | cast --to-dec
    ```
  </Step>
</Steps>


# How to rewind op-geth
Source: https://docs.optimism.io/chain-operators/tutorials/rewind-op-geth

Learn how to rewind an op-geth node to a previous chain head.

## Overview

This tutorial teaches you how to rewind a single op-geth instance to a previous chain head.
This can be helpful to fix a divergent node, recreate archival state, or the safedb from an earlier chain state.

## Rewind op-geth

Follow these steps to rewind your op-geth node.

<Steps>
  <Step title="Shut down the CL">
    Whatever CL clients are driving the op-geth instance need to be stopped to prevent them from interfering with the rewind later.
    This would typically be a locally running `op-node` or `kona-node` application, a Docker container or a pod in a Kubernetes cluster.

    <Note>
      Make sure you don't have something like ArgoCD syncing the app in question which would just scale the pod back up again.
    </Note>
  </Step>

  <Step title="Determine rewind target">
    If you already know the block number/hash you want to rewind to, you can proceed to the next step.

    If you only know the *timestamp* you want to rewind to, you can find the corresponding block with

    ```bash theme={null}
    cast find-block 1741890000 -r <ETH_RPC_URL>
    ```

    Where `<ETH_RPC_URL>` points to your op-geth node’s RPC endpoint, e.g. `http://localhost:8545` if it was a local instance with the default port and `1741890000` is an example unix timestamp. You can use e.g. [https://www.epochconverter.com/](https://www.epochconverter.com/) to convert from human times to unix timestamps.
  </Step>

  <Step title="Rewind op-geth">
    You need the JWT secret and *open* & *admin* port (default `8545` & `8551`).
    Then you can use the `op-wheel` command from the [monorepo](https://github.com/ethereum-optimism/optimism/tree/develop/op-wheel) to issue the rewind.

    ```bash theme={null}
    # save JWT secret to env var
    export JWT="YourJWTSecret123"
    # assuming default ports 8545 and 8551 and local endpoint
    go run ./op-wheel/cmd engine rewind \
    --engine.open http://localhost:8545 \
    --engine http://localhost:8551 \
    --engine.jwt-secret $JWT \
    --log.level DEBUG \
    --set-head --to 8460000
    ```

    This would rewind the op-geth node to the block with number `8460000`. You should have determined the right block number in step 2.
  </Step>

  <Step title="Start the CL">
    You can now start your CL client again. It will sync from the rewound block head.
  </Step>
</Steps>


# Upgrading a Chain From Output Roots to Super Roots
Source: https://docs.optimism.io/chain-operators/tutorials/upgrade-chain-to-super-roots

Upgrade an OP Stack chain from output-root dispute games to super-root dispute games with a single opcm.upgrade call, then cut op-proposer, op-challenger, and op-dispute-mon over to super roots.

# Upgrading a Chain From Output Roots to Super Roots

<Warning>This guide depends on the interop feature, which is still in development. Do not follow it on production chains.</Warning>

This runbook walks you through upgrading a single OP Stack chain from output-root dispute games (`PERMISSIONED_CANNON`, `CANNON` or `CANNON_KONA`) to super-root dispute games (`SUPER_PERMISSIONED` or `SUPER_CANNON_KONA`). It runs as a single `opcm.upgrade` call against the chain's existing per-chain `AnchorStateRegistry` and `DisputeGameFactory`. The chain's permission model is preserved: a permissioned chain stays permissioned with `SUPER_PERMISSIONED` only; a permissionless chain runs both super game types with `SUPER_CANNON_KONA` as the respected one. Differences between the two are called out inline.

By the end you will have a chain proposing super-root claims via `op-proposer` using a single-chain super-root RPC endpoint and monitoring them with `op-dispute-mon`. On permissionless chains, `op-challenger` defends `SUPER_CANNON_KONA` claims. On permissioned chains, `op-dispute-mon` detects invalid `SUPER_PERMISSIONED` claims, `op-challenger` updates the `AnchorStateRegistry` as games finalize. Every pre-migration dispute game already in flight continues to resolve, and proven withdrawals are not invalidated.

<Note>This is `opcm.upgrade`, not `opcm.migrate` — the chain keeps its own per-chain `AnchorStateRegistry` and `DisputeGameFactory`.</Note>

Looking to switch from permissioned to permissionless fault proofs? See [Migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless). This runbook is for chains already running fault proofs that need to move from output-root games to super-root games.

## Before You Begin

<SuperchainOpsPrereqs />

### Required tooling

The versions below are the ones the optimism repo's `mise.toml` pins; older versions of `cast` in particular may not parse the function-selector syntax used in this runbook.

| Tool                        | Minimum version |
| --------------------------- | --------------- |
| `foundry` (`cast`, `forge`) | `1.2.3`         |
| `just`                      | `1.46.0`        |
| `jq`                        | `1.7.1`         |
| `go`                        | `1.26.5`        |
| `curl`                      | any             |

You also need a checkout of the [optimism monorepo](https://github.com/ethereum-optimism/optimism) to run [`op-fetcher`](https://github.com/ethereum-optimism/optimism/tree/develop/op-fetcher) (used in the next step).

### Gather the Required Inputs

Collect everything below before you start.

**Chain identity.** The chain's per-chain addresses live in the `superchain-registry` repository under `superchain/configs/<network>/<chain-name>.toml`. Open that file and read `chain_id`, `addresses.SystemConfigProxy`, and `addresses.L1StandardBridgeProxy`.

**Chain addresses and roles.** Use `op-fetcher` to derive the rest of the on-chain configuration in a single call. It runs an embedded forge script against `$L1_RPC` and resolves every per-chain proxy, role, and the current fault-proof status from `SystemConfig` and `L1StandardBridge`:

```bash theme={null}
cd <optimism-monorepo>/op-fetcher
just build-all
go run ./cmd fetch \
  --l1-rpc-url "$L1_RPC" \
  --system-config "<SystemConfigProxy>" \
  --l1-standard-bridge "<L1StandardBridgeProxy>" \
  --output-file chain.json
```

Read the values you need from `chain.json`:

| Item                                                       | Source                                                     |
| ---------------------------------------------------------- | ---------------------------------------------------------- |
| L2 chain ID                                                | `chain_id` in the chain's registry TOML                    |
| `SystemConfig` proxy                                       | `addresses.SystemConfigProxy` in the chain's registry TOML |
| `OptimismPortal2` proxy                                    | `.addresses.OptimismPortalProxy`                           |
| `AnchorStateRegistry` proxy (referred to below as `<ASR>`) | `.addresses.AnchorStateRegistryProxy`                      |
| `DisputeGameFactory` proxy (referred to below as `<DGF>`)  | `.addresses.DisputeGameFactoryProxy`                       |
| `SuperchainConfig` proxy                                   | `.addresses.SuperchainConfigProxy`                         |

**Chain type.** The upgrade preserves the chain's existing permission model. `chain.json` reports the current respected game type at `.faultProofs.respectedGameType`:

* `1` (`PERMISSIONED_CANNON`) — chain is **permissioned**. The new respected game type is `5` (`SUPER_PERMISSIONED`).
* `0` (`CANNON`) or `8` (`CANNON_KONA`) — chain is **permissionless**. The new respected game type is `9` (`SUPER_CANNON_KONA`).

**Init bonds.** `SUPER_PERMISSIONED` (game type `5`) is bondless and must use an `initBond` of `0`. `SUPER_CANNON_KONA` (game type `9`) uses `0.08 ether` (`80000000000000000` wei), the standard value used on existing chains.

**Release artifacts and infrastructure.**

| Item                                                     | Source                                                                                                                                                                                                                                                                                           |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OPCM` address for the target network                    | `validation/standard/standard-versions-<network>.toml` in the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry). Look up the `op-contracts/v8.x.y` release pinned by the `OPCMUpgradeV800` template and read `op_contracts_manager.address`.                       |
| Kona-interop prestate hash                               | OPCM release manifest. Use the `-interop` kona variant, even if interop is not scheduled for the chain.                                                                                                                                                                                          |
| Prestate artifact URL                                    | The chain's existing `cannon-kona-prestates-url` server, with the kona-interop prestate uploaded ahead of the upgrade                                                                                                                                                                            |
| Single-chain super-root RPC endpoint (`$SUPER_ROOT_RPC`) | Your infrastructure team. Use the chain's op-node RPC endpoint or an op-supernode `/<chainID>/` endpoint. An op-node must run with `--safedb.path` enabled and populated. The namespaced endpoint returns a super root containing only this chain, even if the op-supernode tracks other chains. |

### Verify the Preconditions

Before you change any configuration:

* **Confirm the template's extra instructions.** Open `superchain-ops/src/template/OPCMUpgradeV800.sol` and check `_buildExtraInstructions`. As of writing it injects `overrides.cfg.startingRespectedGameType` and `PermittedProxyDeployment`. Both need attention before continuing. `PermittedProxyDeployment` must be dropped: OPCM `8.0.0` permits no proxy deployments during an upgrade, because the unified `DelayedWETH` shipped with the 7.x OPCM, so the instruction now reverts with `OPContractsManagerV2_InvalidUpgradeInstruction`. An `overrides.cfg.startingAnchorRoot` override must be added: without it, OPCM falls back to the existing on-chain `startingAnchorRoot`, which on a pre-upgrade chain is an output-root-shaped value with a block-number `l2SequenceNumber` — not a valid super-root anchor. The template must be extended to read a starting super-root anchor from TOML and add it as an extra instruction. Fix the template before continuing.
* **Confirm the RPC endpoint returns a single-chain super root.** Either the chain's op-node RPC endpoint or an op-supernode `/<chainID>/` endpoint can be used. Do not use a multi-chain op-supernode root endpoint; it computes roots across its full dependency set.
* **Verify the single-chain RPC endpoint is healthy.** For an op-node or namespaced op-supernode endpoint, confirm it reports a recent finalized L2 head and can produce the corresponding super root:

  ```bash theme={null}
  TS=$(cast rpc optimism_syncStatus --rpc-url $SUPER_ROOT_RPC | jq -r '.finalized_l2.timestamp')
  cast rpc superroot_atTimestamp "$(cast 2h $TS)" \
    --rpc-url $SUPER_ROOT_RPC | jq -r '.data.super_root'
  ```

  If an op-node returns a SafeDB error, configure `--safedb.path`, let the node populate records through derivation, and retry. `optimism_syncStatus` can succeed while SafeDB is disabled, but `superroot_atTimestamp` cannot serve a non-genesis timestamp without SafeDB.
* **Verify the prestate server serves the new hash.**

  ```bash theme={null}
  curl -fI "$PRESTATE_URL/$SUPER_PRESTATE_HASH.bin.gz"
  ```

## Stage the Off-Chain Configuration

Apply these changes before you submit the on-chain upgrade. After the changes ship, the components keep operating against existing pre-migration games and pick up super-root games automatically once the upgrade lands.

### Update op-challenger

Update the running `op-challenger` for the chain. Keep `--rollup-rpc` and the existing `--game-types` so existing games continue to be defended. Add the super-root trace type only on permissionless chains, where `SUPER_CANNON_KONA` is enabled.

| Action      | Flag (env var)                                                                                                                             | Value                                                                                                                                |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| Add         | `--superroot-rpc` (`OP_CHALLENGER_SUPERROOT_RPC`)                                                                                          | `$SUPER_ROOT_RPC`                                                                                                                    |
| Append to   | `--game-types` (`OP_CHALLENGER_GAME_TYPES`)                                                                                                | `super-cannon-kona`. Do not add `super-permissioned`; the simplified `SUPER_PERMISSIONED` game does not require claims to be posted. |
| Confirm set | `--cannon-kona-prestates-url` (`OP_CHALLENGER_CANNON_KONA_PRESTATES_URL`)                                                                  | The prestate-server URL you validated in the preconditions                                                                           |
| Confirm set | `--cannon-kona-network` (`OP_CHALLENGER_CANNON_KONA_NETWORK`) or `--cannon-kona-depset-config` (`OP_CHALLENGER_CANNON_KONA_DEPSET_CONFIG`) | One must be set so kona can resolve the dependency set for `SUPER_CANNON_KONA`.                                                      |

On a permissionless chain, confirm the startup log lists `super-cannon-kona` as registered and shows no connection errors against the single-chain super-root RPC endpoint. On a permissioned chain, confirm the existing trace types remain registered; do not configure a `SUPER_PERMISSIONED` trace type. `op-challenger` is still required on permissioned chains to update the `AnchorStateRegistry` as `SUPER_PERMISSIONED` games finalize.

### Update op-dispute-mon

Update the running `op-dispute-mon` for the chain.

| Action | Flag (env var)                                     | Value             |
| ------ | -------------------------------------------------- | ----------------- |
| Add    | `--superroot-rpc` (`OP_DISPUTE_MON_SUPERROOT_RPC`) | `$SUPER_ROOT_RPC` |

Keep `--rollup-rpc`. `op-dispute-mon` discovers games from the existing `DisputeGameFactory` and does not need a game-type filter change. After the restart, confirm the existing-games metrics keep populating.

### Leave op-proposer Unchanged for Now

Skip `op-proposer` until cutover. Its configuration changes in [Switch op-proposer to Super Roots](#switch-op-proposer-to-super-roots).

## Generate the Starting Anchor Super Root

The upgrade must re-initialise `<ASR>` with a super-root-shaped starting anchor. The existing on-chain `startingAnchorRoot` is in output-root form (its `l2SequenceNumber` is an L2 block number), so the template must inject a fresh super-root value via `overrides.cfg.startingAnchorRoot` in `extraInstructions`. Confirm in the precondition above that the template has been extended to read this from TOML and pass it through.

Compute the value using `superroot_atTimestamp`. Pick the current finalized timestamp (or any recent finalized timestamp), then ask the single-chain RPC endpoint for the super root at that timestamp.

```bash theme={null}
# .finalized_l2.timestamp is a JSON number (decimal Unix seconds).
TS=$(cast rpc optimism_syncStatus --rpc-url $SUPER_ROOT_RPC | jq -r '.finalized_l2.timestamp')
# superroot_atTimestamp expects a hex-encoded JSON string (hexutil.Uint64); cast 2h handles the conversion.
cast rpc superroot_atTimestamp "$(cast 2h $TS)" --rpc-url $SUPER_ROOT_RPC | jq -r '.data.super_root'
echo "timestamp=$TS"
```

Capture two values:

* `super_root` (a `bytes32` hash from `.data.super_root`) — passed as `Proposal.root` in `overrides.cfg.startingAnchorRoot`.
* `timestamp` (the uint64 you passed in) — passed as `Proposal.l2SequenceNumber`. This field is the timestamp itself, not a block number or sequence index.

## Build the superchain-ops Task

Author a new task directory under `superchain-ops/src/tasks/<network>/<NNN-name>/` using the `OPCMUpgradeV800` template. The schema below assumes the template has been extended (per the precondition above) to also read a starting super-root anchor and inject it as `overrides.cfg.startingAnchorRoot`.

### Configure config.toml

```toml theme={null}
l2chains = [
    {name = "<chain name>", chainId = <chain id>},
]

templateName = "OPCMUpgradeV800"

[[opcmUpgrades]]
chainId = <chain id>
# Kona-interop super prestate, used by SUPER_CANNON_KONA. The `-interop` variant
# supports super roots and works whether
# or not interop is enabled or scheduled on the chain.
cannonKonaPrestate = "0x<kona-interop super prestate>"
expectedValidationErrors = ""   # fill in after the dry run
initBond = 80000000000000000    # 0.8 ether, applied to `SUPER_CANNON_KONA` games; the template always forces SUPER_PERMISSIONED to 0
startingRespectedGameType = <9 or 5>   # 9 permissionless, 5 permissioned

# Pending template extension — see the "Generate the Starting Anchor Super Root" section.
startingAnchorRoot = { root = "0x<super root hash>", l2SequenceNumber = <timestamp> }

[addresses]
OPCM = "0x<OPCM v8.x.y address>"
```

The template derives everything else (per-game-type config, `SuperchainConfig`, validator, etc.) automatically — no further TOML required.

### Capture expectedValidationErrors

Run the task in simulation mode against an L1 fork from inside the task directory:

```bash theme={null}
cd superchain-ops/src/tasks/<network>/<NNN-name>
just simulate
```

If the validator's output does not match `expectedValidationErrors` in TOML, the simulation reverts with a message of the form `Unexpected errors: <actual>; expected: <expectedValidationErrors>`. Read the actual codes from that revert message. The default expectation is **no errors** — `expectedValidationErrors = ""` and a clean simulation.

Any non-empty error string must be reviewed code by code, not copy-pasted. For each code:

* **Resolve it** if it points at a fixable input — a wrong address, a wrong prestate, a template release mismatch, a missing override, or a registry entry that needs updating.
* **Add it to `expectedValidationErrors` only after justifying it** with an inline comment in the TOML explaining why it is structurally expected for this chain.

The simulation passes once every printed code has been either resolved or knowingly added with justification. Treat any code you cannot explain as a hard stop.

## Execute the Upgrade

1. **Stop `op-proposer` for the chain.** Existing games continue to resolve; only new proposals halt.
2. **Leave `op-challenger` and `op-dispute-mon` running.** Both were configured earlier and pick up super-root games automatically.
3. **Sign and broadcast the task** using your team's standard `superchain-ops` signing workflow.
4. **Wait for the L1 transaction to confirm.**

The on-chain effect:

* `<ASR>` is re-initialised with the supplied anchor and respected game type. The retirement timestamp is not bumped, so existing in-flight games stay valid.
* The super dispute game implementation or implementations are installed on `<DGF>`.
* Implementation pointers for the game types passed with `enabled = false` are cleared, blocking creation of new games of those types.

## Verify the Upgrade On-Chain

Run the checks below before you cut `op-proposer` over.

<Warning>If any check fails, stop, do not start the new proposer, and escalate via your standard incident-response channel. Recovery from a half-cut state with a misbehaving proposer is materially harder than recovery from a paused proposer.</Warning>

### Common Checks

```bash theme={null}
# Respected game type
cast call <ASR> 'respectedGameType()(uint32)' --rpc-url $L1_RPC
# Expect: 9 (permissionless) or 5 (permissioned)

# Anchor root and timestamp
cast call <ASR> 'getAnchorRoot()(bytes32,uint256)' --rpc-url $L1_RPC
# Expect: (<super root hash>, <timestamp>) from the previous step

# Retirement timestamp unchanged
cast call <ASR> 'retirementTimestamp()(uint64)' --rpc-url $L1_RPC
# Expect: same value as before the upgrade

# Pre-migration impls cleared
cast call <DGF> 'gameImpls(uint32)(address)' 0 --rpc-url $L1_RPC   # CANNON
cast call <DGF> 'gameImpls(uint32)(address)' 1 --rpc-url $L1_RPC   # PERMISSIONED_CANNON
cast call <DGF> 'gameImpls(uint32)(address)' 8 --rpc-url $L1_RPC   # CANNON_KONA
# Expect each: 0x0000000000000000000000000000000000000000
```

### Permissionless Chain Checks

```bash theme={null}
cast call <DGF> 'gameImpls(uint32)(address)' 5 --rpc-url $L1_RPC   # SUPER_PERMISSIONED
cast call <DGF> 'gameImpls(uint32)(address)' 9 --rpc-url $L1_RPC   # SUPER_CANNON_KONA
# Expect both: non-zero

cast call <DGF> 'initBonds(uint32)(uint256)' 5 --rpc-url $L1_RPC
# Expect: 0
cast call <DGF> 'initBonds(uint32)(uint256)' 9 --rpc-url $L1_RPC
# Expect: 80000000000000000, or the configured SUPER_CANNON_KONA bond
```

### Permissioned Chain Checks

```bash theme={null}
cast call <DGF> 'gameImpls(uint32)(address)' 5 --rpc-url $L1_RPC   # SUPER_PERMISSIONED
# Expect: non-zero

cast call <DGF> 'initBonds(uint32)(uint256)' 5 --rpc-url $L1_RPC
# Expect: 0

cast call <DGF> 'gameImpls(uint32)(address)' 9 --rpc-url $L1_RPC   # SUPER_CANNON_KONA
# Expect: 0x0000000000000000000000000000000000000000
```

## Switch op-proposer to Super Roots

Start `op-proposer` with the new configuration.

| Flag (env var)                                                | Old        | New                                                                                                                  |
| ------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------- |
| `--rollup-rpc` (`OP_PROPOSER_ROLLUP_RPC`)                     | set        | **remove**                                                                                                           |
| `--superroot-rpcs` (`OP_PROPOSER_SUPERROOT_RPCS`)             | unset      | `$SUPER_ROOT_RPC`, or a list of high-availability endpoints that each return a super root containing only this chain |
| `--game-type` (`OP_PROPOSER_GAME_TYPE`)                       | `0` or `1` | numeric: `9` for permissionless, `5` for permissioned                                                                |
| `--game-factory-address` (`OP_PROPOSER_GAME_FACTORY_ADDRESS`) | unchanged  | unchanged (same `<DGF>`)                                                                                             |

Other flags such as `--proposal-interval` and `--poll-interval` stay the same.

After start-up, verify:

* The logs show the proposer polling the configured single-chain super-root RPC endpoint and contain no references to `--rollup-rpc`.

* Within one `--proposal-interval`, the proposer submits a new game. Inspect it:

  ```bash theme={null}
  COUNT=$(cast call <DGF> 'gameCount()(uint256)' --rpc-url $L1_RPC)
  # Expect: increased by 1 since the upgrade
  echo "gameCount=$COUNT"

  read -r GAME_TYPE CREATED_AT GAME_PROXY < <(cast call <DGF> 'gameAtIndex(uint256)(uint32,uint64,address)' $((COUNT-1)) --rpc-url $L1_RPC)
  # Expect: gameType matches the configured super type (5 or 9) and gameProxy is non-zero.
  echo "gameType=$GAME_TYPE createdAt=$CREATED_AT gameProxy=$GAME_PROXY"

  cast call $GAME_PROXY 'rootClaim()(bytes32)'        --rpc-url $L1_RPC
  cast call $GAME_PROXY 'l2SequenceNumber()(uint256)' --rpc-url $L1_RPC
  ```

* Recompute the super root for the proposed timestamp and confirm it matches the proposal:

  ```bash theme={null}
  cast rpc superroot_atTimestamp "$(cast 2h <l2SequenceNumber from above>)" \
    --rpc-url $SUPER_ROOT_RPC | jq -r '.data.super_root'
  # Expect: equals rootClaim from above
  ```

  This confirms `op-proposer` is correctly configured and passing valid super roots.

## Verify After the Upgrade

Run these checks once the proposer is stable.

* **Pre-migration game still resolves.** Pick a still-in-flight pre-migration game (use `op-dispute-mon` dashboards or `gameAtIndex` to find one) and watch its status until it resolves:

  ```bash theme={null}
  cast call <gameProxy> 'status()(uint8)' --rpc-url $L1_RPC
  # 0 = IN_PROGRESS, 1 = CHALLENGER_WINS, 2 = DEFENDER_WINS
  ```

* **`op-challenger` traces `SUPER_CANNON_KONA` when enabled.** On a permissionless chain, verify the startup log lists `super-cannon-kona` and ongoing logs contain no scheduler or game-poll errors as type-9 games appear. On a permissioned chain, `op-challenger` continues to update the `AnchorStateRegistry` when `SUPER_PERMISSIONED` games finalize but does not need to post claims.

* **`op-dispute-mon` reports super-root games.** Confirm `op_dispute_mon_games` reports the enabled super game types and `op_dispute_mon_failed_games` remains zero. On a permissioned chain, alert on `op_dispute_mon_games_agreement{status="disagree_defender_wins"}` and `Unexpected game result` logs for `SUPER_PERMISSIONED`.

* **No new pre-migration games can be created.** Optionally call `DisputeGameFactory.create` with one of the disabled game types and confirm it reverts.

* **Anchor advances on first super-game finalisation.** The first anchor update typically lands \~7 days after the first super-root game is created (game duration plus `DISPUTE_GAME_FINALITY_DELAY_SECONDS`). Do not block the rollout on this — schedule a follow-up to re-run `getAnchorRoot()` after that window and confirm it returns the new game's claim instead of the starting root. Track via `op-dispute-mon` rather than waiting in-line.


# EAS contracts and attestation schemas
Source: https://docs.optimism.io/governance/attestation-schemas

Contract addresses for the Ethereum Attestation Service and the attestation schemas used across the Optimism Collective.

This page catalogues the [Ethereum Attestation Service ("EAS")](https://attest.sh/) contract addresses on OP Mainnet and OP Sepolia, the ways to read and write attestations, and the attestation schemas used across the Optimism Collective.
For how attestations underpin identity in the Collective, see [How identity works in the Optimism Collective](/governance/eas-attestations).
For details on the EAS predeploys themselves, see the [smart contracts overview](/op-stack/protocol/smart-contracts#eas-ethereum-attestation-service).

## EAS contract addresses

The [Ethereum Attestation Service](https://docs.attest.sh/docs/welcome) is deployed on these addresses:

| **Network** | **Attestation Contract**                                                                                                               | **Schema Registry Contract**                                                                                                           |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| OP Sepolia  | [0x4200000000000000000000000000000000000021](https://sepolia-optimism.etherscan.io/address/0x4200000000000000000000000000000000000021) | [0x4200000000000000000000000000000000000020](https://sepolia-optimism.etherscan.io/address/0x4200000000000000000000000000000000000020) |
| OP Mainnet  | [0x4200000000000000000000000000000000000021](https://optimistic.etherscan.io/address/0x4200000000000000000000000000000000000021)       | [0x4200000000000000000000000000000000000020](https://optimistic.etherscan.io/address/0x4200000000000000000000000000000000000020)       |

## How to read and write attestations

You can read and write attestations in several ways:

* [EAS scan user interface (OP Mainnet)](https://optimism.easscan.org/)
* [EAS scan user interface (OP Sepolia)](https://optimism-sepolia.easscan.org/)
* [JavaScript SDK](https://docs.attest.sh/docs/developer-tools/eas-sdk)
* [Access directly onchain](https://github.com/ethereum-attestation-service/eas-contracts/blob/master/contracts/EAS.sol) (if you need to attest from a smart contract)

## Indexing

Indexing is available via:

* [GraphQL endpoint](https://docs.attest.sh/docs/developer-tools/api)
* [Ponder graph](https://github.com/ethereum-attestation-service/eas-ponder-graph)
* [Open source indexer](https://github.com/ethereum-attestation-service/eas-indexing-service)

## Schemas

Schemas define the structure and type of data that can be included in an attestation.

Below you will find a list of relevant schemas that are being used on OP Mainnet. Schemas are built using the [Ethereum Attestation Service](https://docs.attest.sh/docs/welcome).

### General schemas

* [**Gitcoin Passport V1 scores schema UID**](https://optimism.easscan.org/schema/view/0x6ab5d34260fca0cfcf0e76e96d439cace6aa7c3c019d7c4580ed52c6845e9c89): `0x6ab5d34260fca0cfcf0e76e96d439cace6aa7c3c019d7c4580ed52c6845e9c89`
* [**Superchain Faucet schema UID**](https://optimism.easscan.org/schema/view/0x98ef220cd2f94de79fbc343ef982bfa8f5b315dec6a08f413680ecb7085624d7): `0x98ef220cd2f94de79fbc343ef982bfa8f5b315dec6a08f413680ecb7085624d7`

### Schemas related to project creation and Retro Funding application

[**Project and organization identifier**](https://optimism.easscan.org/schema/view/0xff0b916851c1c5507406cfcaa60e5d549c91b7f642eb74e33b88143cae4b47d0)

Used as the unique identifier for projects and organizations created on or after 23 August 2024. For projects created earlier, please see the [archived schemas](#archived-schemas) at the bottom of this page.

| **Schema UID** | **`0xff0b916851c1c5507406cfcaa60e5d549c91b7f642eb74e33b88143cae4b47d0`**                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| Issuer         | Attestations issued as part of Retro Funding sign up are issued by `0xF6872D315CC2E1AfF6abae5dd814fd54755fE97C` |
| farcasterID    | The Farcaster id of the individual who created the project or organization                                      |
| type           | "Project" or "Organization"                                                                                     |

[**Organization metadata**](https://optimism.easscan.org/schema/view/0xc2b376d1a140287b1fa1519747baae1317cf37e0d27289b86f85aa7cebfd649f)

Used to associate metadata to an organization. Re-issued each time there is a change to metadata

| **Schema UID** | **`0xc2b376d1a140287b1fa1519747baae1317cf37e0d27289b86f85aa7cebfd649f`**                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| Issuer         | Attestations issued as part of Retro Funding sign up are issued by `0xF6872D315CC2E1AfF6abae5dd814fd54755fE97C` |
| Recipient      | Null                                                                                                            |
| RefUID         | The attestation UID of the organization this metadata relates to                                                |
| farcasterID    | The Farcaster id of the individual who published the organization metadata                                      |
| name           | The name of the organization                                                                                    |
| projects       | The array of projects that belong to this organization                                                          |
| parentOrgUID   | The attestation UID of this organization's parent, in case it has one                                           |
| metadataType   | How the metadata can be accessed. 1 for ipfs, 2 for http                                                        |
| metadataUrl    | The storage location where the metadata can be retrieved                                                        |

[**Project metadata**](https://optimism.easscan.org/schema/view/0xe035e3fe27a64c8d7291ae54c6e85676addcbc2d179224fe7fc1f7f05a8c6eac)

Used to associate metadata to a project. Re-issued each time there is a change to metadata.

| **Schema UID**       | **`0xe035e3fe27a64c8d7291ae54c6e85676addcbc2d179224fe7fc1f7f05a8c6eac`**                                        |
| -------------------- | --------------------------------------------------------------------------------------------------------------- |
| Issuer               | Attestations issued as part of Retro Funding sign up are issued by `0xF6872D315CC2E1AfF6abae5dd814fd54755fE97C` |
| Recipient            | Null                                                                                                            |
| projectRefUID        | The attestation UID of the project this metadata relates to                                                     |
| farcasterID          | The Farcaster id of the individual who published the project metadata                                           |
| name                 | The name of the project                                                                                         |
| category             | The category of the project                                                                                     |
| parentProject RefUID | The attestation UID of this project's parent project, in case it has a parent                                   |
| metadataType         | How the metadata can be accessed. 1 for ipfs, 2 for http                                                        |
| metadataUrl          | The storage location where the metadata can be retrieved                                                        |

[**Retro funding application**](https://optimism.easscan.org/schema/view/0x2169b74bfcb5d10a6616bbc8931dc1c56f8d1c305319a9eeca77623a991d4b80)

Used to identify a project's application to a specific Retro Funding Round. This attestation is used for Retro Funding Round 6 and beyond.

| **Schema UID**          | **`0x2169b74bfcb5d10a6616bbc8931dc1c56f8d1c305319a9eeca77623a991d4b80`**                                         |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Issuer                  | Attestations issued as part of Retro Funding sign up are issued by: `0xF6872D315CC2E1AfF6abae5dd814fd54755fE97C` |
| Recipient               | Null                                                                                                             |
| round                   | The round number for which this application was submitted                                                        |
| metadataType            | How the metadata can be accessed. 1 for ipfs, 2 for http                                                         |
| metadataUrl             | The storage location where the metadata can be retrieved                                                         |
| farcasterID             | The individual that submitted this application on behalf of the project.                                         |
| metadataSnapshot RefUID | The project metadata at the time the application was submitted.                                                  |

[**Retro funding application approval/rejection**](https://optimism.easscan.org/schema/view/0x683b1b399d47aabed79c9aa8f2674729021174b6e5cce1e20675eab404fc82d6)

Used to identify which Retro Funding applications have been approved or rejected.

| **Schema UID**        | **`0x683b1b399d47aabed79c9aa8f2674729021174b6e5cce1e20675eab404fc82d6`**                                                                                             |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuer                | Currently, the Optimism Foundation issues these from the following address: `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`                                             |
| Recipient             | Null                                                                                                                                                                 |
| projectApplicationUID | The unique identifier of the projects Retro Funding application.                                                                                                     |
| Status                | The status of the Retro Funding application.                                                                                                                         |
| Reason                | Identifier for the reason an application was rejected. 1 = "Duplicate Application", 2 = "Deceiving Badgeholders", 3 = "Spam", 4 = "Not meeting eligibility criteria" |

[**Retro funding rewards**](https://optimism.easscan.org/schema/view/0x670ad6e6ffb842d37e050ea6d3a5ab308195c6f584cf2121076067e0d8adde18)

Used to identify the reward amount each approved project received in a Retro Funding round

| **Schema UID** | **`0x670ad6e6ffb842d37e050ea6d3a5ab308195c6f584cf2121076067e0d8adde18`**                                                 |
| -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Issuer         | Currently, the Optimism Foundation issues these from the following address: `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F` |
| Recipient      | Null                                                                                                                     |
| refUID         | The UID of the Retro Funding application                                                                                 |
| projectRefUID  | The unique identifier of the project                                                                                     |
| round          | The retro round for which the project was rewarded                                                                       |
| OPamount       | The amount of OP awarded to the project                                                                                  |

### Schemas related to token house grants

[**Token house grant approved**](https://optimism.easscan.org/schema/view/0x8aef6b9adab6252367588ad337f304da1c060cc3190f01d7b72c7e512b9bfb38)

Issued by the Grants Council when a project is approved for a grant. Does not indicate that the grant has been completed.

| **Schema UID**   | **`0x8aef6b9adab6252367588ad337f304da1c060cc3190f01d7b72c7e512b9bfb38`**          |
| ---------------- | --------------------------------------------------------------------------------- |
| Issuer           | Currently issued by the Grants Council lead.                                      |
| Recipient        | The address where the tokens will be delivered once the grant has been completed. |
| refUID           | Currently null                                                                    |
| projectRefUID    | The unique identifier of the project that was approved for the grant.             |
| UserIncentivesOP | The OP amount approved for user incentives.                                       |
| BuildersOP       | The OP amount approved for the builder.                                           |
| Season           | The season (number) in which the grant was approved                               |
| Intent           | The intent (number) to which the mission belongs                                  |
| Mission          | The name of the mission (in words) under which this grant was made.               |
| Approval date    | The date the grant was approved, in the following format MM/DD/YYYY               |
| MetadataUrl      | Currently null                                                                    |

### Schemas related to roles and contributions

[**Citizens**](https://optimism.easscan.org/schema/view/0xc35634c4ca8a54dce0a2af61a9a9a5a3067398cb3916b133238c4f6ba721bc8a)

Citizen attestations were first issued in Season 6 and are used to represent Citizenship separately from the ability to vote in a specific Retro Round. The resolver contract checks that the issuer is the Foundation with following address `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`

| **Schema UID**  | **`0xc35634c4ca8a54dce0a2af61a9a9a5a3067398cb3916b133238c4f6ba721bc8a`**                                                                                       |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RefUID          | In case the Citizen is a chain or an app, the refUID field will reference the organization/project id of the chain or app. If null, the Citizen is an end-user |
| FarcasterID     | The Citizen's unique identifier                                                                                                                                |
| SelectionMethod | A Code representing the method through which the Citizen was selected. Codes beginning with the number 1 refer to various flavours of Web of Trust selection.  |

[**Retro funding voters**](https://optimism.easscan.org/schema/view/0x41513aa7b99bfea09d389c74aacedaeb13c28fb748569e9e2400109cbe284ee5)

These attestations are voting Badges issued for Retro Round 5 and beyond. They are different from the [previous schema](https://optimism.easscan.org/schema/view/0xfdcfdad2dbe7489e0ce56b260348b7f14e8365a8a325aef9834818c00d46b31b) to include new fields like votingGroup, used to assign voters to sub-categories in the round.

| **Schema UID**  | **`0x41513aa7b99bfea09d389c74aacedaeb13c28fb748569e9e2400109cbe284ee5`**   |
| --------------- | -------------------------------------------------------------------------- |
| FarcasterID     | The voter's unique identifier                                              |
| Round           | The round number for which this voting Badge was valid                     |
| voterType       | Guest or Citizen                                                           |
| votingGroup     | Used to assign voters to subcategories in case the Round has subcategories |
| selectionMethod | The method in which this voter was selected                                |

[**MetaGov contribution**](https://optimism.easscan.org/schema/view/0x84260b9102b41041692558a4e0cba6b7e5f9b813be56402c3db820c06dd4a5f1)

| **Schema UID**    | **`0x84260b9102b41041692558a4e0cba6b7e5f9b813be56402c3db820c06dd4a5f1`**                                                                                                           |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuer            | Currently, the Optimism Foundation issues these from one of the following addresses: `0x621477dBA416E12df7FF0d48E14c4D20DC85D7D9` or `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`. |
| Recipient         | The address of the individual who made the contribution                                                                                                                            |
| refUID            | The UID of the project, in case this contribution is represented as a project                                                                                                      |
| FarcasterID       | The id of the individual who made the contribution, if known                                                                                                                       |
| Impact            | This field is not currently being used                                                                                                                                             |
| Season            | The season in which the contribution was made                                                                                                                                      |
| Decision Module   | The decision module to which the contribution relates                                                                                                                              |
| Contribution Type | The type of contribution                                                                                                                                                           |
| MetadataUrl       | This field is not currently being used                                                                                                                                             |

[**Foundation mission request completed**](https://optimism.easscan.org/schema/view/0x649cc6df5af7561b66384405a62682c44e2428584d2f17a202ac3ef4506e2457)

| **Schema UID** | **`0x649cc6df5af7561b66384405a62682c44e2428584d2f17a202ac3ef4506e2457`**                                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuer         | Currently, the Optimism Foundation issues these from one of the following addresses: `0x621477dBA416E12df7FF0d48E14c4D20DC85D7D9` or `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`. |
| projectRefUID  | The UID of the project that represents the work completed as part of the Foundation Mission Request                                                                                |
| OP Amount      | The OP Amount that was awarded for the completion of this Mission Request                                                                                                          |
| Season         | The season in which this Mission Request was completed                                                                                                                             |

[**Retro funding governance contribution**](https://optimism.easscan.org/schema/view/0x3743be2afa818ee40304516c153427be55931f238d961af5d98653a93192cdb3)

| **Schema UID**         | **`0x3743be2afa818ee40304516c153427be55931f238d961af5d98653a93192cdb3`**                                                                                                           |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuer                 | Currently, the Optimism Foundation issues these from one of the following addresses: `0x621477dBA416E12df7FF0d48E14c4D20DC85D7D9` or `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`. |
| Recipient              | The address of the individual who made the contribution                                                                                                                            |
| Rpgf\_round            | The round number for which this contribution was made                                                                                                                              |
| RetroPGF\_Contribution | The type of contribution made                                                                                                                                                      |

[**Governance contribution**](https://optimism.easscan.org/schema/view/0xef874554718a2afc254b064e5ce9c58c9082fb9f770250499bf406fc112bd315)

Issued to those who held governance roles in the Collective, such as Grants Council members.

| **Schema UID** | **`0xef874554718a2afc254b064e5ce9c58c9082fb9f770250499bf406fc112bd315`**                                                                                                           |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuer         | Currently, the Optimism Foundation issues these from one of the following addresses: `0x621477dBA416E12df7FF0d48E14c4D20DC85D7D9` or `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`. |
| Recipient      | The address of the individual who made the contribution                                                                                                                            |
| govSeason      | The season the individual held the role                                                                                                                                            |
| govRole        | The role held by the individual                                                                                                                                                    |

### Archived schemas

These schemas are no longer being actively issued, but capture valuable historical data.

[**Retro funding application**](https://optimism.easscan.org/schema/view/0x88b62595c76fbcd261710d0930b5f1cc2e56758e155dea537f82bf0baadd9a32)

Used to identify a project's application to a specific Retro Funding Round. This attestation was used for Retro Funding Rounds 4 and 5.

| **Schema UID**          | **`0x88b62595c76fbcd261710d0930b5f1cc2e56758e155dea537f82bf0baadd9a32`**                                         |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Issuer                  | Attestations issued as part of Retro Funding sign up are issued by: `0xF6872D315CC2E1AfF6abae5dd814fd54755fE97C` |
| Recipient               | Null                                                                                                             |
| round                   | The round number for which this application was submitted                                                        |
| projectRefUID           | The unique identifier of the project that submitted this application                                             |
| farcasterID             | The individual that submitted this application on behalf of the project.                                         |
| metadataSnapshot RefUID | The project metadata at the time the application was submitted.                                                  |

[**Retro funding badgeholders**](https://optimism.easscan.org/schema/view/0xfdcfdad2dbe7489e0ce56b260348b7f14e8365a8a325aef9834818c00d46b31b)

These attestations are considered "voting Badges" and allow an individual to vote in any given iteration of Retro Funding. They were used up to and including Retro Round 4.

| **Schema UID** | **`0xfdcfdad2dbe7489e0ce56b260348b7f14e8365a8a325aef9834818c00d46b31b`**                                                                                                          |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Issuer         | Currently, the Optimism Foundation issues these from one of the following addresses: `0x621477dBA416E12df7FF0d48E14c4D20DC85D7D9` or `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F` |
| Recipient      | The Badgeholder's address                                                                                                                                                         |
| rpgfRound      | The round number for which this voting Badge was valid                                                                                                                            |
| referredBy     | In early rounds, new Badges were issued by referral. This field captures the address of the referrer, if there was one                                                            |
| referredMethod | If this voting Badge was issued by referral, this field captures the referral method                                                                                              |

[**Project identifier**](https://optimism.easscan.org/schema/view/0x7ae9f4adabd9214049df72f58eceffc48c4a69e920882f5b06a6c69a3157e5bd)

Used as the unique identifier for projects created in the Collective before 23 August 2024. Attestations issued from this schema prior to 23 August 2024 are still used as the unique identifier for projects. New projects created after 23 August 2024 use the new entity identifier (see above).

| **Schema UID** | **`0x7ae9f4adabd9214049df72f58eceffc48c4a69e920882f5b06a6c69a3157e5bd`**                                        |
| -------------- | --------------------------------------------------------------------------------------------------------------- |
| Issuer         | Attestations issued as part of Retro Funding sign up are issued by `0xF6872D315CC2E1AfF6abae5dd814fd54755fE97C` |
| Recipient      | Null                                                                                                            |
| farcasterID    | The Farcaster id of the individual who created the project                                                      |

* [**RetroPGF 3 Approved Application schema UID**](https://optimism.easscan.org/schema/view/0xebbf697d5d3ca4b53579917ffc3597fb8d1a85b8c6ca10ec10039709903b9277): `0xebbf697d5d3ca4b53579917ffc3597fb8d1a85b8c6ca10ec10039709903b9277`. Important: Remember to verify the attester address is `0x621477dBA416E12df7FF0d48E14c4D20DC85D7D9`
* [**RetroPGF 3 Application schema UID**](https://optimism.easscan.org/schema/view/0x76e98cce95f3ba992c2ee25cef25f756495147608a3da3aa2e5ca43109fe77cc): `0x76e98cce95f3ba992c2ee25cef25f756495147608a3da3aa2e5ca43109fe77cc`
* [**RetroPGF 3 Lists schema UID**](https://optimism.easscan.org/schema/view/0x3e3e2172aebb902cf7aa6e1820809c5b469af139e7a4265442b1c22b97c6b2a5): `0x3e3e2172aebb902cf7aa6e1820809c5b469af139e7a4265442b1c22b97c6b2a5`
* [**Season 4 Co-grant participant schema UID**](https://optimism.easscan.org/schema/view/0x401a80196f3805c57b00482ae2b575a9f270562b6b6de7711af9837f08fa0faf): `0x401a80196f3805c57b00482ae2b575a9f270562b6b6de7711af9837f08fa0faf`. Important: Remember to verify the attester address is `0x3C7820f2874b665AC7471f84f5cbd6E12871F4cC` or `0x2a0eB7cAE52B68e94FF6ab0bFcf0dF8EeEB624be`
* [**Optimist Profile schema UID**](https://optimism.easscan.org/schema/view/0xac4c92fc5c7babed88f78a917cdbcdc1c496a8f4ab2d5b2ec29402736b2cf929): `0xac4c92fc5c7babed88f78a917cdbcdc1c496a8f4ab2d5b2ec29402736b2cf929`


# Capital Allocation
Source: https://docs.optimism.io/governance/capital-allocation

Learn how Optimism allocates capital for long-term success.

## How does Optimism ensure long-term success?

Optimism strives to create a sustainable ecosystem flywheel. In this flywheel, revenue contributed by OP Chains to the Optimism Collective funds open-source development and drives ecosystem growth, which strengthens the OP Stack and attracts more end-users, apps, integration partners, and chains.

In implementing this flywheel, Optimism uses a public decision making process designed to prevent short-term profit seeking at the expense of the platform, while ensuring organizations contributing the OP Stack remain accountable to tokenholders and customers. This process includes a capital allocation model, designed to avoid many of the common failure modes of corporate governance, aiming to ensure the product always remains at the cutting edge.

For more details, please see the [Operating Manual.](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md)

<img alt="capital alloction" />

## How does Optimism generate revenue?

OP Chains in the Superchain earn transaction fees whenever users send transactions onchain, including for payments, trading, identity, and other applications. Each chain also pays costs to publish its activity to Ethereum for security.

OP Chains contribute a portion of their revenue to Optimism. This treasury is used to drive growth, provide shared infrastructure, and fund open source contributions that benefit the Superchain.

Superchain member chains contribute the greater of:

* 15% of net transaction fee profit (transaction fees earned on L2 - costs paid to Ethereum L1), or
* 2.5% of gross transaction fees

OP Mainnet contributes 100% of its revenue to this shared treasury.

You can find more information about revenue in the [Superchain Revenue Explainer documentation](/superchain/superchain-information/superchain-revenue-explainer).

The wallets across L1 and OP Mainnet where this revenue sits, along with the Optimism Foundation treasury and grants wallet addresses, are listed under [relevant addresses](/governance/resources#relevant-addresses) on the dashboards, trackers, and addresses page.

## How is the treasury managed?

The treasury is currently stewarded by the Foundation, but is subject to oversight by key stakeholder groups, via Optimism's public decision making process. Specifically, tokenholders, chains, apps, and users are asked to oversee annual budgets, which enable the Foundation to deploy the treasury into initiatives aimed at generated the sustainable flywheel described above.

Foundation Budget Reports can be found [here](https://gov.optimism.io/c/updates-and-announcements/foundation-budgets/) on the governance forum.

The OP Token Unlock (Estimated) tracker is listed under [OP trackers](/governance/resources#op-trackers) on the dashboards, trackers, and addresses page.

You can find more information via the Operating Manual [here](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md).

## What is Optimism's commitment to Open Source Software?

Optimism has always been committed to funding open-source software. OP Labs, a core contributor to the OP Stack, is registered as a public benefit corporation with a mission to enhance and enshrine access to public goods. The OP Stack is MIT licensed and Optimism dedicates a significant portion of its treasury to funding public goods and open-source software.

Optimism operates various grant programs to incentivize and reward open-source contributions. Grant programs can be found via [atlas.optimism.io](http://atlas.optimism.io).

## What can I do with the OP Token?

The OP token was created in May of 2022, with an initial supply of 4,294,967,296 OP tokens. The token was launched as a governance token to enable tokenholders to weigh in on technical and economic decisions that impact Optimism, such as protocol upgrades and capital allocation. The Optimism Foundation estimates the total supply of circulating OP tokens to increase as detailed in the [OP Token Unlock (Estimated) tracker](/governance/resources#op-trackers).

Tokenholders can use OP to vote on:

* Protocol Upgrades
* Token Allocations
* Adjusting Inflation
* Removing the Director of the Optimism Foundation
* Dissolutions
* Elections (and representative removal)
* Protecting the rights of tokenholders by consenting to any changes to the founding documents of the Optimism Foundation, if those changes would materially reduce their rights.
* Ratification of Governing Documents

You can find full details of what Tokenholders can vote with the Operating Manual [here](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md). You can sign up to vote with your tokens [here](https://vote.optimism.io/delegates).


# How identity works in the Optimism Collective
Source: https://docs.optimism.io/governance/eas-attestations

Learn how the Optimism Collective uses onchain attestations to represent Citizenship, project identity, and governance roles.

Optimism governance gives a voice to several distinct stakeholder groups: tokenholders, chains, apps, and end-users.
Token House voting power is straightforward to establish — it follows OP token holdings.
The rest of the system is harder: the Citizens' House uses a "1 member, 1 vote" model, Retro Funding rewards specific projects for their impact, and elected roles carry responsibilities across Seasons.
All of that requires a shared, verifiable answer to the question "who is this participant?" — without handing the answer to a private membership database.

The Collective's answer is **attestations**: signed onchain statements, published where anyone can read and verify them.
This page explains what attestations are, how the Collective uses them, and why the model works the way it does.

## Attestations and the Ethereum Attestation Service

An attestation is an onchain record in which one account (the issuer) makes a structured claim — for example, "this address is a Citizen" or "this project applied to Retro Funding Round 6."

Attestations in the Collective are built on the [Ethereum Attestation Service ("EAS")](https://attest.sh/), an open-source public good that is included as a predeploy in the OP Stack.
Every OP Stack chain ships with two EAS contracts at fixed addresses:

* The **EAS contract** (`0x4200000000000000000000000000000000000021`), where attestations are created and stored.
* The **SchemaRegistry contract** (`0x4200000000000000000000000000000000000020`), which holds the schemas that attestations are checked against.

Because these are predeploys, the same identity infrastructure is available on OP Mainnet, OP Sepolia, and any other OP Stack chain, with no extra deployment.
For predeploy details, see the [smart contracts overview](/op-stack/protocol/smart-contracts#eas-ethereum-attestation-service).

### Schemas give attestations structure

A schema defines the structure and type of data that an attestation can carry, and each schema has a unique identifier (UID).
This is what makes attestations machine-readable rather than free-form claims: an application that wants to check Citizenship looks for attestations issued against the specific Citizen schema UID, and knows exactly which fields (such as the member's Farcaster ID and selection method) it will find there.

The full catalogue of schemas the Collective uses — with their UIDs, issuers, and field-by-field descriptions — is maintained in the [EAS contracts and attestation schemas reference](/governance/attestation-schemas).

### Trust comes from the issuer, not the statement

Anyone can issue an attestation, so an attestation on its own proves only that *someone* made a claim.
What makes an attestation meaningful is *who issued it*.
Citizen attestations, for example, are only valid when issued by the Optimism Foundation, and the schema's resolver contract enforces that check onchain.
Other schemas document their expected issuer addresses so that consumers can verify them — several archived schemas explicitly remind readers to verify the attester address before trusting the record.

This is the core design trade-off: rather than a closed registry that must be queried and trusted wholesale, the Collective publishes individually signed claims and lets every consumer verify the issuer for themselves.

## How the Collective uses attestations

### Citizenship

Membership in the Citizens' House is represented by Citizen attestations, first issued in Season 6.
A Citizen attestation identifies the member (by Farcaster ID), records how they were selected, and — for chain and app Citizens — references the organization or project they represent.
Citizenship is recorded separately from the ability to vote in any specific Retro Funding round.
To learn who is eligible and how to register, see the [governance FAQ](/governance/gov-faq).

### Projects and organizations

Projects and organizations in the Collective (as registered in [OP Atlas](https://atlas.optimism.io)) are identified by attestations: an identifier attestation acts as the project's unique ID, and metadata attestations — re-issued each time something changes — associate names, categories, and metadata locations with it.
This is how Retro Funding knows which project an application, approval, or reward belongs to.

### Retro Funding and grants

The Retro Funding lifecycle is recorded as a chain of attestations: applications to a round, approval or rejection decisions, voting badges for the round's voters, and finally the reward amount each approved project received.
Token House grant approvals and governance contributions (such as serving on the Grants Council) are attested in the same way.

### Proof of personhood

For end-user Citizens, the Collective relies on external proof-of-personhood systems — [World ID](https://world.org/world-id) and [Passport](https://app.passport.xyz/) — alongside attestations such as Gitcoin Passport scores.
Until Sybil-resistance mechanisms are more mature, the Optimism Foundation may suspend Citizens flagged as possible Sybils and request further verification of unique personhood.

## Next steps

* Look up contract addresses, schema UIDs, and field definitions in the [EAS contracts and attestation schemas reference](/governance/attestation-schemas).
* Read or issue attestations via [EAS scan for OP Mainnet](https://optimism.easscan.org/) or the [EAS SDK](https://docs.attest.sh/docs/developer-tools/eas-sdk).
* Learn how the Token House and Citizens' House use these identities in the [governance FAQ](/governance/gov-faq).


# Evolution & Experimentation
Source: https://docs.optimism.io/governance/evolution-and-experimentation

Learn about Optimism's commitment to iterative improvement and experimentation.

## Evolution

In our pursuit to design a new type of organization, Optimism's public decision making process has undergone significant evolution since its inception, reflecting Optimism's commitment to iterative improvement and experimentation.
Below is a summary of some of the key things we learned along the way.

### Key Stakeholders

* We've run multiple experiments to understand who our most engaged stakeholders are and how they participate in our public decision making process.
* **Tokenholders:** Anyone who holds OP can vote
  * We've also run multiple delegation experiments aimed at getting if specific types of tokenholders (protocols, chains, and individual community members) more involved. Our main learning has been that tokenholders need strong incentive alignment to invest time in decision making processes and they want to be involved in low effort, high impact ways.
  * While our system allows for delegation - whereby tokenholders can assign their votes to someone else to cast on their behalf - over time we've come to believe that delegation disrupts the incentives of token-weighted voting and that voting directly should be heavily encouraged.
  * Tokenholders are asked to make decisions that would benefit from investor protections
* **Users, Apps, and Chains:** You must qualify to be a Citizen
  * Citizenship started with a small initial group and expanded via a Web of Trust model. This model suffered from in-group dynamics (which were replicated here), resulting in many Citizens that were impacted by the decisions being made.
  * We later ran targeted experiments to evaluate how community members, chains, and past grant recipients voted, ultimately resulting in our key stakeholder model. Our stakeholder models ensures chains, apps, and end-users are able to influence the decisions that impact them.
  * Citizens are asked to make decisions that would benefit from consumer protections
* We've realized that input from different stakeholders is needed depending on the type of decision being made:
  * **Preferences**: There is no absolute "right" answer and all stakeholders should have a say
  * **Prediction**: There is a correct answer, which is only revealed in the future. Experts are best suited to make these decisions.
    * When “experts” are needed, these decisions are made by Councils and Boards -  such as the Developer Advisory Board and Security Council. These Councils and Boards are still ultimately accountable to key stakeholders.
  * **Measurement**: This is best done objectively, by a computer, when possible, or by experts.

### High Impact Inputs

* Different decisions impact each stakeholder group in unique ways. Our approach has evolved from “everyone decides everything” to one that only asks stakeholders to make decisions that directly impact them.
* In many cases, a stakeholder doesn't need to make a decision directly, but should still have the ability to veto - or reject - a decision that disadvantages their stakeholder group.
* Stakeholders will also be able to express preferences and influence strategy via non-voting processes.
* We've outlined the different decisions here: Figma

### The Core Set of Decisions

* Governance minimization is a foundational principle of Optimism's collective decision making process. Our evolution has been one of continuously simplifying process, reducing structure, and further refining scope.
* We've learned over time that several decisions that used to be made publicly, actually benefit from more centralized decision making (CoCC, CFC, BB.)
* We believe the set of decisions that should be made collectively are those that:
  * Reduce platform risk for customers and users of the protocol
  * Prevent short-term profit seeking at the long-term expense of the platform
* Optimism has always been committed to supporting public goods, but the way we support public goods has evolved greatly over time. We started with a fully public grant making process, which gradually evolved to be more metrics-driven and programmatic approach, requiring less human input. We expect this to be a continued area of evolution and innovation.
* Our Decentralization Milestones outlines the remaining steps we hope to take to refine and further decentralize our public decision making process.

## Experimentation

Underpinning the learnings outlined above is a culture of experimentation. In our early days, our [iterative approach](https://gov.optimism.io/t/the-path-to-open-metagovernance/7728) sometimes involved a less-scientific, trial-and-error approach. Over time, we've realized a more rigorous, data-driven approach - leveraging controlled trials where possible - allows us to truly understand what works and what doesn't.

A sample of our Research & Experiments findings are summarized in the table below. We often collaborate with academics, industry experts, and independent researchers.

| **Topic**                | **Research question**                                                                                                       | **Methods**                                                                   | **Key Takeaways**                                                                                                                                                                                        | **Write-up**                                                                                                                                                                                                                                                                                                                                           |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Airdrops**             | Do airdrops drive prosocial behaviors like delegation? Do they increase retention among new users?                          | Regression discontinuity design (RDD)                                         | Increased delegation esp among small wallets; Baseline reward increases retention but high activity bonuses decrease retention                                                                           | - [Did OP Airdrop 2 Increase Governance Engagement?](https://gov.optimism.io/t/did-op-airdrop-2-increase-governance-engagement/7270) <br /> - [Did OP Airdrop 5 Increase User Retention Rates? A Regression Discontinuity Analysis](https://gov.optimism.io/t/did-op-airdrop-5-increase-user-retention-rates-a-regression-discontinuity-analysis/9610) |
| **Citizenship**          | How do we identify key stakeholders (eg, end users, app devs, or partner chains) and give them decision-making rights?      | Voting data analysis, surveys, qualitative interviews                         | Experts no “better” at values questions but better at assessing impact; Guest voters don’t vote differently to existing set; 3 clear personas                                                            | - [Citizenship Learnings 2024](https://gov.optimism.io/t/citizenship-learnings-2024/9563)                                                                                                                                                                                                                                                              |
| **Deliberation**         | How does participating in a deliberative process with direct policy implications change individual attitudes and behaviors? | Randomized experiment, instrumental variable regression                       | Deliberation increases knowledge and trust; No reduction in polarization when outcome is binding                                                                                                         | - [When Is Deliberation Useful for Optimism Governance?](https://gov.optimism.io/t/when-is-deliberation-useful-for-optimism-governance/9142)                                                                                                                                                                                                           |
| **Futarchy**             | Do projects selected via Futarchy see greater increase in TVL than projects selected by existing Grants Council?            | Time-series analysis, RDD, analysis of telegram, survey, and trading data     | Futarchy grants produced more Superchain TVL after 3 months than Grants Council picks; Predictions notably overpriced; 400+ forecasters participated                                                     | - [Futarchy v1 Preliminary Findings](https://gov.optimism.io/t/futarchy-v1-preliminary-findings/10062)                                                                                                                                                                                                                                                 |
| **Public Goods Funding** | What voting designs lead to impactful grant allocation decisions? Does algorithmic/ metrics-based voting improve outcomes?  | Voting data analysis, synthetic control method, surveys, qualitative feedback | Humans are bad at quantification and bias toward even distributions rather than reflecting value; Experts with context make better decisions for OSS; Individual bias about impact vs need is inevitable | - [Retro Funding 4: Learnings and Reflections](https://gov.optimism.io/t/retro-funding-4-learnings-and-reflections/9271) <br /> - [Season 7 Retro Funding - Early Evidence on Developer Tooling Impact](https://gov.optimism.io/t/season-7-retro-funding-early-evidence-on-developer-tooling-impact/10162)                                             |
| **Voter mobilization**   | Do appeals to civic duty, economic self-interest, collective security, or decision authority increase tokenholder turnout?  | Randomized multi-wave experiment                                              | Economic and security (tangible stakes) were most effective in driving turnout; Repeated reminders are necessary to sustain increase in participation; catchy visuals and follow-ups important           | - “What Drives Turnout in Digital Governance? Evidence from a Multi-stage Voter Mobilization Experiment among 34,328 Tokenholders” (Draft available upon request: [eliza@optimism.io](mailto:eliza@optimism.io))                                                                                                                                       |


# FAQs
Source: https://docs.optimism.io/governance/gov-faq

Frequently Asked Questions about how Optimism evolves.

<AccordionGroup>
  <Accordion title="What is the Token House?">
    All OP tokenholders, a key stakeholder group, are represented in governance via the Token House. The Token House uses token-weighted voting, giving influence proportional to OP token holdings. Tokenholders may vote themselves or assign their voting power to a “delegate.” The primary role of tokenholders is to express their financial interest in the evolution of the Superchain and to hold proposers accountable. Tokenholders may vote on:

    **Protocol Upgrades**

    Delegates have the power to veto decisions about protocol upgrades made by the Developer Advisory Board (DAB). This veto power serves as a critical check on technical changes, with the aim of ensuring they align with the interests of those who rely on the protocol.

    **Capital Allocation**

    Delegates participate in resource allocation decisions, including:

    * Approving the Collective Intent, missions, and budget
    * Approving Governance Fund proposals

    **Representative Elections**

    Delegates elect members to the Councils and Boards and/or approve any alternative selection mechanisms

    **Ratification**

    Delegates may ratify core governing documents.

    For a full description of the voting mechanics for each of these proposal types, please refer to the [Operating Manual](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md). In future phases, the Token House may gain additional governance powers.
  </Accordion>

  <Accordion title="How do I vote with my tokens?">
    **Unlock Your Voting Power**

    OP token holders are able to vote on some of the most important decisions for the Collective. This empowers one of the Collective's key stakeholders to have a say in the development of the system.

    You can either vote yourself with your OP tokens, or you can delegate the voting power of your OP tokens to someone else to make decisions on your behalf.

    Get started at [vote.optimism.io/delegates](http://vote.optimism.io/delegates)
  </Accordion>

  <Accordion title="What is the Citizens' House?">
    Users, Apps, and Chains, key stakeholder groups, are represented in governance via the Citizens’ House. The Citizens' House uses a ‘1 member, 1 vote’ model, so all members have the same level of influence. The primary role of Citizens is to express their preferences in the evolution of the Superchain and to hold proposers accountable. Citizens may vote on:

    ### **Protocol Upgrades**

    Citizens have the power to veto decisions about protocol upgrades made by the Developer Advisory Board (DAB). This veto power serves as a critical check on technical changes, ensuring they align with the interests of those who rely on the protocol.

    ### **Resource Allocation**

    Citizens participate in resource allocation decisions, including:

    * Approving the Collective Intent, missions, and budget

    ### **Representative Elections**

    Citizens elect representatives to the Developer Advisory Board, ensuring it remains accountable to their interests.

    ### **Ratification**

    Citizens may ratify core governing documents.

    For a full description of the voting mechanics for each of these proposal types, please refer to the [Operating Manual](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md). In future phases, the Citizens’ House may gain additional governance powers.
  </Accordion>

  <Accordion title="How do I become a Citizen?">
    ## **Eligibility Framework and Principles**

    The Citizens' House relies on a carefully designed eligibility framework aimed at achieving representation from key stakeholders in the Superchain ecosystem. This framework is built on the following principles:

    1.Those who are most impacted by Protocol Upgrades should have governance power over them

    2.Those who contribute most to shared resources should have a voice in the governance of those shared resources

    Eligibility criteria include three distinct stakeholder groups within the Citizens' House:

    1.Chains

    2.Onchain Applications

    3.Superchain End-Users

    ## **Citizenship Eligibility Criteria**

    Eligibility is recalculated at the beginning of every Season, and criteria are subject to change.

    ## **Chain Citizens**

    ### **Eligibility Criteria in Season 9**

    Chains are eligible to vote in the Citizens' House if they meet either of these criteria:

    * Account for at least 2% of the total revenue share contributed by all chains in the past Season
    * Are among the top 15 chains by revenue contribution in the past Season

    Eligibility for Season 9 is calculated based on activity from 01 August 2025 - 31 December 2025. This approach aims to give chains with significant economic stake in the ecosystem a voice in governance, while the minimum number of seats (15) should mean broad representation even if revenue becomes concentrated.

    ## **App Citizens**

    ### **Eligibility Criteria**

    Onchain applications are eligible to join the Citizens' House if they meet either of these criteria:

    * Are responsible for at least 0.5% of the total gas used across the Superchain over the past Season
    * Are among the top 100 apps by gas usage in the past Season

    Eligibility for Season 9 is calculated based on activity from 01 August 2025 - 31 December 2025 based on contract data registered by projects in OP Atlas. Projects/contracts not registered in OP Atlas cannot be considered at this time. This approach aims to give applications driving significant activity on the Superchain a voice in governance, while the minimum number of seats (100) should mean broad representation from the application ecosystem.

    ## **End-user Citizens**

    ### **Eligibility Criteria**

    Individual end-users are eligible to join the Citizens' House if they meet all of these criteria:

    * Had their first Superchain transaction before June 1, 2024
    * Have at least 2 Superchain transactions each month in at least 3 distinct months from 01 August 2025 - 31 December 2025
    * Can provide proof of personhood through [World ID](https://world.org/world-id) or [Passport](https://app.passport.xyz/)

    To check the eligibility of your address, navigate to [atlas.optimism.io/citizenship](http://atlas.optimism.io/citizenship) and link the address to your Atlas profile. These criteria are designed so that Citizens will be genuine, active users of the Superchain with sustained engagement over time, rather than one-time or sporadic users.

    ### **Selection Process**

    To register as an end-user Citizen, please visit [https://atlas.optimism.io/citizenship](https://atlas.optimism.io/citizenship)

    Until Sybil-resistance mechanisms are more mature, the Optimism Foundation may suspend Citizens flagged as possible Sybils and request further verification of unique personhood.
  </Accordion>

  <Accordion title="How do the Token House and the Citizens' House work together? ">
    The Token House and the Citizens' House together represent all key stakeholders of the Superchain: tokenholders, chains, apps, and end-users. Both houses vote on proposals when the interests of all stakeholders should be represented in a particular decision. Each house has a distinct voting mechanism which, when combined together, creates a system of checks and balances aimed at balancing competing interests.

    Voting happens on a regular schedule via three-week voting cycles. Regular voting Cycles begin on Thursday at 19:00p GMT (12p PST) and end on Wednesday at 19:00 GMT (12p PST). Protocol Upgrades may go through an accelerated process. You can view full details [here](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md). You can track cycles on [the governance calendar](https://calendar.google.com/calendar/u/0/r?cid=Y180aHVpNzBpdG0wODllN3Q4cTUwaGVoMWtub0Bncm91cC5jYWxlbmRhci5nb29nbGUuY29t).
  </Accordion>

  <Accordion title="What is expected of voters?">
    Key stakeholders of the Superchain can protect their interests by participating in Optimism's public decision making process (governance). This process allows stakeholders to influence the future of the Superchain with limited day-to-day involvement.

    Key stakeholders will be asked to:

    * **Vote:** 1-2 times per year
    * **Provide input:** 3-4 times per year
    * **Veto:** only as needed

    Email notifications will be sent to all stakeholders whenever any of the above actions is possible. Stakeholders can also monitor activity directly at [vote.optimism.io](http://vote.optimism.io) or [atlas.optimism.io](http://atlas.optimism.io)

    **Token House Voters**

    1. **Activity:** The social standard for being an active delegate is participating in 70% of all votes.
    2. **No self-dealing:** Voters are prohibited from approving and voting on their own proposals. Voters may not vote solely for their own candidacy in an election. In the case of approval/ranked choice elections, optimists may vote for themselves, so long as they also cast votes for the remaining elected positions.
    3. **Conflicts of Interest:** Any actual or reasonably anticipated conflicts of interest must be disclosed in writing and prominently displayed ahead of any voting (i.e. when approving proposal drafts, when running for an elected position, when making public recommendations).

    These guidelines help ensure that the Token House remains active and resistant to capture or manipulation.

    **Citizens House Voters**

    To maintain the integrity of the Citizens' House, several important rules govern participation:

    1. **No Double Representation**: If you are an admin of a Citizen project or organization, you may not also join the Citizens' House as a Superchain user.
    2. **Organization Priority**: An organization and a project under that organization can never both get votes in the Citizens' House. If both are eligible, membership defaults to the organization.
    3. **No Multiple Accounts**: It is forbidden to create multiple accounts to attempt to get multiple votes in the Citizens' House as a Superchain user. In Season 8, Citizens will be manually reviewed for possible Sybil activity by the Optimism Foundation.
    4. **Seasonal Recalculation**: The eligibility criteria for being a member of the Citizens' House will be recalculated every Season and may change—being a Citizen now doesn't guarantee future Citizens' House membership.

    These rules help ensure that the Citizens' House remains balanced, representative, and resistant to capture or manipulation.

    You can view the Code of Conduct [here](https://gov.optimism.io/t/code-of-conduct/5751).
  </Accordion>

  <Accordion title="What is Retro Funding?">
    Funding public goods is core to Optimism's values and vision for a healthy ecosystem. Retroactive Public Goods Funding (Retro Funding) is an experimental grant program to reward public goods that have created impact in the Optimism ecosystem. Learn more at atlas.optimism.io
  </Accordion>

  <Accordion title="How does identity work within the Optimism ecosystem? ">
    Identity in the Optimism Collective is built on onchain attestations, created with the [Ethereum Attestation Service ("EAS")](https://attest.sh/) — an open-source public good that is included as a predeploy in the OP Stack. Attestations represent Citizenship, project and organization identity, Retro Funding participation, and governance roles.

    * For how attestations work and why the Collective uses them, see [How identity works in the Optimism Collective](/governance/eas-attestations).
    * For EAS contract addresses, how to read and write attestations, and the full schema catalogue, see the [EAS contracts and attestation schemas reference](/governance/attestation-schemas).
  </Accordion>

  <Accordion title="Where can I find governance dashboards, trackers, and addresses?">
    Relevant governing documents, OP trackers, Foundation budget reports, Retro Funding round results, and Optimism Foundation wallet addresses are collected on the [dashboards, trackers, and addresses](/governance/resources) page, alongside the [Superchain Health Dashboard](https://docs.google.com/spreadsheets/d/1f-uIW_PzlGQ_XFAmsf9FYiUf0N9l_nePwDVrw0D5MXY/edit?gid=584971628#gid=584971628).
  </Accordion>

  <Accordion title="What is the Optimism Foundation?">
    The Optimism Foundation is a Cayman Islands foundation company. It operates to support the establishment of the Optimism Collective, the development of the Optimism ecosystem, and the technology that powers it.

    Consistent with the Collective's Working Constitution, the Foundation strives to:

    * Support the Collective with a formal legal entity, allowing the Foundation to:
      * Enter into contracts with third parties, such as service providers.
      * Administer intellectual property rights.
      * Make required governmental reports and filings.

    **How does the Foundation work?**

    The Optimism Foundation is governed by a Board of Directors and a Supervisor.

    The Board of Directors currently consists of: Abbey Titcomb, Mark Tyneway, Brian Avello, and Jing Wang. The Board's role is to manage the business and affairs of the Foundation.

    The Supervisor is the Cayman Islands firm, DS Limited. Its role is to oversee the Foundation's directors and ensure the observance of their legal obligations.

    The Foundation also employs officers, contractors and service providers to execute on its operational and administrative aims.

    **How is the Foundation held accountable?**

    As a Cayman Islands foundation company, the Foundation is legally accountable to its governing documentation, which sets up the Foundation to defer to the will of the Optimism Collective and its governance.

    There are two governance proposal types specifically targeted towards ensuring that the Foundation and its personnel are accountable to the will of the Collective:

    * **Director removal** - the ability of governance to have a member of the Foundation's Board of Directors removed from service.
    * **Rights protections** - a blocking vote, which enables governance to veto any proposed change to the Foundation's governing documents that would materially reduce the rights of OP token holders.

    More information on each of the above proposal types is contained in the [Operating Manual](https://github.com/ethereum-optimism/OPerating-manual).
  </Accordion>
</AccordionGroup>


# Protocol Upgrades
Source: https://docs.optimism.io/governance/protocol-upgrades

Learn how the OP Stack stay up to date with the latest innovations.

## How does the OP Stack stay up to date with the latest innovation?

The OP Stack is Optimism's open-source software for deploying next-generation onchain products. The software is licensed under the MIT license, meaning it can be freely used and forked by all parties. The OP Stack has a vibrant core developer community who contribute to the stack, ensuring it reflects the features and values protocol users care about.

The Superchain is an ecosystem of chains running on Optimism's OP Stack, featuring some of the world's largest enterprises. Superchain networks benefit from shared security, upgrades and services provided by Optimism. Each chain maintains peak performance with access to innovative new features developed anywhere on the stack, continually strengthening the entire Superchain ecosystem. Chains may also configure components of the OP Stack to fit their regulatory and business needs while still benefiting from shared infrastructure and innovation. Learn more about the best way to build on the OP Stack for your business [here](https://www.optimism.io/compare).

## How are new features added to the OP Stack?

OP Labs and external contributors determine the feature roadmap. Based on discussions, protocol upgrades are drafted, which go through the protocol upgrade process.

## What is the protocol upgrade process?

The protocol upgrade process is designed to make sure the OP Stack does not change against the interests of the businesses building on the platform. This is a key benefit of crypto systems compared to their centralized alternatives. Platform risk is a common risk of [Web 2 platforms](https://a16zcrypto.com/posts/article/when-is-decentralizing-on-a-blockchain-valuable/) and is a key consideration for the largest partners building on the OP Stack.

<img alt="protocol-upgrade-process" />

Protocol upgrades are drafted by OP Labs or other core contributors to the OP Stack. Before they are implemented, they are reviewed by an independent group of  developers (the Developer Advisory Board) to ensure the upgrade is well justified.

After a proposal has been reviewed by the Developer Advisory Board, it enters a 7 day veto period. This allows all impacted stakeholders, namely tokenholders, chains, apps, and end-users to override the DAB's decision if they believe an upgrade disadvantages their interests. This is how platform risk is reduced for key stakeholders of the OP Stack.

If a proposal is veto'd, it enters an appeals and discussion phase and can be resubmitted.

For full details about the protocol upgrade process, please see the [Operating Manual](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md).

Overall - contributors, tokenholders, chains, apps, and end-users all have a voice. Checks and balances exist so that no single entity (including OP Labs or the Foundation) can unilaterally dictate the future of the OP Stack.

Platform risk is reduced by distributing veto power across stakeholder groups while maintaining an efficient core developer process. This ensures upgrades happen quickly but can be vetoed if they harm key stakeholders.

## How can my chain specifically influence the feature roadmap?

Superchain members who contribute revenue back to the Collective are consulted by OP Labs and core developers about the feature roadmap to ensure their voices are heard. All development happens in the open and chains are encouraged to participate and share their perspectives within various research and development repositories.

## How does Optimism help my chain achieve decentralization?

Permissionless Fault Proof OP Chains that have their upgrade keys managed by the Optimism Security Council are classified as Stage 1 in [L2Beat's framework](https://l2beat.com/stages). This distributed group delivers the benefit of security scrutinized upgrades that are managed by Optimism.


# Dashboards, trackers, and addresses
Source: https://docs.optimism.io/governance/resources

Key governing documents, trackers, budget reports, and Optimism Foundation wallet addresses in one place.

This page collects the governing documents, dashboards, trackers, reports, and addresses referenced throughout Optimism governance.
Start with the [Superchain Health Dashboard](https://docs.google.com/spreadsheets/d/1f-uIW_PzlGQ_XFAmsf9FYiUf0N9l_nePwDVrw0D5MXY/edit?gid=584971628#gid=584971628) for an overview of the state of the Superchain.

## Governing documentation

* [Operating Manual](https://github.com/ethereum-optimism/OPerating-manual/blob/main/manual.md)
* [Working Constitution of the Optimism Collective](https://gov.optimism.io/t/working-constitution-of-the-optimism-collective/55)
* [Standard Rollup Charter](https://github.com/ethereum-optimism/OPerating-manual/blob/main/Standard%20Rollup%20Charter.md)
* [Law of Chains](https://gov.optimism.io/t/final-law-of-chains-v0-1/)
* [Decentralization Milestone Working Model](https://docs.google.com/spreadsheets/d/1IpL0oTd3AgNBu_eWdjP9EjbQfZjq-_Nd3yU1H2ke3vY/edit?gid=0#gid=0)
* [Decision Diagram Working Model](https://www.figma.com/board/iXqyKmLJeBeplKpJBHDI7G/PUBLIC%3A-Optimism-Decision-Diagram-Working-Model?node-id=0-1\&node-type=canvas\&t=QLiz1uM1DepwYyHy-0)
* [Optimist Expectations](https://gov.optimism.io/t/optimist-expectations/)

## OP trackers

* [Optimism GovFund Grants: Public Delivery Tracking](https://docs.google.com/spreadsheets/d/1Ul8iMTsOFUKUmqz6MK0zpgt8Ki8tFtoWKGlwXj-Op34/edit?gid=1179446718#gid=1179446718)
* [OP Token Unlock (Estimated)](https://docs.google.com/spreadsheets/d/1qVMhLmmch3s6XSbiBe8hgD4ntMkPIOhc1WrhsYsQc7M/edit?gid=470961921#gid=470961921)

## Foundation budget reports

* These can be found [here](https://gov.optimism.io/c/updates-and-announcements/foundation-budgets/) on the governance forum.

## Retroactive Public Goods Funding round results

* These can be found [here](https://retrofunding.optimism.io/round/results) on retrofunding.optimism.io.

## Relevant addresses

You can find the list of wallets across L1 and OP Mainnet where the Optimism Collective Revenue earned sits [here](https://docs.google.com/spreadsheets/d/1f-uIW_PzlGQ_XFAmsf9FYiUf0N9l_nePwDVrw0D5MXY/edit?gid=155717474#gid=155717474), on the right-hand side of the Collective Contribution page.

* OP Treasury Address for Foundation Allocated Budget: `0x2A82Ae142b2e62Cb7D10b55E323ACB1Cab663a26`
  * This address holds the remaining OP tokens allocated to the Foundation, which the Foundation requires governance approval to access (via annual FND budget proposals).
* OP Treasury Address for Foundation Approved Budget: `0x2501c477D0A35545a387Aa4A3EEe4292A9a8B3F0`
  * This is the Foundation's OP Treasury which is available for the Foundation to utilize as the Foundation's budget granted through the initial token allocation. Transactions from this wallet are typically internal operational movements per the Foundation's needs.
  * Additional tokens may be moved from `0x2…3a26` to `0x2…B3F0` based on governance approval of budgets.
* OP Foundation Grants Wallet: `0x19793c7824Be70ec58BB673CA42D2779d12581BE`
  * This Foundation wallet is used to make private OP grants. This is topped up from the OP Treasury Foundation Approved Budget wallet `0x2…B3F0` as needed.
* OP Foundation Locked Grants Wallet: `0xE4553b743E74dA3424Ac51f8C1E586fd43aE226F`
  * This Foundation wallet is used to hold OP for one year lockups. This is topped up from the OP Foundation Grants Wallet `0x1…81BE` as needed.

## Optimism governance calendar

* You can find a link to the Governance Calendar [here](https://calendar.google.com/calendar/embed?src=c_fnmtguh6noo6qgbni2gperid4k%40group.calendar.google.com\&ctz=Europe%2FBerlin).


# OP Stack documentation
Source: https://docs.optimism.io/index

Build apps on the OP Stack, deploy your own OP Stack chain, run a node, or learn how the protocol works.

<div>
  <div>
    <div>
      <a href="/app-developers/quickstarts/get-started">Start building</a>
      <a href="/chain-operators/quickstart">Deploy a chain</a>
    </div>
  </div>
</div>

## Find your path

<CardGroup>
  <Card title="App developers" icon="code" href="/app-developers/quickstarts/get-started">
    Build and deploy apps on OP Mainnet and other OP Stack chains. Deploy your first contract, bridge ETH to a testnet, and explore interop.
  </Card>

  <Card title="Chain operators" icon="server" href="/chain-operators/quickstart">
    Launch and operate your own OP Stack chain. Deploy the L1 contracts, spin up a sequencer, and run the full stack of services.
  </Card>

  <Card title="Node operators" icon="hard-drive" href="/node-operators/overview">
    Run a node on OP Mainnet or any OP Stack chain. Docker-based setups, source builds, monitoring, and troubleshooting.
  </Card>

  <Card title="Protocol learners & contributors" icon="book-open" href="/op-stack/introduction/op-stack">
    Understand how the OP Stack works - from transaction flow to fault proofs, interop, and more.
  </Card>
</CardGroup>

## Jump straight to a goal

* **Deploy your first smart contract** — [Deploy a contract to OP Sepolia](/app-developers/tutorials/deploy-a-contract)
* **Bridge ETH or tokens between L1 and L2** — [Bridging basics](/app-developers/guides/bridging/basics)
* **Launch an L2 rollup testnet end to end** — [Create your own L2 rollup](/chain-operators/tutorials/create-l2-rollup)
* **Run an OP Mainnet node with Docker** — [Running a node with Docker](/node-operators/tutorials/node-from-docker)
* **Understand fault proofs** — [Fault proofs explainer](/op-stack/fault-proofs/explainer)
* **Build cross-chain apps with interop** — [Interoperability explainer](/op-stack/interop/explainer)

## Ready to go further?

<Card title="Launching a chain for your organization?" icon="building" href="https://optimism.io/op-enterprise?utm_source=docs&utm_medium=docs&utm_campaign=op-enterprise">
  Compare running the stack yourself with OP Enterprise's managed and supported options. Either way, these docs are the reference for what your chain runs.
</Card>


# Consensus client configuration
Source: https://docs.optimism.io/node-operators/guides/configuration/consensus-clients

Learn how to configure consensus clients (op-node, kona-node) for your OP Stack node.

The consensus client (also called the rollup node) builds, relays, and verifies the canonical chain of blocks.
This guide covers configuration for the most popular consensus client implementations.

<Info>
  Always run your consensus client and execution client in a one-to-one configuration.
  Don't run multiple execution client instances behind one consensus client, or vice versa.
</Info>

## Consensus clients

Choose the consensus client that best fits your needs:

<Tabs>
  <Tab title="op-node">
    ## op-node configuration

    [op-node](https://github.com/ethereum-optimism/optimism/tree/develop/op-node) is the reference implementation of the OP Stack consensus client, written in Go.

    ### Minimal configuration

    The minimum required flags for running op-node:

    ```bash theme={null}
    op-node \
      --l1=https://ethereum-rpc-endpoint.example.com \
      --l1.beacon=https://ethereum-beacon-endpoint.example.com \
      --l2=http://localhost:8551 \
      --l2.jwt-secret=/path/to/jwt-secret.txt \
      --network=op-mainnet \
      --rpc.addr=0.0.0.0 \
      --rpc.port=9545
    ```

    ### Sequencer configuration

    If you're running a sequencer node, use these additional flags:

    ```bash theme={null}
    --rpc.enable-admin \
    --sequencer.enabled \
    --sequencer.l1-confs=4 \
    --p2p.sequencer.key=<your-sequencer-private-key>
    ```

    <Warning>
      Keep your sequencer private key secure and never commit it to version control.
      Use environment variables or secure key management systems in production.
    </Warning>

    ### l2.enginekind

    Controls op-node's engine-API behavior to match the connected execution client. Supported values:

    * `reth` — default; for op-reth.
    * `geth` — for op-geth (*deprecated*, see the [op-geth deprecation notice](/notices/archive/op-geth-deprecation)).

    The default is `reth`, so op-reth operators do not need to set this flag. Set `--l2.enginekind=geth` only if you are running op-geth.

    ### Complete reference

    For all available configuration options, see the [op-node configuration reference](/node-operators/reference/op-node-config).
  </Tab>

  <Tab title="kona-node">
    ## kona-node configuration

    [kona-node](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/bin/node) is an experimental Rust-based implementation of the OP Stack consensus client.

    <Warning>
      kona-node is experimental and may not be production-ready. Use with caution.
    </Warning>

    ### Basic configuration

    kona-node follows a similar configuration pattern to op-node:

    ```bash theme={null}
    kona-node \
      --l1-rpc-url=https://ethereum-rpc-endpoint.example.com \
      --l2-rpc-url=http://localhost:8551 \
      --jwt-secret=/path/to/jwt-secret.txt \
      --network=op-mainnet
    ```

    ### Additional resources

    For more details on kona-node configuration, see:

    * [kona-node component hub](/op-stack/components/kona-node)
    * [kona-node CLI reference](/node-operators/kona-node/configuration)
    * [Run a node with kona-node](/node-operators/kona-node/run/overview)
  </Tab>
</Tabs>

## JWT secret

To communicate with execution client and enable the Engine API, you'll also need to generate a JWT secret file and enable the consensus client's authenticated RPC endpoint.
To generate the JWT secret file:

```bash theme={null}
openssl rand -hex 32 > jwt-secret.txt
```


# Execution client configuration
Source: https://docs.optimism.io/node-operators/guides/configuration/execution-clients

Configure op-reth as your OP Stack execution client and migrate off end-of-support op-geth.

The execution client provides the EVM runtime and transaction processing for your OP Stack node.

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

<Info>
  Always run your execution client and consensus client in a 1:1 configuration. Don't run multiple execution clients behind one consensus client, or vice versa.
</Info>

## What a running node needs

The execution client is one of three pieces. Before configuring it, make sure you have:

1. **L1 endpoints** for the settlement layer of the chain you are syncing: an L1 execution RPC endpoint and an L1 Beacon API endpoint. Your consensus client reads batch data and blobs from them.
2. **A consensus client**, also called the rollup node: op-node or kona-node. It derives the canonical chain from L1 and drives the execution client over the Engine API. See [Consensus client configuration](/node-operators/guides/configuration/consensus-clients).
3. **An execution client**, configured below.

## Execution clients

<Tabs>
  <Tab title="op-reth">
    [op-reth](https://github.com/paradigmxyz/reth) is a Rust-based execution client and the primary supported path for OP Stack nodes going forward. The [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry) chain configurations are compiled into the binary, so registry chains work by name through `--chain` (for example `--chain unichain` or `--chain unichain-sepolia`).

    ### Install

    Two supported install paths:

    * **Docker image**, wired up end to end in [Running a Node With Docker](/node-operators/tutorials/node-from-docker).
    * **From source.** op-reth lives at `rust/op-reth/` inside the Optimism monorepo and builds with Cargo. Follow [Building and running an OP Stack node from source](/node-operators/tutorials/run-node-from-source), which pins op-node and op-reth to the same coordinated release tag.

    ### Minimal configuration

    ```bash theme={null}
    op-reth node \
      --chain optimism \
      --rollup.sequencer https://mainnet-sequencer.optimism.io \
      --http \
      --ws \
      --authrpc.port 9551 \
      --authrpc.jwtsecret /path/to/jwt.hex
    ```

    ### OP Stack specific flags

    op-reth's `Rollup` flag group holds the behavior that exists only on OP Stack chains. Two matter to most operators:

    * `--rollup.sequencer <uri>` (shown above) is the sequencer endpoint that transactions submitted to this node are forwarded to, since the sequencer is what builds blocks. Aliases: `--rollup.sequencer-http`, `--rollup.sequencer-ws`.
    * `--rollup.disable-tx-pool-gossip` stops the node from gossiping its transaction pool to peers. Omit it on a personal node; set it on a replica you operate as a provider.

    The rest of the group covers the interop filter, subblocks, and historical RPC. For the full list with the binary's own descriptions, see the [`op-reth node` flag listing](/node-operators/op-reth/cli/op-reth/node), and [Understanding the op-reth CLI](/node-operators/op-reth/cli/overview) for how the flag groups fit together.

    ### Subblocks

    To serve pre-confirmed state from a chain that streams [Subblocks](/op-stack/features/subblocks), point op-reth at the chain's WebSocket stream:

    ```bash theme={null}
    op-reth node \
      --chain optimism \
      --rollup.sequencer https://mainnet-sequencer.optimism.io \
      --flashblocks-url wss://op-mainnet-fb-ws-pub.optimism.io/ws \
      --http \
      --ws \
      --authrpc.port 9551 \
      --authrpc.jwtsecret /path/to/jwt.hex
    ```

    The node then answers requests carrying the `pending` block tag from subblock state, executing each subblock's transactions against its own view of the chain. It does not need the stream's `state_root`, which subblocks leave zeroed. The flag keeps its `flashblocks` spelling; `--websocket-url` is an accepted alias.

    `--flashblocks-url` on its own is what an ordinary node wants. Leave `--flashblock-consensus` unset: it drives the chain forward from the stream by submitting completed sequences through `engine_newPayload`, which is a specialized topology, not an addition to a normal node following op-node. Enabling it also turns on local state-root computation for the last subblock in each sequence, which an ordinary node has no use for.

    ### Historical proofs

    Permissionless chains need \~28 days of historical state for withdrawal proving. Follow the [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs) tutorial to set up the `--proofs-history` (v2) store on op-reth v2.2.3 or later.

    ### Pruning

    op-reth defaults to an archive node. To reclaim disk, prune the state and receipt segments and keep block bodies. Body pruning (`--minimal` or `--prune.bodies.distance`) is unsupported and advised against. See [Pruning op-reth](/node-operators/guides/management/archive-node#pruning-op-reth).

    ### Complete reference

    * [op-reth configuration reference](/node-operators/reference/op-reth-config)
    * [op-reth historical proof configuration](/node-operators/reference/op-reth-historical-proof-config)
    * [reth.rs documentation](https://reth.rs/run/opstack)
  </Tab>

  <Tab title="Nethermind">
    [Nethermind](https://github.com/NethermindEth/nethermind) is a .NET-based alternative execution client.

    ### Minimal configuration

    ```bash theme={null}
    nethermind \
      -c op-mainnet \
      --data-dir path/to/data/dir \
      --jsonrpc-jwtsecretfile path/to/jwt.hex
    ```

    ### Additional resources

    * [Nethermind OP Stack documentation](https://docs.nethermind.io/get-started/running-node/l2-networks)
    * [Nethermind configuration reference](https://docs.nethermind.io/fundamentals/configuration)
  </Tab>
</Tabs>

## JWT secret

The execution client and consensus client communicate over the Engine API using a shared JWT secret:

```bash theme={null}
openssl rand -hex 32 > jwt-secret.txt
```

This file must be identical for both your execution client and your consensus client.

## op-geth (legacy, end of support 2026-05-31)

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

<Accordion title="op-geth configuration (legacy)">
  [op-geth](https://github.com/ethereum-optimism/op-geth) is a minimal fork of go-ethereum optimized for the OP Stack.

  <Info>
    Although the Docker image is called `op-geth`, the actual binary is still named `geth` to minimize differences from go-ethereum. See the [op-geth diff viewer](https://op-geth.optimism.io/?utm_source=op-docs\&utm_medium=docs) for details.
  </Info>

  ### Minimal configuration

  ```bash theme={null}
  geth \
    --datadir=/data/optimism \
    --http \
    --http.addr=0.0.0.0 \
    --http.port=8545 \
    --http.api=eth,net,web3 \
    --authrpc.jwtsecret=/path/to/jwt-secret.txt \
    --op-network=op-mainnet \
    --rollup.sequencerhttp=https://mainnet-sequencer.optimism.io/ \
    --rollup.disabletxpoolgossip
  ```

  Defaults: snap sync mode, no WebSocket server, no metrics.

  ### OP Stack specific flags

  * `--rollup.sequencerhttp`: HTTP endpoint of the sequencer for transaction submission
  * `--rollup.disabletxpoolgossip`: Disables transaction pool gossip (for replica nodes)
  * `--rollup.historicalrpc`: Enables historical RPC endpoint for upgraded networks (OP Mainnet pre-bedrock archive nodes)

  ### Complete reference

  The op-geth configuration reference has been retired; see the [op-reth configuration reference](/node-operators/reference/op-reth-config) for the equivalent op-reth flags.
</Accordion>


# Legacy Geth configuration
Source: https://docs.optimism.io/node-operators/guides/configuration/legacy-geth

Learn how to configure Legacy Geth for serving historical execution traces on upgraded OP Stack networks.

Legacy Geth (`l2geth`) is the old pre-Bedrock OVM client running against a preconfigured data directory.
It is required only for upgraded networks like OP Mainnet to serve execution traces and chain data from before the Bedrock upgrade.
If you're running a node that had a chain genesis after the Bedrock upgrade, you do not need Legacy Geth.

<Info>
  Legacy Geth (`l2geth`) is the pre-Bedrock OVM client and is unrelated to op-geth's deprecation. l2geth is required on OP Mainnet archive nodes regardless of which post-Bedrock execution client you run (op-reth or op-geth).
</Info>

<Info>
  If you need state proofs for post-Bedrock blocks (for example, for withdrawal proving), see the [historical proofs config](/node-operators/reference/op-reth-historical-proof-config) — that's a different feature.
</Info>

## Do you need Legacy Geth?

op-reth routes RPC requests that target pre-Bedrock blocks to Legacy Geth.
This includes *historical execution* — methods that need to execute pre-Bedrock transactions, such as `eth_call` and the `debug_trace*` methods — as well as reads of pre-Bedrock block and transaction data, such as `eth_getBlockByNumber` and `eth_getTransactionReceipt`.
op-reth serves everything post-Bedrock directly.
If you do not need any RPC access to pre-Bedrock blocks, then you do not need to run Legacy Geth at all.

For the exact list of RPC methods routed to Legacy Geth, see the [Legacy Geth configuration reference](/node-operators/reference/legacy-geth-config#rpc-methods-routed-to-legacy-geth).

## Setup

### 1. Download the preconfigured data directory

Download and extract the Legacy Geth data directory, which is available at [datadirs.optimism.io](https://datadirs.optimism.io).

```bash theme={null}
# Download the data directory
curl -o legacy-geth-datadir.tar -sL <URL-to-legacy-datadir>

# Extract it
tar -xvf legacy-geth-datadir.tar -C /data/legacy-geth
```

### 2. Configure Legacy Geth

Run Legacy Geth with the minimum required configuration:

```bash theme={null}
USING_OVM=true \
  ETH1_SYNC_SERVICE_ENABLE=false \
  RPC_API=eth,rollup,net,web3,debug \
  RPC_ADDR=0.0.0.0 \
  RPC_CORS_DOMAIN=* \
  RPC_ENABLE=true \
  RPC_PORT=8545 \
  RPC_VHOSTS=* \
  geth --datadir /data/legacy-geth
```

<Warning>
  It is imperative that you specify the `USING_OVM=true` environment variable.
  Failing to specify this will cause `l2geth` to return invalid execution traces or panic at startup.
</Warning>

The full set of environment variables Legacy Geth accepts, with defaults, is catalogued in the [Legacy Geth configuration reference](/node-operators/reference/legacy-geth-config#environment-variables).

### 3. Configure your execution client to route to Legacy Geth

Point your execution client at Legacy Geth with the `--rollup.historicalrpc` flag; op-reth and op-geth accept the same flag (see the [routing-flag reference](/node-operators/reference/legacy-geth-config#execution-client-routing-flag)).

<Tabs>
  <Tab title="op-reth">
    ```bash theme={null}
    op-reth node \
      --datadir=/data/optimism \
      --rollup.historicalrpc=http://localhost:8545 \
      # ... other flags
    ```
  </Tab>

  <Tab title="op-geth">
    <Warning>
      **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
    </Warning>

    ```bash theme={null}
    geth \
      --datadir=/data/optimism \
      --rollup.historicalrpc=http://localhost:8545 \
      # ... other flags
    ```
  </Tab>
</Tabs>

## Troubleshooting

<Warning>
  `l2geth` is based on an old version of geth where trace functionality is unstable.
  It is no longer maintained and will not be updated.
</Warning>

### Legacy Geth won't start

**Problem**: `l2geth` panics or returns errors on startup

**Solution**: Ensure `USING_OVM=true` is set in your environment variables

### Invalid execution traces

**Problem**: Legacy Geth returns invalid or incorrect trace data

**Solution**: Verify that `USING_OVM=true` is set and the data directory is complete and uncorrupted

### Execution client not routing to Legacy Geth

**Problem**: Historical execution requests are not being routed to Legacy Geth

**Solution**: Check that `--rollup.historicalrpc` is set on your execution client (op-reth or op-geth) with the correct URL to Legacy Geth


# Supernode configuration
Source: https://docs.optimism.io/node-operators/guides/configuration/supernode

Learn how to configure op-supernode to run every chain in an interop dependency set in one process.

<Info>
  op-supernode is in active development.
  This page tracks the [op-supernode/v0.2.2-rc.8](https://github.com/ethereum-optimism/optimism/releases/tag/op-supernode%2Fv0.2.2-rc.8) release candidate and the recommendations may evolve before the stable release.
  For background on what op-supernode is and why it exists, see the [supernode explainer](/op-stack/interop/supernode).
</Info>

This guide covers the recommended settings and a starter configuration for op-supernode.
op-supernode runs every chain in an interop dependency set together as virtual nodes inside one process, sharing the L1 client and beacon-chain plumbing across them.
For the end-to-end procedure to stand up a supernode from scratch (build, engine-API wiring, start, verify), see the [supernode setup guide](/node-operators/guides/configuration/supernode-setup).
For the complete per-flag catalogue, see the [op-supernode configuration reference](/node-operators/reference/op-supernode-config).

## Recommendations

### Share the JWT secret across virtual nodes with `--vn.all.l2.jwt-secret`

<Info>
  Each chain's virtual node needs the JWT secret to authenticate with its execution client over the Engine API.
  When every chain in the dependency set uses the same secret, set it once at the supernode level and let every virtual node inherit it.
</Info>

To share a single JWT secret across every virtual node, set `--vn.all.l2.jwt-secret=<path>` (or `OP_SUPERNODE_VN_ALL_L2_ENGINE_AUTH`) at the supernode level.
This avoids repeating the per-chain `--vn.<chainID>.l2.jwt-secret` line for every chain in `--chains`.
Reserve the per-chain form for the case where one chain's execution client needs a different secret; the [configuration reference](/node-operators/reference/op-supernode-config) documents both forms.

### Configure a beacon archiver fallback with `--l1.beacon-fallbacks`

<Warning>
  Ethereum beacon nodes prune blob sidecars after roughly 18 days.
  Without an archive fallback configured, a supernode that has been offline past the prune window cannot fetch the blobs it needs to derive missed L1 blocks, and chain containers will stall at the gap.
</Warning>

Configure `--l1.beacon-fallbacks` (or `OP_SUPERNODE_L1_BEACON_FALLBACKS`) with one or more beacon-API-compatible archive endpoints.
Set them up from the start — once a primary beacon prunes a blob the supernode needs, only an archiver can recover it.
The shared beacon client uses the fallbacks transparently when the primary beacon node returns 404 for an expired blob.

For options on what to point `--l1.beacon-fallbacks` at — running your own non-pruning beacon, running `blob-archiver`, or using a third-party service — see the [blob archiver guide](/node-operators/guides/management/blobs#configure-a-blob-archiver).

### Configure EL retention for supernode backfill

<Info>
  The supernode reads historical block and receipt data from each chain's execution client to backfill initiating-message logs after restarts or extended downtime.
  ELs that aggressively prune receipts will break the backfill path.
</Info>

Configure each EL to retain at least 7 days of block and receipt history.
A full archive is not required — see the [op-reth configuration reference](/node-operators/reference/op-reth-config) for the granular `--prune.*` flags that let you keep block and receipt history without enabling transaction indexing or world-state history.

If you also run op-challenger for permissionless fault proofs, the same ELs additionally need historical proofs enabled — see [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs).

### Pair op-supernode with a Light CL fleet

For operators running more than a handful of nodes, the deployable pattern is to concentrate the expensive multi-chain derivation work on supernodes and run the rest of the fleet as op-node or kona-node instances in Light CL mode.
Each supernode (or HA pool of supernodes) acts as the safe source for a fleet of Light CLs.
The fleet points at the supernode's `optimism_syncStatus` RPC over the `--l2.follow.source` flag and inherits its safe and finalized view, while keeping its own unsafe-head progression over P2P.
Larger operators often run several such supernode-plus-fleet groups for blast-radius isolation, regional placement, or staged rollouts.

See the [specialized op-node topology notice](/notices/specialized-node-topology) for the fleet side of this pattern, and the [supernode explainer](/op-stack/interop/supernode#op-supernode-and-light-cl) for the architecture overview.

Set `--disable-p2p=true` on the supernode when the fleet handles unsafe-head P2P gossip on its own.
Leave P2P enabled (the default) when the supernode is the only node in the topology.

### Run an HA pool of supernodes behind a consensus-aware proxyd

For production reliability, OP Labs recommends running an **HA pool of at least three op-supernode instances** and fronting them with a [consensus-aware `proxyd`](/chain-operators/tools/proxyd#consensus-awareness) configured with the `consensus_aware_consensus_layer` routing strategy.
Point the Light CL fleet's `--l2.follow.source` at the proxyd endpoint rather than at a single supernode.
This hides individual supernode failures or reorgs from the Light CL fleet and lets the supernode tier roll between releases without downtime.

An individual supernode going down inside the HA pool is masked by `proxyd` — Light CLs continue following the surviving instances.
If the entire supernode tier becomes unreachable, Light CLs keep advancing the unsafe chain over P2P gossip and resume safe-head tracking automatically once the tier is restored.

A single op-supernode is acceptable for evaluation, but treat it as a single point of failure for safe-head progression on every chain it hosts.

## Example configuration

This is a minimum viable configuration for an op-supernode acting as a verifier across OP Sepolia and Unichain Sepolia.
The example uses environment variables; pass the equivalent `--flag` arguments instead if that fits your deployment better.
Fill in the placeholders before starting the binary.

<Info>
  The example below assumes a two-chain dependency set of OP Sepolia (chain ID `11155420`) and Unichain Sepolia (chain ID `1301`).
  For a different dependency set, replace the chain IDs in `OP_SUPERNODE_CHAINS` and add or remove the matching `OP_SUPERNODE_VN_<CHAINID>_NETWORK` and `OP_SUPERNODE_VN_<CHAINID>_L2_ENGINE_RPC` pairs for each chain.
</Info>

```yaml theme={null}
# Dependency set and storage
OP_SUPERNODE_CHAINS: "11155420,1301"          # OP Sepolia + Unichain Sepolia
OP_SUPERNODE_DATA_DIR: /var/lib/op-supernode  # default is ./datadir

# Shared L1 access
OP_SUPERNODE_L1_ETH_RPC: <your-l1-eth-rpc>
OP_SUPERNODE_L1_BEACON: <your-l1-beacon-rpc>
OP_SUPERNODE_L1_BEACON_FALLBACKS: <your-l1-beacon-archiver-rpc>

# Shared JWT secret for every virtual node's engine connection
OP_SUPERNODE_VN_ALL_L2_ENGINE_AUTH: /etc/op/jwt-secret.txt

# Per-chain: chain identity, engine RPC, and engine kind (reth when the chain's EL is op-reth)
OP_SUPERNODE_VN_11155420_NETWORK: op-sepolia
OP_SUPERNODE_VN_11155420_L2_ENGINE_RPC: <op-sepolia-engine-rpc>
OP_SUPERNODE_VN_11155420_L2_ENGINE_KIND: reth
OP_SUPERNODE_VN_1301_NETWORK: unichain-sepolia
OP_SUPERNODE_VN_1301_L2_ENGINE_RPC: <unichain-sepolia-engine-rpc>
OP_SUPERNODE_VN_1301_L2_ENGINE_KIND: reth

# Top-level JSON-RPC server (per-chain namespaces under /<chainID>/)
OP_SUPERNODE_RPC_ADDR: 0.0.0.0
OP_SUPERNODE_RPC_PORT: "8545"

# Observability
OP_SUPERNODE_LOG_LEVEL: info
OP_SUPERNODE_METRICS_ENABLED: "true"
OP_SUPERNODE_METRICS_ADDR: 0.0.0.0
OP_SUPERNODE_METRICS_PORT: "7300"
```

For chains that are not in op-node's built-in network registry, replace `--vn.<chainID>.network` with `--vn.<chainID>.rollup.config=<path-to-rollup-config.json>`.

Every flag in the example — and everything else the binary accepts, including P2P, interop verification, JSON-RPC, logging, and metrics options — is catalogued with syntax, examples, and environment-variable names in the [op-supernode configuration reference](/node-operators/reference/op-supernode-config).

## Where to go next

* Follow the [supernode setup guide](/node-operators/guides/configuration/supernode-setup) to stand up a supernode from scratch.
* Read the [op-supernode configuration reference](/node-operators/reference/op-supernode-config) for the complete flag and environment-variable catalogue.
* Read the [interop prep notice](/notices/interop-prep) for the node-operator action checklist for the OP Sepolia and Unichain Sepolia activation.
* Read the [supernode explainer](/op-stack/interop/supernode) for what op-supernode is and why it exists.
* Read the [specialized op-node topology notice](/notices/specialized-node-topology) for the operator-facing pattern of running Light CL fleets that follow a supernode safe source.
* Read the [interop explainer](/op-stack/interop/explainer) for how cross-chain messaging works at the protocol level.
* Read the [op-node configuration reference](/node-operators/reference/op-node-config) for the full set of flags available under the `--vn.*` namespace.
* See the [op-supernode source](https://github.com/ethereum-optimism/optimism/tree/develop/op-supernode) in the monorepo for implementation detail.


# Supernode setup
Source: https://docs.optimism.io/node-operators/guides/configuration/supernode-setup

Stand up op-supernode end to end - build the binary, wire each chain's engine API, start the process, and verify every chain is syncing.

<Info>
  op-supernode is in active development.
  This page tracks the [op-supernode/v0.2.2-rc.8](https://github.com/ethereum-optimism/optimism/releases/tag/op-supernode%2Fv0.2.2-rc.8) release candidate and the procedure may evolve before the stable release.
  For background on what op-supernode is and why it exists, see the [supernode explainer](/op-stack/interop/supernode).
</Info>

This guide stands up a single op-supernode process from scratch: build the binary, wire each chain's execution client over the engine API, start the process, and verify that every chain in the dependency set is syncing.
At the end, one op-supernode acts as the consensus layer for every chain it hosts, replacing a separate op-node per chain.

This page covers getting to a running, verified process.
For recommended production settings (beacon archiver fallbacks, execution-client retention, Light CL fleets, and HA pools), continue with the [supernode configuration guide](/node-operators/guides/configuration/supernode).
Every flag used below is catalogued in the [op-supernode configuration reference](/node-operators/reference/op-supernode-config).

## Before you start

You need:

* **One execution client per chain.** Each chain in the dependency set needs its own execution client with the engine API (authrpc) enabled; one execution client cannot back two chains. See the [execution client configuration guide](/node-operators/guides/configuration/execution-clients) for client options, and the [run a node from source tutorial](/node-operators/tutorials/run-node-from-source) for a full execution-client walkthrough.
* **L1 endpoints.** An L1 JSON-RPC endpoint with the `eth` namespace enabled and an L1 beacon-node HTTP endpoint, shared by every chain. A beacon archiver fallback is strongly recommended; see [configuring a blob archiver](/node-operators/guides/management/blobs#configuring-a-blob-archiver).
* **The chain IDs of every chain the supernode will host.** For chains in op-node's built-in network registry (for example `op-sepolia`, `unichain-sepolia`), the network name is enough. For any other chain, you need a rollup configuration JSON file per chain.

## Build op-supernode

The binary is built from the Optimism Monorepo.
The build environment is managed through [mise](https://mise.jdx.dev/), which installs the toolchains needed to build the monorepo; see [`mise.toml`](https://github.com/ethereum-optimism/optimism/blob/develop/mise.toml) at the monorepo root.

<Steps>
  <Step title="Clone the monorepo and check out the release tag">
    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism.git
    cd optimism
    git checkout op-supernode/v0.2.2-rc.8
    ```
  </Step>

  <Step title="Build the binary">
    ```bash theme={null}
    cd op-supernode
    just op-supernode
    ```

    The binary is written to `op-supernode/bin/op-supernode`.
  </Step>

  <Step title="Confirm the build">
    ```bash theme={null}
    ./bin/op-supernode --version
    ```

    <Info>
      The flag set is generated dynamically from the `--chains` list, so to inspect the full help output for your chains, run `./bin/op-supernode --chains=<chainIDs> --help`.
    </Info>
  </Step>
</Steps>

## Create the JWT secret and wire the engine API

Each chain's virtual node authenticates to that chain's execution client over the engine API using a shared JWT secret.

<Steps>
  <Step title="Generate the secret">
    ```bash theme={null}
    openssl rand -hex 32 > jwt-secret.txt
    ```
  </Step>

  <Step title="Start each execution client with the secret">
    Start every chain's execution client with its authrpc listening and pointed at the same secret file; for op-reth, `--authrpc.jwtsecret=<path>`.
    Start the execution clients before the supernode; they simply won't receive blocks until the supernode connects.
  </Step>

  <Step title="Note the engine-API endpoint of each execution client">
    You will pass each chain's engine-API endpoint (port `8551` by convention) to the supernode as `--vn.<chainID>.l2` in the next section.
    The supernode side of the secret is a single `--vn.all.l2.jwt-secret=<path>` flag when every execution client shares one secret; use the per-chain `--vn.<chainID>.l2.jwt-secret` form only when a client needs its own.
  </Step>
</Steps>

## Start op-supernode

Start the supernode with the list of chain IDs, the shared L1 endpoints, and each chain's network identity and engine-API endpoint.
The example below hosts OP Sepolia (chain ID `11155420`) and Unichain Sepolia (chain ID `1301`) with op-reth execution clients.
Fill in the placeholders, and add or remove the per-chain `--vn.<chainID>.*` groups to match your dependency set.

```bash theme={null}
./bin/op-supernode \
  --chains=11155420,1301 \
  --data-dir=/var/lib/op-supernode \
  --l1=<your-l1-eth-rpc> \
  --l1.beacon=<your-l1-beacon-rpc> \
  --l1.beacon-fallbacks=<your-l1-beacon-archiver-rpc> \
  --vn.all.l2.jwt-secret=./jwt-secret.txt \
  --vn.11155420.network=op-sepolia \
  --vn.11155420.l2=http://op-sepolia-el:8551 \
  --vn.11155420.l2.enginekind=reth \
  --vn.1301.network=unichain-sepolia \
  --vn.1301.l2=http://unichain-sepolia-el:8551 \
  --vn.1301.l2.enginekind=reth \
  --metrics.enabled=true
```

A few notes on the flags:

* For a chain that is not in op-node's built-in network registry, replace `--vn.<chainID>.network` with `--vn.<chainID>.rollup.config=<path-to-rollup-config.json>`.
* The `--vn.<chainID>.l2.enginekind=reth` lines tell the supernode the execution client is op-reth; the default is `geth`, so drop them if you run op-geth.
* P2P is enabled by default, with each virtual node's listen port chosen dynamically to avoid collisions. Set `--disable-p2p=true` when other nodes in your topology handle unsafe-head gossip; see [pair op-supernode with a Light CL fleet](/node-operators/guides/configuration/supernode#pair-op-supernode-with-a-light-cl-fleet).
* The JSON-RPC server listens on `0.0.0.0:8545` by default (`--rpc.addr` / `--rpc.port`). Like the op-node RPC, it is not meant to be exposed to the public internet.
* Every flag has an environment-variable equivalent (`OP_SUPERNODE_*`). The [configuration guide's example configuration](/node-operators/guides/configuration/supernode#example-configuration) shows the same kind of setup in environment-variable form, and the [configuration reference](/node-operators/reference/op-supernode-config) lists the exact name for every flag.

## Verify the supernode is working

<Steps>
  <Step title="Watch the logs">
    The heartbeat activity logs a `heartbeat` message every 10 seconds as a basic sign that the process is alive and its activities are running.
  </Step>

  <Step title="Check liveness over RPC">
    The `heartbeat_check` method at the RPC root returns a random hex value as a sign of life:

    ```bash theme={null}
    curl -X POST -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","method":"heartbeat_check","params":[],"id":1}' \
      http://localhost:8545/
    ```
  </Step>

  <Step title="Check aggregate sync status">
    The `supernode_syncStatus` method at the RPC root returns the per-chain op-node sync status for every hosted chain, plus dependency-set-wide fields: the chain IDs, the highest fully derived and verified L1 block, and the safe, local-safe, and finalized L2 timestamps across the set.

    ```bash theme={null}
    curl -X POST -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","method":"supernode_syncStatus","params":[],"id":1}' \
      http://localhost:8545/
    ```

    Confirm that every chain ID you configured appears in the response and that the reported heads advance between calls.
  </Step>

  <Step title="Check an individual chain">
    Each chain's full op-node RPC surface is mounted under a `/<chainID>/` path prefix on the same server, so any [op-node JSON-RPC method](/node-operators/reference/op-node-json-rpc#optimism_syncstatus) works per chain:

    ```bash theme={null}
    curl -X POST -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
      http://localhost:8545/11155420/
    ```

    A chain's endpoint becomes available once its chain container has started; requests to a chain ID that is not configured return `404 Not Found`.
  </Step>

  <Step title="Check metrics">
    With `--metrics.enabled=true`, every chain's metrics are fanned into a single Prometheus endpoint at `/metrics` on the metrics port (default `7300`), labeled per chain:

    ```bash theme={null}
    curl http://localhost:7300/metrics
    ```
  </Step>
</Steps>

## Next steps

* Harden the deployment with the [supernode configuration guide](/node-operators/guides/configuration/supernode): beacon archiver fallbacks, execution-client retention for backfill, Light CL fleets, and HA pools behind a consensus-aware proxyd.
* Look up any flag in the [op-supernode configuration reference](/node-operators/reference/op-supernode-config).
* Read the [supernode explainer](/op-stack/interop/supernode) for what op-supernode is and why it exists.
* Read the [interop prep notice](/notices/interop-prep) for the node-operator action checklist for the OP Sepolia and Unichain Sepolia activation.


# Running an archive node
Source: https://docs.optimism.io/node-operators/guides/management/archive-node

Learn how to configure and run an archive node.

This guide shows you how to configure your node to run as an archive node. Archive nodes store the complete history of the blockchain, including all historical states.

## Overview

Archive nodes maintain the entire state history of the blockchain, allowing you to query any historical state at any block height. This is useful for:

* Block explorers that need to provide historical data
* Analytics and data analysis applications
* Services that need to query historical state
* Debugging and auditing purposes

Archive nodes use execution-layer sync but configure the execution client to retain all historical state data instead of pruning it.

<Info>
  Historical proofs are a lighter-weight alternative to a full archive node when you only need cryptographic state proofs (`eth_getProof`) at historical blocks — the typical case is withdrawal proving and fault proof workloads. If you need historical execution (`eth_call`, `debug_trace*`) or arbitrary historical state queries, you still need a full archive node. See the [historical proofs config](/node-operators/reference/op-reth-historical-proof-config).
</Info>

## Requirements

* **OP Mainnet**: Requires the [bedrock datadir](/node-operators/guides/management/snapshots)
* **Other OP Stack networks**: No datadir required
* **Storage**: Archive nodes require significantly more disk space than regular nodes (several terabytes for OP Mainnet)
* **Sync time**: Archive sync with execution-layer mode is faster than full block-by-block execution

## Configuration

Each section below shows the full set of flags needed on both `op-node` and your chosen execution client to run as an archive node. The `op-node` flag `--syncmode=execution-layer` is required in all cases and is not the default — it must be explicitly configured.

### op-reth

op-reth retains complete state when run without pruning flags, so the standard op-node + op-reth configuration already produces an archive node.

Set on `op-node`:

```shell theme={null}
--syncmode=execution-layer
```

Do not pass any `--prune.*` flags to op-reth for a complete archive node. If you don't need complete history and want to reclaim disk, see [Pruning op-reth](#pruning-op-reth) below.

### Nethermind

Set on `op-node`:

```shell theme={null}
--syncmode=execution-layer
```

Enable archive mode on Nethermind using the archive network configuration:

```shell theme={null}
--config op-mainnet_archive
```

<Info>
  Replace `op-mainnet_archive` with the appropriate archive configuration for your network (e.g., `op-sepolia_archive` for OP Sepolia).
</Info>

### op-geth

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

Set on `op-node`:

```shell theme={null}
--syncmode=execution-layer
```

Set on `op-geth`:

```shell theme={null}
--syncmode=full
--gcmode=archive
```

<Info>
  Both flags are not the default settings and must be explicitly configured. The `--syncmode=full` flag ensures every block is executed, and `--gcmode=archive` disables state pruning.
</Info>

## Pruning op-reth

If you don't need a complete archive node, you can prune op-reth to reclaim disk. The recommended approach prunes state and receipts while keeping every block body.

### Recommended: prune state and receipts, keep block bodies

Prune the state and receipt segments and leave block bodies fully intact. Set the same depth on each:

```shell theme={null}
--prune.minimum-distance=<depth>
--prune.receipts.distance=<depth>
--prune.account-history.distance=<depth>
--prune.storage-history.distance=<depth>
```

Recommended `<depth>` (in blocks), matching production:

* **`22000`** for sequencer-side nodes — covers the 12h sequencing window (≈ 21,600 blocks at a 2s block time).
* **`1296000`** (\~30 days at 2s) for nodes that need more history.

### Pruning block bodies (unsupported)

op-node's safe derivation reads the L1-info deposit transaction — the first transaction of every block — from the block body at the head placed [`--syncmode.offset-el-safe`](/node-operators/reference/op-node-config#syncmode-offset-el-safe) behind the tip, and possibly further if restoring a safedb. If that body has been pruned, EL sync fails with `l2 block is missing L1 info deposit tx`.

Body pruning is therefore **not supported, and we advise against it** — you run it at your own risk, with no guarantees. It can be made to work if you know what you're doing, subject to one hard requirement: the retained body window must always cover the `--syncmode.offset-el-safe` range. Concretely, set [`--prune.bodies.distance`](/node-operators/op-reth/cli/op-reth/node) (in blocks) comfortably **greater than** the offset converted to blocks (the default `12h` ≈ 21,600 at a 2s block time), with margin for the block-time and offset you actually run. And if you restore a safedb, you also have to take the maximum distance to its head into account.

Do not use `--minimal`: it prunes bodies to a fixed 10,064-block window, which is smaller than the default offset and cannot be widened independently.

<Warning>
  Body pruning is unsupported. If you enable it anyway, `--prune.bodies.distance` must always exceed `--syncmode.offset-el-safe` (in blocks), and additionally the distance to a restoring safedb's head, or execution-layer sync fails with `l2 block is missing L1 info deposit tx`. Prefer pruning only the state and receipt segments above.
</Warning>

## How archive sync works

With execution-layer sync mode enabled:

1. **Initial sync**: The node downloads block headers and data through the P2P network
2. **Block execution**: The node executes every block in the chain to build the complete state history
3. **State retention**: Unlike regular nodes, archive nodes never prune historical state data
4. **Faster than legacy**: While still executing all blocks, this is faster than the legacy consensus-layer sync because block data is retrieved via P2P instead of being derived from L1

## Storage considerations

Archive nodes require substantial storage:

* **OP Mainnet**: Several terabytes and growing
* **Other networks**: Varies by network age and activity
* **Growth rate**: Storage requirements increase continuously as new blocks are added
* **Recommendation**: Use fast SSD storage for optimal performance

## Next steps

* See the [sync modes reference](/node-operators/reference/consensus-layer-sync) for non-archive node sync configuration
* See the [Consensus Client Configuration](/node-operators/guides/configuration/consensus-clients) and [Execution Client Configuration](/node-operators/guides/configuration/execution-clients) guides for additional explanation or customization
* See the [Snapshots guide](/node-operators/guides/management/snapshots) for information about downloading the bedrock datadir
* If you experience difficulty at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions)


# Fetch blob data for your node
Source: https://docs.optimism.io/node-operators/guides/management/blobs

Configure op-node to fetch L1 batcher blob data, including blobs older than the beacon retention window.

OP Stack rollups post batch data to L1 as [EIP-4844 blobs](https://eips.ethereum.org/EIPS/eip-4844). To retrieve this data, `op-node` requires access to an L1 beacon endpoint. Run your own beacon node ([Lighthouse](https://lighthouse-book.sigmaprime.io/run_a_node.html), Lodestar, Nimbus, Prysm, or Teku) or use a third-party service like [QuickNode](https://www.quicknode.com/docs/ethereum/eth-v1-beacon-genesis).

Pass the beacon endpoint to op-node:

```shell theme={null}
--l1.beacon value                                                      ($OP_NODE_L1_BEACON)
          HTTP endpoint Address of L1 Beacon-node.
```

## Configuring a blob archiver

Standard beacon nodes prune blobs after 18 days. If your node is synced within the last 18 days and stays online, the default beacon endpoint is sufficient. You need a blob archiver if either of these is true:

* You're syncing a new node from a snapshot or genesis older than 18 days
* Your node has been offline for more than 18 days

Pass one or more fallback endpoints to op-node:

```shell theme={null}
--l1.beacon-fallbacks value                                            ($OP_NODE_L1_BEACON_FALLBACKS)
          Addresses of L1 Beacon-API compatible HTTP fallback endpoints. Used to fetch blob sidecars
          not available at the l1.beacon (e.g. expired blobs).
```

<Info>
  `--l1.beacon-fallbacks` was previously called `--l1.beacon-archiver`. The old name still works as an alias, and so does the legacy env var `$OP_NODE_L1_BEACON_ARCHIVER`.
</Info>

Choose one of these options for the archiver endpoint:

* **Option 1 — Run a beacon node with blob pruning disabled.** For Lighthouse, set `--prune-blobs=false` and point `--l1.beacon-fallbacks` at it.
* **Option 2 — Run a dedicated blob archiver service** such as [base-org/blob-archiver](https://github.com/base-org/blob-archiver), and point `--l1.beacon-fallbacks` at its API endpoint. Lighter weight than running a full no-prune beacon node.
* **Option 3 — Use a third-party blob-archiver service.** Useful if you don't want to operate any beacon infrastructure.


# Restore a Node From a Snapshot
Source: https://docs.optimism.io/node-operators/guides/management/restore-from-snapshot

Download, verify, and extract a snapshot into your node's data directory to skip the initial sync.

This guide walks you through bootstrapping an OP Stack execution client from a pre-synced snapshot: download it, verify the checksum, extract it into your data directory, and start the node from the snapshot's tip instead of replaying the chain from genesis.

For **what** snapshots are available for OP Mainnet and their download links, see the [Snapshots reference page](/op-mainnet/network-information/snapshots).

## When to use a snapshot

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

This guide assumes an `op-reth` node.

You don't always need one. With [execution-layer sync](/node-operators/reference/consensus-layer-sync) — `--syncmode=execution-layer` and `--l2.enginekind=reth` on `op-node` — `op-reth` retrieves blocks over the P2P network instead of deriving each one, which makes the initial sync much faster and, on most OP Stack chains, needs no snapshot at all. [Nethermind](https://docs.nethermind.io/get-started/running-node/l2-networks#op-stack) downloads what it needs automatically.

Use a snapshot when:

* You are running an **archive node**, or otherwise need to trace the entire chain.
* You simply want to skip the initial sync entirely: a mature chain's data directory can run to hundreds of gigabytes (OP Mainnet is roughly 700 GB for a full node), and even execution-layer sync takes days from scratch.

<Note>
  On **OP Mainnet**, syncing `op-reth` on a fresh data directory is another reason to use a snapshot: it satisfies the [pre-Bedrock state import requirement](/node-operators/op-reth/run/faq/sync-op-mainnet) in one step, even when execution-layer sync is enabled.
</Note>

## Before you begin

* **Disk space**: you temporarily need room for both the compressed archive and the extracted data directory, so plan for roughly twice the snapshot size during the restore, on fast (NVMe-class) storage.
* **Tools**: `curl` (or [aria2](https://aria2.github.io/), which can significantly speed up large downloads), `zstd`, and `tar`.
* **A stopped client**: never extract into a data directory an execution client is actively using.

## Restore the snapshot

<Steps>
  <Step title="Pick a snapshot">
    Pick a recent snapshot matching your network and client from your chain's snapshot provider. For OP Mainnet, browse the OP Labs managed [Data Directories website](https://datadirs.optimism.io/); the [Snapshots reference page](/op-mainnet/network-information/snapshots) lists the available sources, including third-party providers.
  </Step>

  <Step title="Download and verify it">
    Download the archive and check its SHA256 against the value published on the index page:

    ```bash theme={null}
    curl -fLO <snapshot-url>/<snapshot-file>.tar.zst

    sha256sum <snapshot-file>.tar.zst       # Linux
    shasum -a 256 <snapshot-file>.tar.zst   # macOS
    ```

    Don't skip verification — a truncated multi-hundred-gigabyte download is easy to miss and produces a corrupt database.
  </Step>

  <Step title="Stop your node and clear the old datadir">
    If the node has run before and you want to start clean from the snapshot, stop the execution client and remove (or move aside) the contents of its data directory.
  </Step>

  <Step title="Extract into the data directory">
    Inspect the archive layout first, then extract it into your client's data directory:

    ```bash theme={null}
    tar -tf <snapshot-file>.tar.zst | head -3

    mkdir -p <datadir>
    tar -I zstd -xvf <snapshot-file>.tar.zst -C <datadir> --strip-components=1
    ```

    `--strip-components=1` removes the top-level wrapping directory inside the tarball. If the inspection shows files already at the archive root, omit it. Use the same path your client is configured with (the `--datadir` flag for `op-reth`).
  </Step>

  <Step title="Start the node and confirm it picked up the snapshot">
    Start the execution client pointed at the restored data directory, then confirm the node reports the snapshot's block height — not `0` — as its latest block:

    ```bash theme={null}
    curl -s -X POST -H "Content-Type: application/json" \
      --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
      http://localhost:8545
    ```

    The node then syncs from the snapshot's tip to the current head, which takes minutes to hours depending on the snapshot's age. Once caught up, you can delete the downloaded `.tar.zst` archive to reclaim disk space.
  </Step>
</Steps>

## Next steps

* Running with Docker? The [node-from-docker tutorial](/node-operators/tutorials/node-from-docker#bootstrap-from-a-snapshot) shows this flow with a bind-mounted `op-reth` data directory.
* See the [Snapshots reference page](/op-mainnet/network-information/snapshots) for all OP Mainnet download links, including the legacy (pre-Bedrock) data directory for archive nodes.
* If you run into problems, check the [node troubleshooting guide](/node-operators/guides/troubleshooting) or reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions).


# Node Metrics and Monitoring
Source: https://docs.optimism.io/node-operators/guides/monitoring/metrics

Learn about the different metrics you can use to monitor the health of your node.

The Optimism `op-node` exposes a variety of metrics to help observe the health of the system and debug issues. Metrics are formatted for use with Prometheus and exposed via a metrics endpoint. The default metrics endpoint is `http://localhost:7300/metrics`.

To enable metrics, pass the `--metrics.enabled` flag to the `op-node`. You can customize the metrics port and address via the `--metrics.port` and `--metrics.addr` flags, respectively.

## Important metrics

To monitor the health of your node, you should monitor the following metrics:

* `op_node_default_refs_number`: This metric represents the `op-node`'s current L1/L2 reference block number for different sync types. If it stops increasing, it means that the node is not syncing. If it goes backwards, it means your node is reorging.
* `op_node_default_peer_count`: This metric represents how many peers the `op-node` is connected to. Without peers, the `op-node` cannot sync unsafe blocks and your node will lag behind the sequencer as it will fall back to syncing purely from L1.
* `op_node_default_rpc_client_request_duration_seconds`: This metric measures the latency of RPC requests initiated by the `op-node`. This metric is important when debugging sync performance, as it will reveal which specific RPC calls are slowing down sync. This metric exposes one timeseries per RPC method. The most important RPC methods to monitor are:
  * `engine_forkChoiceUpdatedV1`, `engine_getPayloadV1`, and `engine_newPayloadV1`: These methods are used to execute blocks on `op-geth`. If these methods are slow, it means that sync time is bottlenecked by either `op-geth` itself or your connection to it.
  * `eth_getBlockByHash`, `eth_getTransactionReceipt`, and `eth_getBlockByNumber`: These methods are used by the `op-node` to fetch transaction data from L1. If these methods are slow, it means that sync time is bottlenecked by your L1 RPC.

## Available metrics

A complete list of available metrics is below:

| METRIC                                                     | DESCRIPTION                                                                                      | LABELS       | TYPE      |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------ | --------- |
| op\_node\_default\_info                                    | Pseudo-metric tracking version and config info                                                   | version      | gauge     |
| op\_node\_default\_up                                      | 1 if the op node has finished starting up                                                        |              | gauge     |
| op\_node\_default\_rpc\_server\_requests\_total            | Total requests to the RPC server                                                                 | method       | counter   |
| op\_node\_default\_rpc\_server\_request\_duration\_seconds | Histogram of RPC server request durations                                                        | method       | histogram |
| op\_node\_default\_rpc\_client\_requests\_total            | Total RPC requests initiated by the opnode's RPC client                                          | method       | counter   |
| op\_node\_default\_rpc\_client\_request\_duration\_seconds | Histogram of RPC client request durations                                                        | method       | histogram |
| op\_node\_default\_rpc\_client\_responses\_total           | Total RPC request responses received by the opnode's RPC client                                  | method,error | counter   |
| op\_node\_default\_l1\_source\_cache\_size                 | L1 Source cache size                                                                             | type         | gauge     |
| op\_node\_default\_l1\_source\_cache\_get                  | L1 Source cache lookups, hitting or not                                                          | type,hit     | counter   |
| op\_node\_default\_l1\_source\_cache\_add                  | L1 Source cache additions, evicting previous values or not                                       | type,evicted | counter   |
| op\_node\_default\_l2\_source\_cache\_size                 | L2 Source cache size                                                                             | type         | gauge     |
| op\_node\_default\_l2\_source\_cache\_get                  | L2 Source cache lookups, hitting or not                                                          | type,hit     | counter   |
| op\_node\_default\_l2\_source\_cache\_add                  | L2 Source cache additions, evicting previous values or not                                       | type,evicted | counter   |
| op\_node\_default\_derivation\_idle                        | 1 if the derivation pipeline is idle                                                             |              | gauge     |
| op\_node\_default\_pipeline\_resets\_total                 | Count of derivation pipeline resets events                                                       |              | counter   |
| op\_node\_default\_last\_pipeline\_resets\_unix            | Timestamp of last derivation pipeline resets event                                               |              | gauge     |
| op\_node\_default\_unsafe\_payloads\_total                 | Count of unsafe payloads events                                                                  |              | counter   |
| op\_node\_default\_last\_unsafe\_payloads\_unix            | Timestamp of last unsafe payloads event                                                          |              | gauge     |
| op\_node\_default\_derivation\_errors\_total               | Count of derivation errors events                                                                |              | counter   |
| op\_node\_default\_last\_derivation\_errors\_unix          | Timestamp of last derivation errors event                                                        |              | gauge     |
| op\_node\_default\_sequencing\_errors\_total               | Count of sequencing errors events                                                                |              | counter   |
| op\_node\_default\_last\_sequencing\_errors\_unix          | Timestamp of last sequencing errors event                                                        |              | gauge     |
| op\_node\_default\_publishing\_errors\_total               | Count of p2p publishing errors events                                                            |              | counter   |
| op\_node\_default\_last\_publishing\_errors\_unix          | Timestamp of last p2p publishing errors event                                                    |              | gauge     |
| op\_node\_default\_unsafe\_payloads\_buffer\_len           | Number of buffered L2 unsafe payloads                                                            |              | gauge     |
| op\_node\_default\_unsafe\_payloads\_buffer\_mem\_size     | Total estimated memory size of buffered L2 unsafe payloads                                       |              | gauge     |
| op\_node\_default\_refs\_number                            | Gauge representing the different L1/L2 reference block numbers                                   | layer,type   | gauge     |
| op\_node\_default\_refs\_time                              | Gauge representing the different L1/L2 reference block timestamps                                | layer,type   | gauge     |
| op\_node\_default\_refs\_hash                              | Gauge representing the different L1/L2 reference block hashes truncated to float values          | layer,type   | gauge     |
| op\_node\_default\_refs\_seqnr                             | Gauge representing the different L2 reference sequence numbers                                   | type         | gauge     |
| op\_node\_default\_refs\_latency                           | Gauge representing the different L1/L2 reference block timestamps minus current time, in seconds | layer,type   | gauge     |
| op\_node\_default\_l1\_reorg\_depth                        | Histogram of L1 Reorg Depths                                                                     |              | histogram |
| op\_node\_default\_transactions\_sequenced\_total          | Count of total transactions sequenced                                                            |              | gauge     |
| op\_node\_default\_p2p\_peer\_count                        | Count of currently connected p2p peers                                                           |              | gauge     |
| op\_node\_default\_p2p\_stream\_count                      | Count of currently connected p2p streams                                                         |              | gauge     |
| op\_node\_default\_p2p\_gossip\_events\_total              | Count of gossip events by type                                                                   | type         | counter   |
| op\_node\_default\_p2p\_bandwidth\_bytes\_total            | P2P bandwidth by direction                                                                       | direction    | gauge     |
| op\_node\_default\_sequencer\_building\_diff\_seconds      | Histogram of Sequencer building time, minus block time                                           |              | histogram |
| op\_node\_default\_sequencer\_building\_diff\_total        | Number of sequencer block building jobs                                                          |              | counter   |
| op\_node\_default\_sequencer\_sealing\_seconds             | Histogram of Sequencer block sealing time                                                        |              | histogram |
| op\_node\_default\_sequencer\_sealing\_total               | Number of sequencer block sealing jobs                                                           |              | counter   |


# Node Troubleshooting
Source: https://docs.optimism.io/node-operators/guides/troubleshooting

Learn solutions to common problems to troubleshoot your node.

This page lists common troubleshooting scenarios and solutions for node operators.

## 401 Unauthorized: Signature Invalid

If you see a log that looks like this in `op-node`:

```
WARN [12-13|15:53:20.263] Derivation process temporary error       attempts=80 err="stage 0 failed resetting: temp: failed to find the L2 Heads to start from: failed to fetch current L2 forkchoice state: failed to find the finalized L2 block: failed to determine L2BlockRef of finalized, could not get payload: 401 Unauthorized: signature is invalid
```

It means that the `op-node` is unable to authenticate with `execution client`'s authenticated RPC using the JWT secret.

### Solution

1. Check that the JWT secret is correct in both services.
2. Check that `execution client`'s authenticated RPC is enabled, and that the URL is correct.

## Failed to Load P2P Config

If you see a log that looks like this in `op-node`:

```
CRIT [12-13|13:46:21.386] Application failed                       message="failed to load p2p config: failed to load p2p discovery options: failed to open discovery db: mkdir /p2p: permission denied"
```

It means that the `op-node` lacks write access to the P2P discovery or peerstore directories.

### Solution

1. Make sure that the `op-node` has write access to the P2P directory. By default, this is `/p2p`.
2. Set the P2P directory to somewhere the `op-node` can access via the `--p2p.discovery.path` and `--p2p.peerstore.path` parameters.
3. Set the discovery path to `memory` to disable persistence via the `--p2p.discovery.path` and `--p2p.peerstore.path` parameters.

## Wrong Chain

If you see a log that looks like this in `op-node`:

```
{"attempts":183,"err":"stage 0 failed resetting: temp: failed to find the L2 Heads to start from: wrong chain L1: genesis: 0x4104895a540d87127ff11eef0d51d8f63ce00a6fc211db751a45a4b3a61a9c83:8106656, got 0x12e2c18a3ac50f74d3dd3c0ed7cb751cc924c2985de3dfed44080e683954f1dd:8106656","lvl":"warn","msg":"Derivation process temporary error","t":"2022-12-13T23:31:37.855253213Z"}
```

It means that the `op-node` is pointing to the wrong chain.

### Solution

1. Verify that the `op-node`'s L1 URL is pointing to the correct L1 for the given network.
2. Verify that the `op-node`'s rollup config/`--network` parameter is set to the correct network.
3. Verify that the `op-node`'s L2 URL is pointing to the correct instance of `execution client`, and that `execution client` is properly initialized for the given network.

## Error: `eth_sendRawTransaction` Does Not Exist

If an RPC call to your execution client (`op-reth`, Nethermind, etc.) returns a response like:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "the method eth_sendRawTransaction does not exist/is not available"
  }
}
```

This `-32601` JSON-RPC error means the sequencer endpoint you configured does not expose `eth_sendRawTransaction`. The request path looks like:

```
Client → eth_sendRawTransaction → execution client:8545
                                ↓
                  EL forwards to sequencer (--rollup.sequencer URL)
                                ↓
              eth_sendRawTransaction → op-node:8547
                                ↓
              ❌ ERROR: "method does not exist/is not available"
                 (op-node has no eth namespace!)
```

Because `op-node` only exposes rollup-specific RPC methods—there is no `eth_*` namespace—it cannot accept raw transaction submissions. When your execution client forwards the transaction to an `op-node` URL it immediately fails with `-32601`.

This situation almost always happens when op-reth's `--rollup.sequencer` (aliases `--rollup.sequencer-http`, `--rollup.sequencer-ws`) is misconfigured to point at your own `op-node` rather than the chain's actual sequencer.

### Solution

1. Confirm op-reth exposes the `eth` namespace on its HTTP API (the standard set is `--http.api=eth,net,web3,debug`). If `eth` is disabled, raw transactions will be rejected before they reach the sequencer.
2. Inspect the CLI flags and environment variables of every component that talks to the sequencer (`op-node`, `op-reth`, `op-batcher`, `op-proposer`, scripts). The `--rollup.sequencer` flag must point to the chain's public sequencer endpoint (for example, `https://mainnet-sequencer.optimism.io`), **not** to your own `op-node`.
3. For user-deployed L2s where you run the sequencer yourself, leave `--rollup.sequencer` unset so op-reth forwards locally and never falls back to an `op-node` endpoint.
4. Restart the affected services after correcting the flag so they pick up the new endpoint. The error should disappear as soon as they can reach the proper sequencer RPC.

## Unclean Shutdowns

An unclean shutdown occurs when the execution client stops without completing its normal shutdown procedure — for example, a `SIGKILL`, a power loss, or a container killed past its grace period. The impact depends on which database backend your EL uses.

To minimize risk, always shut down gracefully: `Ctrl-C` for foreground processes, `docker stop -t 300 <container>` for Docker, or `systemctl stop` for systemd (override the default 90s timeout if your EL has a large in-memory write to flush).

### For op-reth

op-reth uses MDBX, which is crash-safe by design. After an unclean shutdown the node typically restarts cleanly with no operator intervention required.

If startup fails after an unclean shutdown, options include:

* **Stage unwind** — roll back to the last consistent stage checkpoint:

  ```bash theme={null}
  op-reth stage unwind to-block <BLOCK_NUMBER> --datadir=<path>
  ```

* **Full resync** — as a last resort, delete the datadir and resync from genesis or a [snapshot](https://datadirs.optimism.io/).

### For Nethermind

Unclean shutdowns in `Nethermind` can lead to database corruption. This typically happens when:

* The node experiences hardware failures (disk failures, memory errors, overheating)
* Power cuts cause abrupt shutdowns
* The process is terminated without proper cleanup

**Solutions**

1. **Lock File Issues**

   If `Nethermind` complains about lock files after an unclean shutdown, run:

   ```bash theme={null}
   find /path/to/nethermind_db -type f -name 'LOCK' -delete
   ```

2. **Block Checksum Mismatch**

   If you encounter block checksum mismatch errors, you can enable direct I/O:

   ```bash theme={null}
   --Db.UseDirectIoForFlushAndCompactions true
   ```

   Note: This may impact performance.

3. **Complete Resync**

   In cases of severe corruption, a full resync is recommended:

   ```bash theme={null}
   sudo systemctl stop nethermind
   sudo rm -rf /path/to/nethermind_db/mainnet
   sudo systemctl start nethermind
   ```


# Kona Node CLI Reference
Source: https://docs.optimism.io/node-operators/kona-node/configuration

Reference for all kona-node CLI flags and environment variables, grouped by category, plus default ports and default runtime behavior.

This document lists all CLI flags for the `kona-node node` subcommand, grouped by category. All flags can be provided as command-line arguments or via environment variables.

<Note>
  For more details on each flag, see the inline help (`kona-node node --help`) or the source code.
</Note>

## Default Ports

| Service       | Default Port | Flag/Env                                             |
| ------------- | ------------ | ---------------------------------------------------- |
| RPC HTTP      | 9545         | `--port` / `KONA_NODE_RPC_PORT`                      |
| RPC WebSocket | 9545         | (same as HTTP, enabled with `--rpc.ws-enabled`)      |
| P2P TCP       | 9222         | `--p2p.listen.tcp` / `KONA_NODE_P2P_LISTEN_TCP_PORT` |
| P2P UDP       | 9223         | `--p2p.listen.udp` / `KONA_NODE_P2P_LISTEN_UDP_PORT` |

`kona-node` does not run a supervisor RPC server: the binary has no `--supervisor.*`
flag group. Its only interop flag, `--interop.dependency-set`
(`KONA_NODE_INTEROP_DEPENDENCY_SET`), takes a path to a dependency-set JSON file
rather than a port.

`--conductor.rpc` (`KONA_NODE_CONDUCTOR_RPC`) is not a listening port either. It is
the RPC endpoint URL of an external conductor service that the node dials out to,
and it has no default value. Supplying it enables the conductor integration when the
node runs in sequencer mode (`--mode sequencer`); in validator mode it has no effect.

## Core Node Arguments

| Flag                                            | Env                                           | Description                                                                 | Required | Default     |
| ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------- | -------- | ----------- |
| `--mode <validator/sequencer>`                  | `KONA_NODE_MODE`                              | Mode of operation for the node                                              | No       | `validator` |
| `--l1-eth-rpc <URL>`                            | `KONA_NODE_L1_ETH_RPC`                        | URL of the L1 execution client RPC API                                      | Yes      | -           |
| `--l1-trust-rpc <true/false>`                   | `KONA_NODE_L1_TRUST_RPC`                      | Whether to trust the L1 RPC without verification                            | No       | `true`      |
| `--l1-beacon <URL>`                             | `KONA_NODE_L1_BEACON`                         | URL of the L1 beacon API                                                    | Yes      | -           |
| `--l2-engine-rpc <URL>`                         | `KONA_NODE_L2_ENGINE_RPC`                     | URL of the engine API endpoint of an L2 execution client                    | Yes      | -           |
| `--l2-trust-rpc <true/false>`                   | `KONA_NODE_L2_TRUST_RPC`                      | Whether to trust the L2 RPC without verification                            | No       | `true`      |
| `--l2-engine-jwt-secret <PATH>`                 | `KONA_NODE_L2_ENGINE_AUTH`                    | Path to file containing the hex-encoded JWT secret for the execution client | No       | -           |
| `--l2-config-file <PATH>`                       | `KONA_NODE_ROLLUP_CONFIG`                     | Path to a custom L2 rollup configuration file                               | No       | -           |
| `--l1-runtime-config-reload-interval <SECONDS>` | `KONA_NODE_L1_RUNTIME_CONFIG_RELOAD_INTERVAL` | Poll interval for reloading runtime config                                  | No       | `600`       |

## Global Arguments

| Flag                                        | Env                     | Description                                  | Required | Default         |
| ------------------------------------------- | ----------------------- | -------------------------------------------- | -------- | --------------- |
| `--l2-chain-id <ID/NAME>` or `-c <ID/NAME>` | `KONA_NODE_L2_CHAIN_ID` | L2 chain ID (numeric) or chain name (string) | No       | `10` (Optimism) |

### Chain ID Support

The `--l2-chain-id` flag supports flexible chain identification using the `alloy_chains` crate:

**Numeric Chain IDs:**

```bash theme={null}
kona-node --l2-chain-id 10 node [args...]      # Optimism mainnet
kona-node --l2-chain-id 8453 node [args...]    # Base mainnet
kona-node --l2-chain-id 1 node [args...]       # Ethereum mainnet
```

**String Chain Names:**

```bash theme={null}
kona-node --l2-chain-id optimism node [args...]
kona-node --l2-chain-id base node [args...]
kona-node --l2-chain-id mainnet node [args...]
```

**Short Flag and Environment Variable:**

```bash theme={null}
kona-node -c optimism node [args...]
export KONA_NODE_L2_CHAIN_ID=optimism && kona-node node [args...]
```

Supported chain names include all those recognized by `alloy_chains` (e.g., `optimism`, `base`, `mainnet`). Unknown numeric chain IDs are accepted for custom networks.

## P2P Arguments

| Flag                                  | Env                                  | Description                                         | Default   |
| ------------------------------------- | ------------------------------------ | --------------------------------------------------- | --------- |
| `--p2p.no-discovery`                  | `KONA_NODE_P2P_NO_DISCOVERY`         | Disable Discv5 (node discovery)                     | `false`   |
| `--p2p.priv.path <PATH>`              | `KONA_NODE_P2P_PRIV_PATH`            | Path to hex-encoded 32-byte private key for peer ID | -         |
| `--p2p.priv.raw <HEX>`                | `KONA_NODE_P2P_PRIV_RAW`             | Hex-encoded 32-byte private key for peer ID         | -         |
| `--p2p.advertise.ip <IP>`             | `KONA_NODE_P2P_ADVERTISE_IP`         | IP to advertise to external peers                   | -         |
| `--p2p.advertise.tcp <PORT>`          | `KONA_NODE_P2P_ADVERTISE_TCP_PORT`   | TCP port to advertise                               | `0`       |
| `--p2p.advertise.udp <PORT>`          | `KONA_NODE_P2P_ADVERTISE_UDP_PORT`   | UDP port to advertise                               | `0`       |
| `--p2p.listen.ip <IP>`                | `KONA_NODE_P2P_LISTEN_IP`            | IP to bind LibP2P/Discv5 to                         | `0.0.0.0` |
| `--p2p.listen.tcp <PORT>`             | `KONA_NODE_P2P_LISTEN_TCP_PORT`      | TCP port to bind LibP2P to                          | `9222`    |
| `--p2p.listen.udp <PORT>`             | `KONA_NODE_P2P_LISTEN_UDP_PORT`      | UDP port to bind Discv5 to                          | `9223`    |
| `--p2p.peers.lo <N>`                  | `KONA_NODE_P2P_PEERS_LO`             | Low-tide peer count                                 | `20`      |
| `--p2p.peers.hi <N>`                  | `KONA_NODE_P2P_PEERS_HI`             | High-tide peer count                                | `30`      |
| `--p2p.peers.grace <SECONDS>`         | `KONA_NODE_P2P_PEERS_GRACE`          | Grace period for new peers                          | `30`      |
| `--p2p.gossip.mesh.d <N>`             | `KONA_NODE_P2P_GOSSIP_MESH_D`        | GossipSub mesh target count                         | `8`       |
| `--p2p.gossip.mesh.lo <N>`            | `KONA_NODE_P2P_GOSSIP_MESH_DLO`      | GossipSub mesh low watermark                        | `6`       |
| `--p2p.gossip.mesh.dhi <N>`           | `KONA_NODE_P2P_GOSSIP_MESH_DHI`      | GossipSub mesh high watermark                       | `12`      |
| `--p2p.gossip.mesh.dlazy <N>`         | `KONA_NODE_P2P_GOSSIP_MESH_DLAZY`    | GossipSub gossip target                             | `6`       |
| `--p2p.gossip.mesh.floodpublish`      | `KONA_NODE_P2P_GOSSIP_FLOOD_PUBLISH` | Publish to all known peers                          | `false`   |
| `--p2p.scoring <none or light>`       | `KONA_NODE_P2P_SCORING`              | Peer scoring strategy                               | `light`   |
| `--p2p.ban.peers`                     | `KONA_NODE_P2P_BAN_PEERS`            | Enable peer banning                                 | `false`   |
| `--p2p.ban.threshold <N>`             | `KONA_NODE_P2P_BAN_THRESHOLD`        | Ban threshold                                       | `-100`    |
| `--p2p.ban.duration <MINUTES>`        | `KONA_NODE_P2P_BAN_DURATION`         | Ban duration                                        | `60`      |
| `--p2p.discovery.interval <SECONDS>`  | `KONA_NODE_P2P_DISCOVERY_INTERVAL`   | Peer discovery interval                             | `5`       |
| `--p2p.bootstore <PATH>`              | `KONA_NODE_P2P_BOOTSTORE`            | Directory to store the bootstore                    | -         |
| `--p2p.redial <N>`                    | `KONA_NODE_P2P_REDIAL`               | Peer redialing threshold                            | `500`     |
| `--p2p.redial.period <MINUTES>`       | `KONA_NODE_P2P_REDIAL_PERIOD`        | Peer dial period                                    | `60`      |
| `--p2p.bootnodes <ENR,...>`           | `KONA_NODE_P2P_BOOTNODES`            | List of bootnode ENRs                               | -         |
| `--p2p.topic-scoring`                 | `KONA_NODE_P2P_TOPIC_SCORING`        | Enable topic scoring                                | `false`   |
| `--p2p.discovery.randomize <SECONDS>` | `KONA_NODE_P2P_DISCOVERY_RANDOMIZE`  | Remove random peers from discovery                  | -         |

## RPC Arguments

| Flag                       | Env                          | Description                           | Default   |
| -------------------------- | ---------------------------- | ------------------------------------- | --------- |
| `--rpc.disabled`           | `KONA_NODE_RPC_DISABLED`     | Disable the RPC server                | `false`   |
| `--rpc.no-restart`         | `KONA_NODE_RPC_NO_RESTART`   | Prevent RPC server from restarting    | `false`   |
| `--rpc.addr <IP>`          | `KONA_NODE_RPC_ADDR`         | RPC listening address                 | `0.0.0.0` |
| `--port <PORT>`            | `KONA_NODE_RPC_PORT`         | RPC listening port                    | `9545`    |
| `--rpc.enable-admin`       | `KONA_NODE_RPC_ENABLE_ADMIN` | Enable the admin API                  | `false`   |
| `--rpc.admin-state <PATH>` | `KONA_NODE_RPC_ADMIN_STATE`  | File path for admin state persistence | -         |
| `--rpc.ws-enabled`         | `KONA_NODE_RPC_WS_ENABLED`   | Enable websocket RPC server           | `false`   |

## Sequencer Arguments

| Flag                                | Env                                | Description                                                                                                                                              | Default |
| ----------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--sequencer.stopped`               | `KONA_NODE_SEQUENCER_STOPPED`      | Start sequencer in stopped state                                                                                                                         | `false` |
| `--sequencer.max-safe-lag <N>`      | `KONA_NODE_SEQUENCER_MAX_SAFE_LAG` | Max L2 safe/unsafe lag                                                                                                                                   | `0`     |
| `--sequencer.l1-confs <N>`          | `KONA_NODE_SEQUENCER_L1_CONFS`     | L1 block confirmations for sequencer                                                                                                                     | `4`     |
| `--sequencer.recover`               | `KONA_NODE_SEQUENCER_RECOVER`      | Strictly prepare next L1 origin and create empty L2 blocks                                                                                               | `false` |
| `--conductor.rpc <URL>`             | `KONA_NODE_CONDUCTOR_RPC`          | RPC endpoint URL of an external conductor service. Supplying it enables the conductor integration in sequencer mode; it has no effect in validator mode. | -       |
| `--conductor.rpc.timeout <SECONDS>` | `KONA_NODE_CONDUCTOR_RPC_TIMEOUT`  | Conductor service RPC timeout                                                                                                                            | `1`     |

## Interop Arguments

| Flag                              | Env                                | Description                                                                                                                                | Default |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- |
| `--interop.dependency-set <PATH>` | `KONA_NODE_INTEROP_DEPENDENCY_SET` | Path to the JSON file describing the interop dependency set for this chain. Required when the rollup config schedules the Lagoon hardfork. | -       |

`kona-node` does not run a supervisor RPC server, so there is no `--supervisor.*`
flag group. `--interop.dependency-set` is the node's only interop flag.

## RPC Trust Flags

The `--l1-trust-rpc` and `--l2-trust-rpc` flags control whether Kona verifies the block hashes of RPC responses. For guidance on when to disable trust and worked examples for trusted, untrusted, and mixed provider setups, see [configure RPC trust](/node-operators/kona-node/run/rpc-trust).

## Default Behavior

Unless overridden by the flags above, a `kona-node node` run has the following defaults:

* The P2P stack is spun up. The libp2p swarm listens on TCP `9222`
  to receive block gossip. The `discv5` discovery service runs on
  UDP port `9223`. Peer scoring is enabled.
* An RPC server is exposed at `0.0.0.0:9545`. Websocket connections
  are disabled by default.
* Prometheus metrics are disabled. Enable them with the
  `--metrics.enabled` flag; metrics are then served on `0.0.0.0:9090`,
  configurable via the `--metrics.port` and `--metrics.addr` flags.

## Rollup Configuration Loading

If a file path to a rollup config is *not* specified via the
`--l2-config-file` cli flag, the Rollup Config will be loaded
via the [superchain registry][scr].

A custom rollup config can either be specified through the
`--l2-config-file` flag, or specific values may be overridden
using a set of override flags provided by the `kona-node`.

Override flags (for example `--canyon-override`) can be viewed
in the help menu by running `kona-node node --help`. The only
overrides currently supported are hardfork timestamps in seconds.

[scr]: https://github.com/ethereum-optimism/superchain-registry/tree/main


# Derivation in Kona Node
Source: https://docs.optimism.io/node-operators/kona-node/design/derivation



The derivation system in kona-node is responsible for transforming L1 data into L2 payload attributes that can be executed to produce the canonical L2 blocks. This document covers how the [`kona-derive`][kd] crate is integrated and used within the kona-node architecture.

## Overview

The derivation subsystem in kona-node is built around the **DerivationActor**, which manages the derivation pipeline lifecycle and coordinates with other node components. The actor uses the trait-abstracted [`kona-derive`][kd] pipeline to continuously process L1 data and produce L2 payload attributes.

### Key Components

* **DerivationActor**: The main actor responsible for running the derivation pipeline
* **OnlinePipeline**: A concrete implementation of the derivation pipeline using online providers
* **DerivationStateMachine**: Manages when derivation is allowed to occur and tracks the confirmed safe head
* **L2Finalizer**: Tracks derived L2 blocks awaiting finalization
* **Signal System**: Handles pipeline resets, hardfork activations, and error conditions

## Architecture

### DerivationActor

The `DerivationActor` is a [`NodeActor`][na] that runs as part of the node service. It receives requests from other actors over a single inbound channel and steps the derivation pipeline forward to produce new payload attributes.

```rust theme={null}
pub struct DerivationActor<DerivationEngineClient_, PipelineSignalReceiver>
where
    DerivationEngineClient_: DerivationEngineClient,
    PipelineSignalReceiver: Pipeline + SignalReceiver,
{
    /// The channel on which all inbound requests are received by the actor.
    inbound_request_rx: mpsc::Receiver<DerivationActorRequest>,
    /// The Engine client used to interact with the engine.
    engine_client: DerivationEngineClient_,
    /// The derivation pipeline.
    pipeline: PipelineSignalReceiver,
    /// The state machine controlling when derivation can occur.
    derivation_state_machine: DerivationStateMachine,
    /// The L2Finalizer tracks derived L2 blocks awaiting finalization.
    finalizer: L2Finalizer,
}
```

Inbound requests are expressed as the `DerivationActorRequest` enum: L1 head updates, finalized L1 block updates, engine safe head updates, engine sync completion, and pipeline signals from the engine (for example flush or reset).

The actor coordinates with several other node components:

* **Engine Actor**: Receives payload attributes for execution and sends back safe head updates and pipeline signals
* **L1 Watcher Actor**: Sends L1 head and finalized block updates from the L1 chain

### Pipeline Construction

The derivation pipeline is constructed by the `RollupNode` service when it wires up the derivation actor. The node builds caching L1/L2 providers and then creates an `OnlinePipeline` in one of two modes, selected by `InteropMode`:

1. **Polled Mode**: Uses polling-based L1 block traversal
2. **Indexed Mode**: Uses indexed L1 block traversal for more efficient L1 block handling

```rust theme={null}
match self.interop_mode {
    InteropMode::Polled => OnlinePipeline::new_polled(
        self.config.clone(),
        self.l1_config.chain_config.clone(),
        OnlineBlobProvider::init(self.l1_config.beacon_client.clone()).await,
        l1_derivation_provider,
        l2_derivation_provider,
        self.dependency_set.clone(),
    ),
    InteropMode::Indexed => OnlinePipeline::new_indexed(
        self.config.clone(),
        self.l1_config.chain_config.clone(),
        OnlineBlobProvider::init(self.l1_config.beacon_client.clone()).await,
        l1_derivation_provider,
        l2_derivation_provider,
        self.dependency_set.clone(),
    ),
}
```

### Provider Configuration

The node uses caching providers to optimize performance:

* **AlloyChainProvider**: Provides L1 blockchain data with configurable cache size
* **AlloyL2ChainProvider**: Provides L2 blockchain data and system configuration
* **OnlineBlobProvider**: Retrieves blob data from the beacon chain for post-4844 transactions

The cache size is set to 1024 entries by default:

```rust theme={null}
const DERIVATION_PROVIDER_CACHE_SIZE: usize = 1024;
```

## Pipeline Operation

### Main Processing Loop

The derivation actor runs a continuous loop that handles various events:

1. **Shutdown signals**: Graceful shutdown when cancellation token is triggered
2. **L1 head updates**: Triggers derivation when new L1 blocks are available
3. **Safe head updates**: Triggers derivation when the L2 safe head advances
4. **Pipeline signals**: Handles resets, hardfork activations, and channel flushes

### Stepping Logic

The core derivation logic is implemented in `produce_next_attributes()`:

```rust theme={null}
async fn produce_next_attributes(
    &mut self,
) -> Result<OpAttributesWithParent, DerivationError>
```

This method continuously steps the pipeline until payload attributes are produced:

1. **Step the pipeline** with the last confirmed L2 safe head from the derivation state machine
2. **Handle step results**:
   * `PreparedAttributes`: Attributes are ready to be consumed
   * `AdvancedOrigin`: Pipeline advanced to next L1 block
   * `OriginAdvanceErr`/`StepFailed`: Handle various error conditions
3. **Return attributes** when available

### Error Handling

The derivation actor handles three categories of pipeline errors:

#### Temporary Errors

* `PipelineError::NotEnoughData`: Continue stepping, more data may become available
* `PipelineError::Eof`: Yield and wait for more L1 data

#### Reset Errors

* `ResetError::HoloceneActivation`: Send `ActivationSignal` to handle hardfork
* `ResetError::ReorgDetected`: Send reset request to engine (if not in interop mode)
* Other reset errors: Wait for external signal before continuing

#### Critical Errors

* Unrecoverable errors that terminate the derivation process
* Increment metrics counter and propagate error up

### Signal Handling

The pipeline supports several signal types for coordination:

* **ResetSignal**: Resets pipeline state with new L1 origin and system config
* **ActivationSignal**: Handles hardfork activations (e.g., Holocene)
* **FlushChannel**: Invalidates current channel data for deposit-only blocks

Signals are sent from the engine actor when specific conditions are detected during payload execution.

## Configuration

### Rollup Configuration

The derivation pipeline requires a [`RollupConfig`][rc] that defines:

* Chain parameters (chain ID, block time, etc.)
* Hardfork activation heights
* System configuration addresses
* Batch and channel parameters

### Runtime Configuration

Runtime configuration includes:

* Provider cache sizes
* Polling intervals for L1 data
* Interop mode selection
* Metrics collection settings

## Integration Patterns

### With Engine Actor

The derivation actor produces `OpAttributesWithParent` that are sent to the engine actor for execution through the `DerivationEngineClient` interface:

```rust theme={null}
// Send payload attributes out for processing.
self.engine_client
    .send_safe_l2_signal(payload_attributes.into())
    .await
```

The engine actor executes these attributes and updates the L2 safe head, which triggers the next derivation cycle.

### With the L1 Watcher

The derivation actor receives L1 head updates from the L1 watcher actor as `DerivationActorRequest::ProcessL1HeadUpdateRequest` messages on its inbound request channel, which indicate when new L1 data is available for processing. Finalized L1 blocks arrive the same way and drive the `L2Finalizer`.

### With RPC Layer

The RPC layer can query derivation status and potentially trigger pipeline operations through the standard node RPC interface.

## Metrics and Observability

The derivation actor exposes several metrics for monitoring:

* `DERIVATION_L1_ORIGIN`: Current L1 origin block number
* `DERIVATION_CRITICAL_ERROR`: Count of critical derivation errors
* `L1_REORG_COUNT`: Count of detected L1 reorganizations

These metrics help operators monitor the health and progress of the derivation process.

## Related Documentation

For more details on the underlying derivation pipeline implementation, see:

* The [`kona-derive` crate source](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/protocol/derive)
* The [`kona-derive` API documentation](https://docs.rs/kona-derive/latest/kona_derive/) on docs.rs
* The [derivation pipeline specification](https://specs.optimism.io/protocol/derivation.html)

[kd]: https://crates.io/crates/kona-derive

[na]: /node-operators/kona-node/design/intro#actors

[rc]: https://docs.rs/kona-genesis/latest/kona_genesis/struct.RollupConfig.html


# Execution Engine
Source: https://docs.optimism.io/node-operators/kona-node/design/engine



The `kona-engine` crate provides a modular execution engine implementation for the OP Stack rollup node. It serves as the bridge between the rollup protocol and the execution layer (EL), managing Engine API interactions through a sophisticated task queue system.

## Architecture Overview

The execution engine is built around several key components:

* **Engine Task Queue**: A priority-ordered queue that manages Engine API operations
* **Trait Abstractions**: Extensible interfaces for tasks, errors, and state management
* **Engine Client**: HTTP client for communicating with the execution layer
* **Actor Integration**: Service layer integration through the `EngineActor`

## Core Trait Abstractions

### EngineTaskExt

The `EngineTaskExt` trait defines the interface for all engine tasks:

```rust theme={null}
#[async_trait]
pub trait EngineTaskExt {
    type Output;
    type Error: EngineTaskError;

    async fn execute(&self, state: &mut EngineState) -> Result<Self::Output, Self::Error>;
}
```

This trait enables:

* **Atomic operations** over the `EngineState`
* **Extensible task implementation** for custom operations
* **Async execution** with proper error handling

### EngineTaskError

The `EngineTaskError` trait provides sophisticated error handling with severity levels:

```rust theme={null}
pub trait EngineTaskError {
    fn severity(&self) -> EngineTaskErrorSeverity;
}

pub enum EngineTaskErrorSeverity {
    Temporary,  // Retry the task
    Critical,   // Propagate to engine actor
    Reset,      // Request derivation reset
    Flush,      // Request derivation flush
}
```

This allows tasks to signal different recovery strategies based on the error type.

## Task Queue System

The engine uses a priority-based task queue (a binary heap ordered by the `EngineTask` `Ord` implementation) where tasks are ordered according to OP Stack synchronization requirements. Tasks are generic over an `EngineClient` implementation.

### Task Priority (Highest to Lowest)

1. **Seal** - Seals blocks that have finished building (sequencer mode)
2. **Build** - Builds new blocks (sequencer mode)
3. **Insert** - Inserts unsafe blocks from gossip
4. **Consolidate** - Advances safe chain via derivation
5. **Finalize** - Finalizes L2 blocks

Forkchoice updates are not a standalone queue entry: the `SynchronizeTask` runs as part of the other tasks whenever the forkchoice state needs to move.

### Task Types

#### SynchronizeTask

Updates the execution layer's forkchoice state. It is invoked by the other tasks rather than queued directly:

```rust theme={null}
pub struct SynchronizeTask<EngineClient_: EngineClient> {
    /// The engine client.
    pub client: Arc<EngineClient_>,
    /// The rollup config.
    pub rollup: Arc<RollupConfig>,
    /// The sync state update to apply to the engine state.
    pub state_update: EngineSyncStateUpdate,
}
```

Handles:

* Forkchoice synchronization via `engine_forkchoiceUpdated`
* EL sync status management

#### BuildTask

Starts building a new block in sequencer mode, producing a payload ID:

```rust theme={null}
pub struct BuildTask<EngineClient_: EngineClient> {
    /// The engine API client.
    pub engine: Arc<EngineClient_>,
    /// The RollupConfig.
    pub cfg: Arc<RollupConfig>,
    /// The OpAttributesWithParent to instruct the execution layer to build.
    pub attributes: OpAttributesWithParent,
    /// The optional sender through which the PayloadId will be sent
    /// after the block build has been started.
    pub payload_id_tx: Option<mpsc::Sender<PayloadId>>,
}
```

Handles payload building initiation with `engine_forkchoiceUpdated`.

#### SealTask

Seals a block started by a `BuildTask`, retrieving the payload with version-specific `engine_getPayload` calls, inserting it, and canonicalizing it:

```rust theme={null}
pub struct SealTask<EngineClient_: EngineClient> {
    /// The engine API client.
    pub engine: Arc<EngineClient_>,
    /// The RollupConfig.
    pub cfg: Arc<RollupConfig>,
    /// The PayloadId being sealed.
    pub payload_id: PayloadId,
    /// The OpAttributesWithParent to instruct the execution layer to build.
    pub attributes: OpAttributesWithParent,
    /// Whether or not the payload was derived, or created by the sequencer.
    pub is_attributes_derived: bool,
    /// An optional sender for the built OpExecutionPayloadEnvelope or the
    /// SealTaskError that occurred during processing.
    pub result_tx: Option<mpsc::Sender<Result<OpExecutionPayloadEnvelope, SealTaskError>>>,
}
```

#### InsertTask

Inserts payloads (for example unsafe blocks received from gossip) into the execution engine:

```rust theme={null}
pub struct InsertTask<EngineClient_: EngineClient> {
    /// The engine client.
    client: Arc<EngineClient_>,
    /// The rollup config.
    rollup_config: Arc<RollupConfig>,
    /// The network payload envelope.
    envelope: OpExecutionPayloadEnvelope,
    /// If the payload is safe this is true.
    is_payload_safe: bool,
}
```

#### ConsolidateTask

Advances the safe chain through derivation:

```rust theme={null}
pub struct ConsolidateTask<EngineClient_: EngineClient> {
    /// The engine client.
    pub client: Arc<EngineClient_>,
    /// The RollupConfig.
    pub cfg: Arc<RollupConfig>,
    /// The input for consolidation (either attributes or block info).
    pub input: ConsolidateInput,
}
```

If consolidation fails, the task reverts to payload attribute processing via the `BuildTask`.

#### FinalizeTask

Finalizes L2 blocks:

```rust theme={null}
pub struct FinalizeTask<EngineClient_: EngineClient> {
    /// The engine client.
    pub client: Arc<EngineClient_>,
    /// The rollup config.
    pub cfg: Arc<RollupConfig>,
    /// Identifier of the L2 block to finalize.
    pub block_id: FinalizeBlockId,
}
```

## Engine State Management

The `EngineState` tracks the current state of the execution engine:

```rust theme={null}
pub struct EngineState {
    /// The sync state of the engine.
    pub sync_state: EngineSyncState,
    /// Whether or not the EL has finished syncing.
    pub el_sync_finished: bool,
    /// Tracks when the rollup node changes the forkchoice to restore a
    /// previously known unsafe chain (e.g. an unsafe reorg caused by an
    /// invalid span batch).
    pub need_fcu_call_backup_unsafe_reorg: bool,
}
```

The unsafe, safe, and finalized heads live in the nested `EngineSyncState`. State updates are communicated through watch channels, enabling reactive programming patterns across the system.

## Integration with kona-node

The `kona-node` service layer integrates the engine through the `EngineActor`:

### Actor Pattern

The `EngineActor` implements the `NodeActor` trait:

```rust theme={null}
#[async_trait]
pub trait NodeActor: Send + 'static {
    /// The error type for the actor.
    type Error: std::fmt::Debug;

    /// Handle the next inbound request, event, or scheduled tick.
    async fn step(&mut self) -> Result<(), Self::Error>;
}
```

### Communication Channels

The `EngineActor` receives all state-mutating input through a single inbound request channel of `EngineActorRequest` messages: payload attributes from derivation, unsafe blocks from gossip, reset requests, finalization requests, and block building requests (sequencer mode only). A separate read-only `EngineRpcActor` runs as an independent peer and serves engine queries; it shares the engine client and a watch over the engine state and queue length, but is constrained to a read-only subset of the engine client so it cannot reach Engine API mutation methods.

### Engine Queries

The engine supports queries for:

```rust theme={null}
pub enum EngineQueries {
    /// Request the current rollup configuration.
    Config(Sender<RollupConfig>),
    /// Request the current EngineState snapshot.
    State(Sender<EngineState>),
    /// Request the L2 output root for a specific block.
    OutputAtBlock { block: BlockNumberOrTag, sender: Sender<(L2BlockInfo, OutputRoot, EngineState)> },
    /// Subscribe to engine state updates via a watch channel receiver.
    StateReceiver(Sender<tokio::sync::watch::Receiver<EngineState>>),
    /// Development API: Subscribe to task queue length updates.
    QueueLengthReceiver(Sender<tokio::sync::watch::Receiver<usize>>),
    /// Development API: Get the current number of pending tasks in the queue.
    TaskQueueLength(Sender<usize>),
}
```

## Usage Patterns

### Basic Engine Setup

```rust theme={null}
// Create an engine client. The `EngineClient` trait is implemented by
// `OpEngineClient`, constructed through the `EngineClientBuilder`.
let client = EngineClientBuilder {
    l2: l2_engine_url,
    l2_jwt: jwt_secret,
    l1_rpc: l1_rpc_url,
    cfg: rollup_config,
}
.build();

// Initialize engine state
let state = EngineState::default();
let (state_sender, state_receiver) = watch::channel(state);
let (queue_length_sender, queue_length_receiver) = watch::channel(0);

// Create engine with task queue
let engine = Engine::new(state, state_sender, queue_length_sender);
```

### Adding Tasks

```rust theme={null}
// Add a consolidate task
let task = EngineTask::Consolidate(Box::new(ConsolidateTask::new(
    client.clone(),
    rollup_config.clone(),
    input,
)));

engine.enqueue(task);
```

### Draining the Queue

```rust theme={null}
// Process all pending tasks
match engine.drain().await {
    Ok(()) => info!("Tasks completed successfully"),
    Err(e) => match e.severity() {
        EngineTaskErrorSeverity::Reset => {
            // Request derivation reset
        },
        EngineTaskErrorSeverity::Critical => {
            // Handle critical error
        },
        _ => {
            // Handle other error types
        }
    }
}
```

## Error Handling and Recovery

The engine provides robust error handling through:

### Severity-Based Recovery

* **Temporary errors**: Automatically retried
* **Critical errors**: Propagated to the actor
* **Reset errors**: Trigger derivation pipeline reset
* **Flush errors**: Trigger derivation pipeline flush

### State Consistency

Tasks operate atomically on the `EngineState`, ensuring consistency even during error conditions.

## Version Support

The engine automatically selects appropriate Engine API versions based on hardfork activation:

* **Pre-Ecotone (Bedrock, Canyon, Delta)**: Uses `engine_newPayloadV2` and `engine_getPayloadV2`
* **Post-Ecotone**: Uses `engine_newPayloadV3` and `engine_getPayloadV3`
* **Post-Isthmus**: Uses `engine_newPayloadV4` and `engine_getPayloadV4`
* **Post-Karst (Osaka)**: Uses `engine_getPayloadV5` (`engine_newPayload` and `engine_forkchoiceUpdated` stay at their V4/V3 versions)

## Metrics and Observability

When the `metrics` feature is enabled, the engine provides comprehensive metrics for:

* Task execution times
* Error rates by task type
* Engine state transitions
* API call latencies

## Extensibility

The trait-based architecture allows for:

* **Custom task implementations** via `EngineTaskExt`
* **Custom error handling** via `EngineTaskError`
* **Custom state management** extensions
* **Testing and mocking** support

This modular design ensures the engine can adapt to future OP Stack protocol changes while maintaining backward compatibility.


# Node Design Overview
Source: https://docs.optimism.io/node-operators/kona-node/design/intro



The entry-point for the `kona-node` is the [`RollupNode`][node] service,
which encapsulates the core wiring for the node. A `RollupNode` is
constructed through the [`RollupNodeBuilder`][builder], and its
[`start` method][start] handles connecting all the different components
of the node, running each in a spawned task. As such, each node
component is considered an actor.

The `RollupNode` abstracts individual actors through the
[`NodeActor` trait][actor], a minimal interface with a single `step`
method that the service drives in a loop until the actor reports a
fatal error or the node shuts down.

Kona provides implementations for all `NodeActor`s required to run a
`RollupNode`. Actors are defined in the [actors][actors] module of the
`kona-node-service` crate, and the `RollupNode` wiring lives in the
[service][service] module.

### Actors

The architecture of `kona-node` is a web of actors that share
state through message passing, using channels, rather than using
shared memory.

The [`RollupNode`][node] builds and starts the following actors.

* **Derivation Actor**: Orchestrates the derivation pipeline,
  deriving L2 payload attributes from L1 blocks. Payload
  attributes prepared this way are forwarded to the Engine
  Actor to be executed. The [derivation][derivation] docs
  dive deeper into how the derivation actor works.
* **Engine Actor**: Brokers the connection to the execution
  layer client (or "execution engine"). The engine actor
  turns messages from other actors into engine "tasks"
  that are executed in priority order against the EL client.
  A companion engine RPC actor serves read-only engine
  queries. The [engine][engine] docs expand on this.
* **L1 Watcher Actor**: Watches the L1 chain for new
  head and finalized blocks and relays them to the
  derivation actor.
* **Network Actor**: Manages the P2P Network for the rollup
  node. The P2P stack consists of `discv5` peer discovery
  and block gossip through libp2p. Visit the [network][p2p]
  docs for more detail.
* **Sequencer Actor**: The sequencer actor extends the
  `kona-node` to be run as a sequencer. Sequencing is
  periphery to the basic rollup node operation. See
  the [sequencer][sequencer] docs.
* **RPC Actor**: The RPC actor spins up and serves an
  RPC server that exposes the rpc methods required by
  the [OP Stack Specs][specs].

[p2p]: ./p2p

[engine]: ./engine

[derivation]: ./derivation

[sequencer]: ./sequencer

[specs]: https://specs.optimism.io/protocol/rollup-node.html

[service]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/node/service/src/service

[actors]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/node/service/src/actors

[actor]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/actors/traits.rs

[start]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/node.rs

[node]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/node.rs

[builder]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/builder.rs


# P2P Networking
Source: https://docs.optimism.io/node-operators/kona-node/design/p2p



<Info>
  Partly adapted from the [OP Stack P2P Specs][p2p-specs].
  Please reference the specs for up-to-date OP Stack requirements.
</Info>

The OP Stack uses P2P networking on the consensus layer to share
the sequencer's view of the L2 chain with other nodes on the
network. L2 blocks shared via P2P are considered "unsafe", and
will be reorganized to match the canonical chain, prioritizing L1.

This means that behavior on the P2P layer does not affect the
rollup security. As such, rules around banning and scoring peers
based on their P2P gossip is policy - it is up to the user to
ultimately choose a configuration best for them.

To understand how the P2P is hooked up to the `kona-node`, jump
to the [P2P Actor](#p2p-actor) section below. Otherwise, read
on to learn more about the details of the P2P stack.

### Topography

The P2P stack topography consists of the following.

* Discovery of peers via [discv5][discv5].
* Gossip and peer connection management through [libp2p][libp2p].
* Publishing and validation of gossip by the node.

In the `kona-node`, these layers are split up into modular
components either as modules or distinct crates.

#### Discovery

Kona's discovery layer is encapsulated in a "driver" called
the [`Discv5Driver`][driver]. When started, the driver spawns a
new thread to handle [`discv5::Discv5`][discv5-service] events
from its event stream as well as metrics requests from the
`kona-node`. A "handler" is returned by the consumed
[`Discv5Driver`][driver] which allows other components of
the `kona-node` to communicate through channels to the
spawned [`discv5::Discv5`][discv5-service] service.

When peers are discovered by kona's discovery service, their
"ENR"s need to be validated to ensure those peers are
participating in the right network gossip. Ethereum Node
Records (ENRs) and how they are validated is discussed in a
[later section](#node-identification). After their ENRs are
validated, they are forwarded to the consumer (in kona's case
libp2p) which establishes and manages the connection to the
node.

There are also a few more notable functions of Kona's discovery
driver.

* Every X seconds it attempts to discover random ENRs. This is
  configurable using `Discv5Builder::with_interval`
* Every Y seconds it evicts a random ENR from the discovery
  table to keep peer discovery fresh. This is configurable
  using `Discv5Builder::with_discovery_randomize`.
* Every Z seconds it stores its ENR table at a configurable
  location so if the service is restarted, it doesn't need to
  rediscover peers, it can just use the stored peers. The
  interval is configurable using
  `Discv5Builder::with_store_interval`.

#### Gossip

L2 blocks on the OP Stack not otherwise derived from L1 are
shared over TCP in the P2P network of nodes. Unsafe L2 blocks
shared this way originate from the sequencer.

In the `kona-node`, L2 block gossip is handled through the
[libp2p Swarm][swarm]. The `GossipDriver` is the component
in the `kona-node` that manages the libp2p swarm, including
any interfacing with the swarm like dialing peers, publishing
payloads (L2 blocks), handling events from the swarm, and more.

<Info>
  The libp2p swarm must be polled via Swarm as Stream
  in order to make progress.
  Through kona's `GossipDriver`, this can be done by looping
  over and consuming events from `GossipDriver::next`.
</Info>

The `GossipDriver` provides the methods to handle events
from the [libp2p Swarm][swarm]. Events should be consumed
this way in order to use the connection gater as well as peer
store and fields on the `GossipDriver`.

The [libp2p Swarm][swarm] listens on a specified
[`Multiaddr`][multiaddr].

#### L2 Block Publishing

As mentioned in [the previous section](#gossip), L2 blocks
are published as payloads through the [libp2p Swarm][swarm],
which is done using the `GossipDriver`. The `GossipDriver` accepts an `OpExecutionPayloadEnvelope` and its
signature, then privately encodes them in the wire format documented
in the [OP Stack P2P Specs][p2p-specs].

L2 blocks published through the `GossipDriver` are published on
a "topic". The topic is used by the gossipsub protocol to publish
the message on that given topic, allowing peers to choose which
topics they wish to subscribe to.

#### L2 Block Validation

L2 blocks are validated in kona through a trait-abstracted
"block handler". Since messages in the libp2p mesh network are
snappy compressed, they need to be decompressed and then decoded
for the correct [block topic][block-topic] those messages are
published on.

After decompression, kona separates the signature from the exact encoded
envelope bytes. It authenticates those bytes before decoding the envelope
according to the corresponding block topic and validating the block contents.

<Info>
  Block validity in kona follows the [OP Stack block validation specs][validation].
</Info>

As of writing these docs, block validation follows a few rules.

* The timestamp is between 60 seconds in the past and at most 5 seconds in the future.
* The block signature authenticates the exact encoded envelope bytes.
* The block hash is valid. This is checked by computing the transaction trie root directly from
  the encoded transaction bytes and hashing the reconstructed header. Transaction decoding and
  execution remain the execution layer's responsibility.
* The contents of the payload envelope are correct for its version. Since different
  versions introduce new contents to the payload from hardforks, the
  forwards-compatible payload envelope cannot have fields with content that don't exist
  for previous versions.

### Node Identification

TODO

### P2P Actor

TODO

[validation]: https://specs.optimism.io/protocol/rollup-node-p2p.html#block-validation

[block-topic]: https://specs.optimism.io/protocol/rollup-node-p2p.html#gossip-topics

[multiaddr]: https://docs.rs/libp2p/0.56.0/libp2p/struct.Multiaddr.html

[swarm]: https://docs.rs/libp2p/latest/libp2p/struct.Swarm.html

[discv5-service]: https://docs.rs/discv5/latest/discv5/struct.Discv5.html

[driver]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/disc/src/driver.rs

[discv5]: https://github.com/ethereum/devp2p/blob/master/discv5/discv5.md

[libp2p]: https://libp2p.io/

[p2p-specs]: https://specs.optimism.io/protocol/rollup-node-p2p.html


# Sequencer Mode
Source: https://docs.optimism.io/node-operators/kona-node/design/sequencer

Understand how the kona-node sequencer actor builds L2 blocks, and the trait abstractions and programmatic configuration behind sequencer mode.

The Kona node can operate in **sequencer mode** to build and produce new L2 blocks. In this mode, the node acts as the sequencer for an OP Stack rollup, building L2 blocks on top of the current unsafe head and extending the L2 chain.

This page explains the design of sequencer mode and how to configure it programmatically through the Node SDK. To run `kona-node` as a sequencer from the command line, follow the [run a sequencer node](/node-operators/kona-node/run/sequencer) guide.

## Overview

When running in sequencer mode, the Kona node:

* **Builds L2 blocks** by collecting transactions from the mempool and constructing new blocks
* **Selects L1 origins** for new L2 blocks based on finalized L1 data
* **Manages block production timing** and ensures proper sequencing constraints
* **Integrates with conductor services** for leader election in multi-sequencer setups
* **Handles recovery scenarios** when the sequencer needs to catch up with L1

The sequencer uses the same core derivation pipeline as validator nodes but operates in reverse - instead of deriving L2 blocks from L1 data, it produces L2 blocks that will later be derivable from L1.

## Core Components

### `NodeMode`

The node's operational mode is expressed by the `NodeMode` enum, carried on the node's `EngineConfig`:

```rust theme={null}
pub enum NodeMode {
    /// Validator mode.
    Validator,
    /// Sequencer mode.
    Sequencer,
}
```

### `SequencerActor`

The core actor responsible for block production. Like every node component, it implements the `NodeActor` trait:

* Builds L2 blocks using the attributes builder
* Manages timing and L1 origin selection
* Handles admin RPC commands for sequencer control
* Coordinates with conductor services for leader election

### `SequencerConfig`

Sequencer behavior is configured through the `SequencerConfig` struct:

```rust theme={null}
pub struct SequencerConfig {
    /// Whether or not the sequencer is enabled at startup.
    pub sequencer_stopped: bool,
    /// Whether or not the sequencer is in recovery mode.
    pub sequencer_recovery_mode: bool,
    /// The Url for the conductor RPC endpoint. If Some, enables the conductor service.
    pub conductor_rpc_url: Option<Url>,
    /// The confirmation delay for the sequencer.
    pub l1_conf_delay: u64,
}
```

## Programmatic Configuration

### Using the RollupNodeBuilder

To configure a Kona node programmatically for sequencer mode, set `NodeMode::Sequencer` on the `EngineConfig` and pass a `SequencerConfig` to the `RollupNodeBuilder`:

```rust theme={null}
use kona_node_service::{NodeMode, RollupNodeBuilder, SequencerConfig};

// Configure sequencer settings
let sequencer_config = SequencerConfig {
    sequencer_stopped: false,           // Start sequencer immediately
    sequencer_recovery_mode: false,     // Normal operation mode
    conductor_rpc_url: Some(            // Optional conductor integration
        Url::parse("http://conductor:8080").unwrap()
    ),
    l1_conf_delay: 4,                   // L1 origin confirmation delay
};

// engine_config carries `mode: NodeMode::Sequencer` along with the
// L2 engine URL, JWT secret, and L1 RPC URL.
RollupNodeBuilder::new(
    rollup_config,
    l1_config_builder,
    l2_trust_rpc,
    engine_config,
    p2p_config,
    rpc_config,
)
.with_sequencer_config(sequencer_config)
.build()
.start()
.await?;
```

### Configuration Options

| Field                     | Description                                    | Default |
| ------------------------- | ---------------------------------------------- | ------- |
| `sequencer_stopped`       | Start sequencer in stopped state               | `false` |
| `sequencer_recovery_mode` | Enable recovery mode for catch-up              | `false` |
| `conductor_rpc_url`       | Conductor service endpoint for leader election | `None`  |
| `l1_conf_delay`           | Confirmation delay for L1 origin selection     | `0`     |

## Next Steps

* To run a sequencer from the command line, including the required flags and example configurations, see [run a sequencer node](/node-operators/kona-node/run/sequencer).
* For the full CLI flag catalogue, see the [Kona node CLI reference](/node-operators/kona-node/configuration).


# FAQ
Source: https://docs.optimism.io/node-operators/kona-node/faq/overview



1. [Ports](/node-operators/kona-node/faq/ports) - Detailed account of ports used by the `kona-node` for P2P communication, JSON-RPC APIs, and the Engine API for execution layer communication.


# Node Ports
Source: https://docs.optimism.io/node-operators/kona-node/faq/ports



| Service       | Default Port | Flag/Env                                             |
| ------------- | ------------ | ---------------------------------------------------- |
| RPC HTTP      | 9545         | `--port` / `KONA_NODE_RPC_PORT`                      |
| RPC WebSocket | 9545         | (same as HTTP, enabled with `--rpc.ws-enabled`)      |
| P2P TCP       | 9222         | `--p2p.listen.tcp` / `KONA_NODE_P2P_LISTEN_TCP_PORT` |
| P2P UDP       | 9223         | `--p2p.listen.udp` / `KONA_NODE_P2P_LISTEN_UDP_PORT` |

`kona-node` does not run a supervisor RPC server: the binary has no `--supervisor.*`
flag group. Its only interop flag, `--interop.dependency-set`
(`KONA_NODE_INTEROP_DEPENDENCY_SET`), takes a path to a dependency-set JSON file
rather than a port.

`--conductor.rpc` (`KONA_NODE_CONDUCTOR_RPC`) is not a listening port either. It is
the RPC endpoint URL of an external conductor service that the node dials out to,
and it has no default value. Supplying it enables the conductor integration when the
node runs in sequencer mode (`--mode sequencer`); in validator mode it has no effect.

Every port can be changed with the flag or environment variable listed
alongside it. For the full flag catalog, see the
[Kona Node CLI Reference](/node-operators/kona-node/configuration).


# Install kona-node
Source: https://docs.optimism.io/node-operators/kona-node/install/overview

Prerequisites and the three ways to obtain kona-node: Docker images, pre-built binaries, or building from source.

## Prerequisites

Before installing Kona, ensure you have the following prerequisites:

* **Rust toolchain** (MSRV: 1.82)
* **`just`** command runner
* **Docker** (optional, for containerized builds)

### Installing Rust

If you don't have Rust installed, you can install it using [rustup](https://rustup.rs/):

```bash theme={null}
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

Rustup is an easy way to update the Rust compiler, and works on all platforms.

<Tip>
  * During installation, when prompted, enter `1` for the default installation.
  * After Rust installation completes, try running `cargo version` . If it cannot
    be found, run `source $HOME/.cargo/env`. After that, running `cargo version` should return the version, for example `cargo 1.68.2`.
  * It's generally advisable to append `source $HOME/.cargo/env` to `~/.bashrc`.
</Tip>

The Minimum Supported Rust Version (MSRV) of this project is 1.82.0. If you
already have a version of Rust installed, you can check your version by running
`rustc --version`. To update your version of Rust, run rustup update.

### Installing Just

`just` is a command runner that Kona uses for build tasks. Install it with:

```bash theme={null}
cargo install just
```

## Installation Methods

There are three ways to obtain Kona:

* [Docker images](/node-operators/kona-node/run/docker#getting-the-kona-node-image): pull a published image or build one locally
* [Pre-built binaries](https://github.com/ethereum-optimism/optimism/releases): download the latest release from GitHub, then follow the [binary guide](/node-operators/kona-node/run/binary)
* [Building from source](/node-operators/kona-node/install/source)

<Note>
  If you have Docker installed, we recommend using the [Docker recipe](/node-operators/kona-node/run/docker) configuration
  that will have kona-node, op-reth, Prometheus and Grafana running and syncing with just one command.
</Note>


# Building from Source
Source: https://docs.optimism.io/node-operators/kona-node/install/source



<Note>
  Building from source requires that the Rust toolchain is installed, as well as the `just` command runner.

  Visit the [Prerequisites](/node-operators/kona-node/install/overview) for details on installing Rust and `just`.
</Note>

First clone the repository:

```bash theme={null}
git clone https://github.com/ethereum-optimism/optimism.git
cd rust/kona
```

Then, install the `kona-node` binary into your PATH directly via:

```bash theme={null}
cargo install --locked --path bin/node --bin kona-node
```

The binary will now be accessible as `kona-node` via the command line,
and exist under your default .cargo/bin folder.

Alternatively, you can build yourself with:

```bash theme={null}
cargo build --release --bin kona-node
```

This will place the reth binary under `./target/release/kona-node`, and
you can copy it to your directory of preference after that.

## Update Kona

You can update the `kona-node` to a specific version by running the
commands below.

`${VERSION}` is the version you wish to build in the format `vX.X.X`.

```bash theme={null}
git fetch
git checkout ${VERSION}
cargo build --release --bin kona-node
```

## Troubleshooting

### Command is not found

Reth will be installed to `CARGO_HOME` or `$HOME/.cargo`.
This directory needs to be on your `PATH` before you can run the
`kona-node` binary.

See ["Configuring the PATH environment variable"][path] for more information.

[path]: https://www.rust-lang.org/tools/install

### Compilation error

Make sure you are running the latest version of Rust.
If you have installed Rust using rustup, simply run `rustup update`.

If you can't install the latest version of Rust you can instead compile
using the Minimum Supported Rust Version (MSRV) which is listed under
the `rust-version` key in kona's [Cargo.toml](https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/Cargo.toml).

If compilation fails with `(signal: 9, SIGKILL: kill)`, this could mean
your machine ran out of memory during compilation. If you are on Docker,
consider increasing the memory of the container, or use a [pre-built
binary](https://github.com/ethereum-optimism/optimism/releases).

If compilation fails with `error: linking with cc failed: exit code: 1`,
try running `cargo clean`.

## Next Steps

* Read the [design docs](/node-operators/kona-node/design/intro) to understand kona-node's architecture
* Check out the [Binaries](/node-operators/kona-node/run/binary) documentation
* Explore the [examples](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/examples)


# Monitoring
Source: https://docs.optimism.io/node-operators/kona-node/monitoring

Set up logging, Prometheus metrics, and Grafana dashboards for kona-node.

This guide covers observability for a running `kona-node`: adjusting
log verbosity, filtering log targets, and collecting Prometheus
metrics into Grafana dashboards.

## Logging

`kona-node` provides a `-v` (or `--v`) flag as a way to set
the "verbosity" level for logs. By default, the verbosity level
is set to `3`, which is the INFO level. The level ranges from `0`
being no logs to `5` which includes trace logs. Log levels are
listed below, with each level including the one below it.

* `5`: `TRACE` - very verbose logs that provide a detailed trace
* `4`: `DEBUG` - logs meant to print debugging information
* `3`: `INFO` - informational logs
* `2`: `WARN` - includes warning and error logs
* `1`: `ERROR` - only error logs are shown
* `0`: No logs

The default verbosity level is `-vvv` which is the `3` or `INFO`
level. To set the `kona-node` to print `DEBUG` logs or level `4`,
run the node like so: `kona-node node -vvvv`.

### Filtering Log Targets

By default, the `kona-node` initializes its tracing (logging)
using the default environment variable filter [provided by the
tracing\_subscriber crate][tracing-env]. This uses the value in
the `RUST_LOG` environment variable to set the tracing level
for specific targets. Effectively, `RUST_LOG` allows you to
bypass the default log level for the whole node or specific
log targets. For example, by prepending `RUST_LOG=engine=debug`
to the `kona-node` command (or setting that as an environment
variable), only `INFO` logs will be displayed except for the
`engine` log target which will also print `DEBUG` logs.

This comes in handy say for when we would like to debug Kona's
P2P stack, we could prepend `RUST_LOG=discv5=debug,libp2p=debug`
to view debug logs from only `discv5` and `libp2p` targets.

## Metrics

The `kona-node` can serve Prometheus metrics, which are disabled
by default. To turn them on, pass the `--metrics.enabled` cli flag.

Unless otherwise specified with the `--metrics.port` flag, metrics
are exposed on port `9090`.

To grab a snapshot of the metrics, you can visit `0.0.0.0:9090`
or `curl` the url.

```
curl 0.0.0.0:9090
```

The output should be raw text mapping metrics with their values.

Remember, this is just a snapshot of the metrics at that point
in time. To record and visualize the metrics, we'll use
[Grafana and Prometheus](#grafana-and-prometheus).

## Grafana and Prometheus

Prometheus is a simple service that scrapes metrics at a predefined
interval. Grafana then uses Prometheus as a "Data Source" to
visualize the collected metrics.

The Reth book provides a great overview to setting up [Prometheus
and Grafana][setup]. Visit the Reth docs to follow along.

The `kona-node` comes shipped with a default Grafana dashboard
for the `kona-node`. To import the dashboard to grafana, click
the `+` icon > `Import Dashboard` > paste the contents of [kona's
dashboard][dashboard] in the textbox > `Load`.

[tracing-env]: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#method.from_default_env

[setup]: https://reth.rs/run/monitoring#prometheus--grafana

[dashboard]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/docker/recipes/kona-node/grafana/dashboards/overview.json


# System Requirements
Source: https://docs.optimism.io/node-operators/kona-node/requirements



`kona-node` is an L2 consensus client, so it stores almost nothing on disk!

<Note>
  Anything stored on disk is configurable, and can be disabled.
</Note>

As a rollup node, it always sends L2 blocks over to the execution client
(`op-reth` or `op-geth`) for execution. That way, chain state is entirely
handled by the execution client. In this way, the `kona-node` is incredibly
lightweight and can be run on a wide range of hardware.

That said, a stable and dependable internet connection is critical for the
peer-to-peer (P2P) part of the node. The `kona-node` relies on P2P communication
to sync the unsafe chain. If the connection is unstable, the node may
struggle to keep up, and could be banned by its peers for being too slow.


# Admin RPC Methods
Source: https://docs.optimism.io/node-operators/kona-node/rpc/admin



The `admin` api provides methods for controlling and monitoring Kona's consensus node operations.

## `admin_postUnsafePayload`

Posts an unsafe payload to the network.

| Client | Method invocation                                            |
| ------ | ------------------------------------------------------------ |
| RPC    | `{"method": "admin_postUnsafePayload", "params": [payload]}` |

### Parameters

* `payload` (`OpExecutionPayloadEnvelope`): The execution payload envelope to post

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_postUnsafePayload","params":[{...payload...}]}
{"jsonrpc":"2.0","id":1,"result":null}
```

## `admin_sequencerActive`

Returns whether the sequencer is currently active.

| Client | Method invocation                     |
| ------ | ------------------------------------- |
| RPC    | `{"method": "admin_sequencerActive"}` |

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_sequencerActive","params":[]}
{"jsonrpc":"2.0","id":1,"result":true}
```

**Note**: This method will return a "Method not found" error if the node is running in validator mode (sequencer not enabled).

## `admin_startSequencer`

Starts the sequencer.

| Client | Method invocation                    |
| ------ | ------------------------------------ |
| RPC    | `{"method": "admin_startSequencer"}` |

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_startSequencer","params":[]}
{"jsonrpc":"2.0","id":1,"result":null}
```

**Note**: This method will return a "Method not found" error if the node is running in validator mode (sequencer not enabled).

## `admin_stopSequencer`

Stops the sequencer and returns the hash of the last processed block.

| Client | Method invocation                   |
| ------ | ----------------------------------- |
| RPC    | `{"method": "admin_stopSequencer"}` |

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_stopSequencer","params":[]}
{"jsonrpc":"2.0","id":1,"result":"0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}
```

**Note**: This method will return a "Method not found" error if the node is running in validator mode (sequencer not enabled).

## `admin_conductorEnabled`

Returns whether the conductor is enabled.

| Client | Method invocation                      |
| ------ | -------------------------------------- |
| RPC    | `{"method": "admin_conductorEnabled"}` |

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_conductorEnabled","params":[]}
{"jsonrpc":"2.0","id":1,"result":false}
```

**Note**: This method will return a "Method not found" error if the node is running in validator mode (sequencer not enabled).

## `admin_setRecoverMode`

Sets the recovery mode for the sequencer.

| Client | Method invocation                                      |
| ------ | ------------------------------------------------------ |
| RPC    | `{"method": "admin_setRecoverMode", "params": [mode]}` |

### Parameters

* `mode` (`bool`): Whether to enable recovery mode (true) or disable it (false)

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_setRecoverMode","params":[true]}
{"jsonrpc":"2.0","id":1,"result":null}
```

**Note**: This method will return a "Method not found" error if the node is running in validator mode (sequencer not enabled).

## `admin_overrideLeader`

Overrides the leader in the conductor.

| Client | Method invocation                    |
| ------ | ------------------------------------ |
| RPC    | `{"method": "admin_overrideLeader"}` |

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"admin_overrideLeader","params":[]}
{"jsonrpc":"2.0","id":1,"result":null}
```

**Note**: This method will return a "Method not found" error if the node is running in validator mode (sequencer not enabled).


# JSON-RPC
Source: https://docs.optimism.io/node-operators/kona-node/rpc/overview



The `kona-node` supports JSON-RPC for interacting with the node.

By default, `kona-node` exposes an HTTP JSON-RPC server. A WebSocket JSON-RPC
endpoint is also available and can be enabled with the `--rpc.ws-enabled` flag
or the `KONA_NODE_RPC_WS_ENABLED` environment variable. IPC transport is not
supported.

### Namespaces

JSON-RPC methods are grouped into namespaces, which are listed below:

| Namespace                                        | Description                                              | Sensitive |
| ------------------------------------------------ | -------------------------------------------------------- | --------- |
| [`p2p`](/node-operators/kona-node/rpc/p2p)       | The `p2p` API allows you to configure the p2p stack.     | Maybe     |
| [`rollup`](/node-operators/kona-node/rpc/rollup) | The `rollup` API provides OP Stack specific rpc methods. | No        |
| [`admin`](/node-operators/kona-node/rpc/admin)   | The `admin` API allows you to configure your node.       | **Yes**   |

### Interacting with the RPC

Kona enables these RPC methods by default.

You can interact with the RPC using any JSON-RPC client, such as `curl`, `httpie`, or a custom client in your preferred programming language.


# P2P RPC Methods
Source: https://docs.optimism.io/node-operators/kona-node/rpc/p2p



The `p2p` api provides methods for interacting with Kona's P2P stack.

## Peer Information Methods

### `opp2p_self`

Returns information about the local node in the form of `PeerInfo`.

| Client | Method invocation          |
| ------ | -------------------------- |
| RPC    | `{"method": "opp2p_self"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_self","params":[]}
{"jsonrpc":"2.0","id":1,"result":{"peerID":"16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x","nodeID":"0x311d8222ffc44e9c86f403d57f454bd823e7dc9d3c8e97171ddd862910352f31","userAgent":"kona","protocolVersion":"","ENR":"enr:-Jm4QBAdUpUqrpTj6yQor5mwif6RRmY11dlj-Um3TqKmJiYha4SUNqdJr2eM3pRsFVCwVikYcBk__5JVTwngUeimKxcCgmlkgnY0gmlwhC36_pOHb3BzdGFja4Xc76gFAIlzZWNwMjU2azGhA2WTa6OqvnWbRmoeuhRRu-BTPgP8y4_MY6snTsNW0gHBg3RjcIIj5oN1ZHCCn7U","addresses":["/ip4/127.0.0.1/tcp/9190/p2p/16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x","/ip4/172.18.0.9/tcp/9190/p2p/16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"],"protocols":["/ipfs/id/push/1.0.0","/meshsub/1.1.0","/ipfs/ping/1.0.0","/meshsub/1.2.0","/ipfs/id/1.0.0","/opstack/req/payload_by_number/2151908/0/","/meshsub/1.0.0","/floodsub/1.0.0"],"connectedness":1,"direction":1,"protected":false,"chainID":11155420,"latency":0,"gossipBlocks":true,"scores":{"gossip":{"total":0.0,"blocks":{"timeInMesh":0.0,"firstMessageDeliveries":0.0,"meshMessageDeliveries":0.0,"invalidMessageDeliveries":0.0},"IPColocationFactor":0.0,"behavioralPenalty":0.0},"reqResp":{"validResponses":0.0,"errorResponses":0.0,"rejectedPayloads":0.0}}}}
```

### `opp2p_peerCount`

Returns the count of connected peers for both discovery and gossip networks.

| Client | Method invocation               |
| ------ | ------------------------------- |
| RPC    | `{"method": "opp2p_peerCount"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_peerCount","params":[]}
{"jsonrpc":"2.0","id":1,"result":{"connectedDiscovery":15,"connectedGossip":12}}
```

### `opp2p_peers`

Returns information about peers. If `connected` parameter is true, only returns connected peers.

| Client | Method invocation                                  |
| ------ | -------------------------------------------------- |
| RPC    | `{"method": "opp2p_peers", "params": [connected]}` |

#### Parameters

* `connected` (boolean): If true, only returns connected peers

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_peers","params":[true]}
{"jsonrpc":"2.0","id":1,"result":{"totalConnected":2,"peers":{"16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x":{"peerID":"16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x","nodeID":"0x311d8222ffc44e9c86f403d57f454bd823e7dc9d3c8e97171ddd862910352f31","userAgent":"kona","protocolVersion":"","addresses":["/ip4/127.0.0.1/tcp/9190"],"protocols":["/ipfs/ping/1.0.0","/meshsub/1.1.0"],"connectedness":1,"direction":2,"protected":false,"chainID":11155420,"latency":50000000,"gossipBlocks":true,"scores":{"gossip":{"total":1.5,"blocks":{"timeInMesh":100.0,"firstMessageDeliveries":10.0,"meshMessageDeliveries":5.0,"invalidMessageDeliveries":0.0},"IPColocationFactor":0.0,"behavioralPenalty":0.0},"reqResp":{"validResponses":25.0,"errorResponses":1.0,"rejectedPayloads":0.0}}}},"bannedPeers":[],"bannedIPS":[],"bannedSubnets":[]}}
```

### `opp2p_peerStats`

Returns statistical information about peers including connection counts and topic subscriptions.

| Client | Method invocation               |
| ------ | ------------------------------- |
| RPC    | `{"method": "opp2p_peerStats"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_peerStats","params":[]}
{"jsonrpc":"2.0","id":1,"result":{"connected":12,"table":50,"blocksTopic":8,"blocksTopicV2":10,"blocksTopicV3":5,"blocksTopicV4":2,"banned":3,"known":75}}
```

### `opp2p_discoveryTable`

Returns the discovery table entries as a list of ENR strings.

| Client | Method invocation                    |
| ------ | ------------------------------------ |
| RPC    | `{"method": "opp2p_discoveryTable"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_discoveryTable","params":[]}
{"jsonrpc":"2.0","id":1,"result":["enr:-Jm4QBAdUpUqrpTj6yQor5mwif6RRmY11dlj-Um3TqKmJiYha4SUNqdJr2eM3pRsFVCwVikYcBk__5JVTwngUeimKxcCgmlkgnY0gmlwhC36_pOHb3BzdGFja4Xc76gFAIlzZWNwMjU2azGhA2WTa6OqvnWbRmoeuhRRu-BTPgP8y4_MY6snTsNW0gHBg3RjcIIj5oN1ZHCCn7U","enr:-Km4QBqBrKNq7F5L1dSrWW8Y1k8k4V2L2nTsNtGuKPpPwp3L_rBVMaQCQpnc2sBB-c2yV_n4qgM2_2yfcNjVXr4OFgCgmlkgnY0gmlwhH8AAAGHb3BzdGFja4OFAoAE"]}
```

## Peer Blocking Methods

### `opp2p_blockPeer`

Blocks a specific peer by peer ID, preventing any connections to or from that peer.

| Client | Method invocation                                   |
| ------ | --------------------------------------------------- |
| RPC    | `{"method": "opp2p_blockPeer", "params": [peerID]}` |

#### Parameters

* `peerID` (string): The peer ID to block

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_blockPeer","params":["16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_unblockPeer`

Unblocks a previously blocked peer by peer ID.

| Client | Method invocation                                     |
| ------ | ----------------------------------------------------- |
| RPC    | `{"method": "opp2p_unblockPeer", "params": [peerID]}` |

#### Parameters

* `peerID` (string): The peer ID to unblock

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_unblockPeer","params":["16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_listBlockedPeers`

Returns a list of all blocked peer IDs.

| Client | Method invocation                      |
| ------ | -------------------------------------- |
| RPC    | `{"method": "opp2p_listBlockedPeers"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_listBlockedPeers","params":[]}
{"jsonrpc":"2.0","id":1,"result":["16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x","16Uiu2HAm7Th3s3C1VHmKrYzA9nPzV4b3vqL8z1x8WZzGk2t9DjRK"]}
```

## Address Blocking Methods

### `opp2p_blockAddr`

Blocks connections from a specific IP address.

| Client | Method invocation                                    |
| ------ | ---------------------------------------------------- |
| RPC    | `{"method": "opp2p_blockAddr", "params": [address]}` |

#### Parameters

* `address` (string): The IP address to block (IPv4 or IPv6)

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_blockAddr","params":["192.168.1.100"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_unblockAddr`

Unblocks a previously blocked IP address.

| Client | Method invocation                                      |
| ------ | ------------------------------------------------------ |
| RPC    | `{"method": "opp2p_unblockAddr", "params": [address]}` |

#### Parameters

* `address` (string): The IP address to unblock (IPv4 or IPv6)

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_unblockAddr","params":["192.168.1.100"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_listBlockedAddrs`

Returns a list of all blocked IP addresses.

| Client | Method invocation                      |
| ------ | -------------------------------------- |
| RPC    | `{"method": "opp2p_listBlockedAddrs"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_listBlockedAddrs","params":[]}
{"jsonrpc":"2.0","id":1,"result":["192.168.1.100","10.0.0.50","2001:db8::1"]}
```

## Subnet Blocking Methods

### `opp2p_blockSubnet`

Blocks connections from an entire IP subnet using CIDR notation.

| Client | Method invocation                                     |
| ------ | ----------------------------------------------------- |
| RPC    | `{"method": "opp2p_blockSubnet", "params": [subnet]}` |

#### Parameters

* `subnet` (string): The subnet to block in CIDR notation (e.g., "192.168.1.0/24")

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_blockSubnet","params":["192.168.1.0/24"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_unblockSubnet`

Unblocks a previously blocked IP subnet.

| Client | Method invocation                                       |
| ------ | ------------------------------------------------------- |
| RPC    | `{"method": "opp2p_unblockSubnet", "params": [subnet]}` |

#### Parameters

* `subnet` (string): The subnet to unblock in CIDR notation

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_unblockSubnet","params":["192.168.1.0/24"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_listBlockedSubnets`

Returns a list of all blocked IP subnets.

| Client | Method invocation                        |
| ------ | ---------------------------------------- |
| RPC    | `{"method": "opp2p_listBlockedSubnets"}` |

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_listBlockedSubnets","params":[]}
{"jsonrpc":"2.0","id":1,"result":["192.168.1.0/24","10.0.0.0/16","2001:db8::/32"]}
```

## Peer Protection Methods

### `opp2p_protectPeer`

Protects a peer from being disconnected due to connection limits or other automatic pruning mechanisms.

| Client | Method invocation                                     |
| ------ | ----------------------------------------------------- |
| RPC    | `{"method": "opp2p_protectPeer", "params": [peerID]}` |

#### Parameters

* `peerID` (string): The peer ID to protect

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_protectPeer","params":["16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_unprotectPeer`

Removes protection from a peer, allowing it to be disconnected by automatic pruning mechanisms.

| Client | Method invocation                                       |
| ------ | ------------------------------------------------------- |
| RPC    | `{"method": "opp2p_unprotectPeer", "params": [peerID]}` |

#### Parameters

* `peerID` (string): The peer ID to unprotect

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_unprotectPeer","params":["16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

## Connection Management Methods

### `opp2p_connectPeer`

Attempts to establish a connection to a specific peer using a multiaddress.

| Client | Method invocation                                        |
| ------ | -------------------------------------------------------- |
| RPC    | `{"method": "opp2p_connectPeer", "params": [multiaddr]}` |

#### Parameters

* `multiaddr` (string): The multiaddress of the peer to connect to

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_connectPeer","params":["/ip4/127.0.0.1/tcp/9190/p2p/16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"]}
{"jsonrpc":"2.0","id":1,"result":null}
```

### `opp2p_disconnectPeer`

Disconnects from a specific peer by peer ID.

| Client | Method invocation                                        |
| ------ | -------------------------------------------------------- |
| RPC    | `{"method": "opp2p_disconnectPeer", "params": [peerID]}` |

#### Parameters

* `peerID` (string): The peer ID to disconnect from

#### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"opp2p_disconnectPeer","params":["16Uiu2HAmKVVub7edwZ3RKDnqMpZVsusYW9TKRgbwpH54nvDWLE4x"]}
{"jsonrpc":"2.0","id":1,"result":null}
```


# Rollup RPC Methods
Source: https://docs.optimism.io/node-operators/kona-node/rpc/rollup



The `optimism` API provides methods for interacting with Kona's rollup state and configuration.

## `optimism_outputAtBlock`

Returns the output root at a specific block number, including the L2 block reference, withdrawal storage root, state root, and sync status.

| Client | Method invocation                                               |
| ------ | --------------------------------------------------------------- |
| RPC    | `{"method": "optimism_outputAtBlock", "params": [blockNumber]}` |

### Parameters

* `blockNumber` (`BlockNumberOrTag`): The block number to get the output for. Can be a number, "latest", "earliest", "pending", "safe", or "finalized".

### Returns

`OutputResponse` - An object containing:

* `version` (`string`): The output version hash
* `outputRoot` (`string`): The output root hash
* `blockRef` (`L2BlockInfo`): Reference to the L2 block
* `withdrawalStorageRoot` (`string`): The withdrawal storage root
* `stateRoot` (`string`): The state root
* `syncStatus` (`SyncStatus`): The current sync status of the node

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"optimism_outputAtBlock","params":["latest"]}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "version": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "outputRoot": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "blockRef": {
      "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
      "number": 12345,
      "parentHash": "0x9876543210fedcba9876543210fedcba9876543210fedcba9876543210fedcba",
      "timestamp": 1699123456,
      "l1Origin": {
        "hash": "0xfedcba0987654321fedcba0987654321fedcba0987654321fedcba0987654321",
        "number": 18123456
      },
      "sequenceNumber": 42
    },
    "withdrawalStorageRoot": "0x567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234",
    "stateRoot": "0xcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
    "syncStatus": {
      "current_l1": {
        "hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
        "number": 18123456
      },
      "current_l1_finalized": {
        "hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
        "number": 18123400
      },
      "head_l1": {
        "hash": "0x3333333333333333333333333333333333333333333333333333333333333333",
        "number": 18123460
      },
      "safe_l1": {
        "hash": "0x4444444444444444444444444444444444444444444444444444444444444444",
        "number": 18123450
      },
      "finalized_l1": {
        "hash": "0x5555555555555555555555555555555555555555555555555555555555555555",
        "number": 18123400
      },
      "unsafe_l2": {
        "hash": "0x6666666666666666666666666666666666666666666666666666666666666666",
        "number": 12350,
        "parentHash": "0x7777777777777777777777777777777777777777777777777777777777777777",
        "timestamp": 1699123500,
        "l1Origin": {
          "hash": "0x8888888888888888888888888888888888888888888888888888888888888888",
          "number": 18123460
        },
        "sequenceNumber": 47
      },
      "safe_l2": {
        "hash": "0x9999999999999999999999999999999999999999999999999999999999999999",
        "number": 12345,
        "parentHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "timestamp": 1699123456,
        "l1Origin": {
          "hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
          "number": 18123456
        },
        "sequenceNumber": 42
      },
      "finalized_l2": {
        "hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        "number": 12340,
        "parentHash": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
        "timestamp": 1699123400,
        "l1Origin": {
          "hash": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
          "number": 18123400
        },
        "sequenceNumber": 37
      },
      "cross_unsafe_l2": {
        "hash": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
        "number": 12350,
        "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000001",
        "timestamp": 1699123500,
        "l1Origin": {
          "hash": "0x0000000000000000000000000000000000000000000000000000000000000002",
          "number": 18123460
        },
        "sequenceNumber": 47
      },
      "local_safe_l2": {
        "hash": "0x0000000000000000000000000000000000000000000000000000000000000003",
        "number": 12345,
        "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000004",
        "timestamp": 1699123456,
        "l1Origin": {
          "hash": "0x0000000000000000000000000000000000000000000000000000000000000005",
          "number": 18123456
        },
        "sequenceNumber": 42
      }
    }
  }
}
```

## `optimism_syncStatus`

Returns the current synchronization status of the rollup node, including information about L1 and L2 block states.

| Client | Method invocation                                 |
| ------ | ------------------------------------------------- |
| RPC    | `{"method": "optimism_syncStatus", "params": []}` |

### Returns

`SyncStatus` - An object containing detailed sync information:

* `current_l1` (`BlockInfo`): The current L1 block that derivation is idled at
* `current_l1_finalized` (`BlockInfo`): The current L1 finalized block (legacy/deprecated)
* `head_l1` (`BlockInfo`): The L1 head block reference
* `safe_l1` (`BlockInfo`): The L1 safe head block reference
* `finalized_l1` (`BlockInfo`): The finalized L1 block reference
* `unsafe_l2` (`L2BlockInfo`): The unsafe L2 block reference (absolute tip)
* `safe_l2` (`L2BlockInfo`): The safe L2 block reference (derived from L1)
* `finalized_l2` (`L2BlockInfo`): The finalized L2 block reference
* `cross_unsafe_l2` (`L2BlockInfo`): Cross-unsafe L2 block with verified cross-L2 dependencies
* `local_safe_l2` (`L2BlockInfo`): Local safe L2 block derived from L1, not yet cross-verified

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"optimism_syncStatus","params":[]}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "current_l1": {
      "hash": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "number": 18123456
    },
    "current_l1_finalized": {
      "hash": "0x2222222222222222222222222222222222222222222222222222222222222222",
      "number": 18123400
    },
    "head_l1": {
      "hash": "0x3333333333333333333333333333333333333333333333333333333333333333",
      "number": 18123460
    },
    "safe_l1": {
      "hash": "0x4444444444444444444444444444444444444444444444444444444444444444",
      "number": 18123450
    },
    "finalized_l1": {
      "hash": "0x5555555555555555555555555555555555555555555555555555555555555555",
      "number": 18123400
    },
    "unsafe_l2": {
      "hash": "0x6666666666666666666666666666666666666666666666666666666666666666",
      "number": 12350,
      "parentHash": "0x7777777777777777777777777777777777777777777777777777777777777777",
      "timestamp": 1699123500,
      "l1Origin": {
        "hash": "0x8888888888888888888888888888888888888888888888888888888888888888",
        "number": 18123460
      },
      "sequenceNumber": 47
    },
    "safe_l2": {
      "hash": "0x9999999999999999999999999999999999999999999999999999999999999999",
      "number": 12345,
      "parentHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "timestamp": 1699123456,
      "l1Origin": {
        "hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
        "number": 18123456
      },
      "sequenceNumber": 42
    },
    "finalized_l2": {
      "hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
      "number": 12340,
      "parentHash": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
      "timestamp": 1699123400,
      "l1Origin": {
        "hash": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "number": 18123400
      },
      "sequenceNumber": 37
    },
    "cross_unsafe_l2": {
      "hash": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
      "number": 12350,
      "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000001",
      "timestamp": 1699123500,
      "l1Origin": {
        "hash": "0x0000000000000000000000000000000000000000000000000000000000000002",
        "number": 18123460
      },
      "sequenceNumber": 47
    },
    "local_safe_l2": {
      "hash": "0x0000000000000000000000000000000000000000000000000000000000000003",
      "number": 12345,
      "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000004",
      "timestamp": 1699123456,
      "l1Origin": {
        "hash": "0x0000000000000000000000000000000000000000000000000000000000000005",
        "number": 18123456
      },
      "sequenceNumber": 42
    }
  }
}
```

## `optimism_rollupConfig`

Returns the rollup configuration parameters that define the rollup chain's behavior and properties.

| Client | Method invocation                                   |
| ------ | --------------------------------------------------- |
| RPC    | `{"method": "optimism_rollupConfig", "params": []}` |

### Returns

`RollupConfig` - An object containing the complete rollup configuration:

* `genesis` (`ChainGenesis`): The genesis state of the rollup
* `blockTime` (`number`): The block time of the L2 in seconds
* `maxSequencerDrift` (`number`): Maximum sequencer drift in seconds
* `seqWindowSize` (`number`): The sequencer window size
* `channelTimeout` (`number`): Number of L1 blocks between channel open/close
* `graniteChannelTimeout` (`number`): Channel timeout after Granite hardfork
* `l1ChainId` (`number`): The L1 chain ID
* `l2ChainId` (`number`): The L2 chain ID
* `batchInboxAddress` (`string`): L1 address where batches are sent
* `depositContractAddress` (`string`): L1 address for deposits
* `l1SystemConfigAddress` (`string`): L1 address for system config
* `protocolVersionsAddress` (`string`): L1 address for protocol versions
* Additional configuration fields for hardforks, fees, and interoperability

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"optimism_rollupConfig","params":[]}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "genesis": {
      "l1": {
        "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
        "number": 18000000
      },
      "l2": {
        "hash": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
        "number": 0,
        "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": 1699000000,
        "l1Origin": {
          "hash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
          "number": 18000000
        },
        "sequenceNumber": 0
      },
      "l2Time": 1699000000,
      "systemConfig": {
        "batcherAddr": "0x1234567890123456789012345678901234567890",
        "overhead": "0x00000000000000000000000000000000000000000000000000000000000000bc",
        "scalar": "0x00000000000000000000000000000000000000000000000000000000000f4240",
        "gasLimit": 30000000
      }
    },
    "blockTime": 2,
    "maxSequencerDrift": 600,
    "seqWindowSize": 3600,
    "channelTimeout": 300,
    "graniteChannelTimeout": 50,
    "l1ChainId": 1,
    "l2ChainId": 10,
    "batchInboxAddress": "0xff00000000000000000000000000000000000010",
    "depositContractAddress": "0xbEb5Fc579115071764c7423A4f12eDde41f106Ed",
    "l1SystemConfigAddress": "0x229047fed2591dbec1eF1118d64F7aF3dB9EB290",
    "protocolVersionsAddress": "0x8062AbC286f5e7D9428a0Ccb9AbD71e50d93b935",
    "superchainConfigAddress": "0x95703e0982140D16f8ebA6d158FccEde42f04a4C",
    "blobs_data": 1710374400,
    "interopMessageExpiryWindow": 3600,
    "chainOpConfig": {
      "canyon_denominator": 250,
      "canyon_elasticity": 6
    }
  }
}
```

## `optimism_version`

Returns the software version of the Kona rollup node.

| Client | Method invocation                              |
| ------ | ---------------------------------------------- |
| RPC    | `{"method": "optimism_version", "params": []}` |

### Returns

`string` - The version string of the Kona software (e.g., "0.1.0")

### Example

```js theme={null}
// > {"jsonrpc":"2.0","id":1,"method":"optimism_version","params":[]}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0.1.0"
}
```

## Deprecated Methods

### `optimism_safeHeadAtL1Block`

This RPC endpoint is **not supported** in Kona. It was used to track the safe head for every L1 block, but this is no longer necessary post-interop. Calling this method will return a "Method not found" error.

| Client | Method invocation                                                   |
| ------ | ------------------------------------------------------------------- |
| RPC    | `{"method": "optimism_safeHeadAtL1Block", "params": [blockNumber]}` |

### Returns

This method returns an error with code `-32601` (Method not found).


# Run Kona Node as a Binary
Source: https://docs.optimism.io/node-operators/kona-node/run/binary

Run the kona-node binary against an op-reth execution client, from starting both clients to watching the node sync.

<Note>
  If you don't have a `kona-node` binary yet, download the latest pre-built
  binary from the [GitHub releases page](https://github.com/ethereum-optimism/optimism/releases),
  or head over to the [Installation](/node-operators/kona-node/install/overview)
  guide to build one yourself.
</Note>

`kona-node` is an L2 consensus client (also called a "rollup node").
This means that the node is a *consensus*-layer client, which needs
a corresponding execution-layer client in order to sync and follow
the L2 chain. The OP Stack uses a minimal diff approach to L1
execution clients, and [`op-reth`][op-reth] is the primary L2
execution layer client.

This section will illustrate running the `kona-node` with an instance
of [`op-reth`][op-reth].

Out of the box, the `kona-node` can be used for any `OP Stack` chain
that is part of the [`superchain-registry`][scr]. In order to use an
out-of-band `OP Stack` chain, for example a new devnet, you'll need
to specify the rollup config using the custom `--l2-config-file`
cli flag. See [rollup configuration loading](/node-operators/kona-node/configuration#rollup-configuration-loading)
for details.

<Info>
  This tutorial walks through running the `kona-node` as
  a binary. To use docker, head over to the
  [Docker Guide](/node-operators/kona-node/run/docker) which uses a `docker-compose`
  setup provided by `kona`. The `docker-compose` setup
  automatically bootstraps the `kona-node` with `op-reth`,
  provisioning grafana dashboards and a default Prometheus
  configuration. It is encouraged to follow the
  [Docker Guide](/node-operators/kona-node/run/docker) to avoid misconfigurations.
</Info>

The `kona-node` requires a few CLI flags.

* `--l1-eth-rpc <L1_ETH_RPC>`
  URL of the L1 execution client RPC API.
* `--l1-beacon <L1_BEACON>`
  URL of the L1 beacon API.
* `--l2-engine-rpc <L2_ENGINE_RPC>`
  URL of the engine API endpoint of an L2 execution client.

The L2 engine RPC points to the execution layer client's engine API,
[`op-reth`][op-reth].

An L1 beacon endpoint and rpc endpoint are also required to
fetch the L1 chain data that the L2 chain is derived from.

First, start an instance of [`op-reth`][op-reth]. The
[`op-reth` docs][op-reth-docs] provide very detailed instructions
for running `op-reth` nodes for OP Stack chains (L2). For this
demo, we'll use `base`, but any other OP Stack chain will do.

```
op-reth node \
    --chain base \
    --rollup.sequencer-http https://mainnet-sequencer.base.org \
    --http \
    --ws \
    --authrpc.port 9551 \
    --authrpc.jwtsecret /path/to/jwt.hex
```

Kona has a `generate-jwt` justfile target that can be used to
create the `jwt.hex` file. Run `just generate-jwt`.

<Info>
  The JWT token file path passed into `--authrpc.jwtsecret`
  **MUST** be the same as the one passed into the `kona-node`.

  This JWT token is how the `op-reth` client authenticates
  requests made by the `kona-node` to the engine rpc.

  By default, the `kona-node` will attempt to read a JWT token
  from a `jwt.hex` file in the local directory. If it cannot
  find one, it will create a JWT token in a new `jwt.hex` file.

  To specify the path to the file that contains the JWT token,
  pass the file path into the `--l2.jwt-secret` CLI flag or
  use the `KONA_NODE_L2_ENGINE_AUTH` environment variable.
</Info>

Then, run the `kona-node` using Base's chain id - `8453`.

```
kona-node node \
    --chain 8453 \
    --l1-eth-rpc <L1_RPC_URL> \
    --l1-beacon <L1_BEACON_URL> \
    --l2-engine-rpc http://127.0.0.1:9551 \
```

That's it! Your node should connect to P2P and start syncing
quickly.

<Note>
  By default, `kona-node` trusts its RPC providers and doesn't perform
  additional verification, which is suitable for local nodes. When
  pointing the node at public RPC endpoints, follow
  [configure RPC trust](/node-operators/kona-node/run/rpc-trust) to enable
  block hash verification.
</Note>

#### What to Expect

Now, when the `kona-node` starts up, it should immediately spin up
the P2P stack. It will begin discovering valid peers on the network
with the same chain id (base - `8453`) and OP Stack enr key "opstack".
When valid peers are discovered, they are sent to the libp2p swarm
which attempts to connect to them and listen for block gossip.

Depending on the chain, and the P2P network topology, it may take
longer for the `kona-node` to establish a strong set of peers and
begin receiving block gossip. For larger, more mature chains like
OP Mainnet and Base, peer discovery should happen quickly via the
chain's P2P bootnodes.

Once the first unsafe L2 payload attributes (block) is received
from peers in the libp2p swarm, it is sent off to the `kona-node`'s
engine actor which will kick off execution layer sync on the
`op-reth` execution client. When this happens, the `op-reth` logs
will start to show that it is fetching past L2 blocks to sync the
chain to tip.

Once EL sync is finished, `kona-node`'s derivation actor will
kick off the derivation pipeline and begin deriving the L2 chain.
All the while, the P2P stack is separately receiving unsafe L2
blocks from the chain's sequencer, and sending them off to the
engine actor to insert into the chain.

#### Next Steps

* The node's default ports, default behavior, and every available CLI
  flag - including the sequencer and interop flag sets - are
  catalogued in the [Kona node CLI reference](/node-operators/kona-node/configuration).
* To adjust log verbosity or set up metrics dashboards, see
  [Monitoring](/node-operators/kona-node/monitoring).
* To learn more about running a `kona-node` using docker, check
  out the [docker guide](/node-operators/kona-node/run/docker).

[scr]: https://github.com/ethereum-optimism/superchain-registry/tree/main

[op-reth-docs]: https://reth.rs/run/opstack

[op-reth]: https://github.com/paradigmxyz/reth/blob/main/crates/optimism/bin/src/main.rs

[buildx]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/docker

[packages]: https://github.com/orgs/op-rs/packages?repo_name=kona

[pdocs]: https://github.com/ethereum-optimism/optimism/pkgs/container/kona%2Fkona-node/446969659?tag=latest


# Docker Guide
Source: https://docs.optimism.io/node-operators/kona-node/run/docker

Run kona-node with op-reth using Kona's pre-packaged docker-compose setup, including Grafana dashboards and Prometheus.

<Info>
  This guide uses Kona's pre-packaged docker config.

  For detailed usage of the `kona-node` binary, head
  over to [the binary guide](/node-operators/kona-node/run/binary).
  To run an op-node + op-reth stack with Docker instead, see
  [Running a Node With Docker](/node-operators/tutorials/node-from-docker).
</Info>

Kona provides a [`kona-node` docker recipe][recipe]
with detailed instructions for running a complete node setup.

## Quick Start

The easiest way to run `kona-node` with Docker is using the provided recipe:

1. **Navigate to the recipe directory:**
   ```bash theme={null}
   cd docker/recipes/kona-node
   ```

2. **Configure environment variables:**
   Edit `cfg.env` to set your L1 RPC endpoints:
   ```bash theme={null}
   L1_PROVIDER_RPC=https://your-l1-rpc-endpoint
   L1_BEACON_API=https://your-l1-beacon-endpoint
   ```

3. **Start the services:**
   ```bash theme={null}
   just up
   ```

This will start:

* `kona-node` - The OP Stack node implementation
* `op-reth` - Execution layer client
* `prometheus` - Metrics collection
* `grafana` - Monitoring dashboards (accessible at [http://localhost:3000](http://localhost:3000))

## Docker Compose

In the [provided docker compose][compose], there are a few services
aside from the `kona-node` and `op-reth`. These are `prometheus`
and `grafana` which automatically come provisioned with dashboards
for monitoring and insight into the `kona-node` and `op-reth` services.
For more detail into how Prometheus and Grafana work, head over to the
[Monitoring][monitoring] docs.

The `docker-compose.yaml` uses published images from GitHub Container Registry:

* **`op-reth`**: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-reth:develop
* **`kona-node`**: us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:develop

### Service Configuration

#### kona-node Service

The `kona-node` service is configured with the following key settings:

* **Ports**:
  * `5060` - RPC endpoint
  * `9223` - P2P discovery (TCP/UDP)
  * `9002` - Metrics
* **Environment**: L1 RPC and Beacon API endpoints are required
* **Volumes**: Persistent data storage and JWT token for engine API authentication

#### op-reth Service

The `op-reth` service provides the execution layer:

* **Ports**:
  * `8545` - HTTP RPC
  * `8551` - Engine API (authenticated)
  * `30303` - P2P discovery
  * `9001` - Metrics
* **Configuration**: Pre-configured for OP Sepolia testnet

## Configuration

### Network Selection

By default, the recipe is configured for **OP Sepolia**. To sync a different OP Stack chain:

1. Set appropriate L1 endpoints for your target network in `cfg.env`
2. Modify the docker-compose.yaml:
   * Update `op-reth --chain` parameter
   * Update `op-reth --rollup.sequencer-http` endpoint
   * Update `kona-node --chain` parameter

### RPC Trust Configuration

By default, `kona-node` trusts RPC providers (both L1 and L2). When using public or untrusted RPC endpoints, you should disable trust to enable block hash verification:

```bash theme={null}
# In cfg.env or as environment variables:
KONA_NODE_L1_TRUST_RPC=false
KONA_NODE_L2_TRUST_RPC=false
```

Or modify the docker-compose.yaml command:

```yaml theme={null}
kona-node:
  command: |
    node
    --chain op-sepolia
    --l1-eth-rpc ${L1_PROVIDER_RPC}
    --l1-beacon ${L1_BEACON_API}
    --l1-trust-rpc false  # Add this for untrusted L1 RPCs
    --l2-engine-rpc ws://op-reth:8551
    --l2-trust-rpc false  # Add this for untrusted L2 RPCs
```

See [configure RPC trust](/node-operators/kona-node/run/rpc-trust) for more details on RPC trust settings.

### Port Configuration

All host ports can be customized via environment variables in `cfg.env`:

```bash theme={null}
# Kona Node ports
KONA_NODE_RPC_PORT=5060
KONA_NODE_DISCOVERY_PORT=9223
KONA_NODE_METRICS_PORT=9002

# OP Reth ports  
OP_RETH_RPC_PORT=8545
OP_RETH_ENGINE_PORT=8551
OP_RETH_METRICS_PORT=9001
OP_RETH_DISCOVERY_PORT=30303

# Monitoring
PROMETHEUS_PORT=9090
```

### Logging

Adjust log levels by setting the `RUST_LOG` environment variable:

```bash theme={null}
export RUST_LOG=engine_builder=trace,runtime=debug
```

## Management Commands

The recipe includes convenient Just commands:

```bash theme={null}
# Start all services
just up

# Stop all services  
just down

# Restart all services
just restart

# Generate JWT token (if needed)
./generate-jwt.sh
```

## Getting the kona-node Image

The recipe pulls published `kona-node` and `op-reth` images automatically.
Use this section when you want to pull or build the `kona-node` image
yourself, for example to pin a release version or test local changes.

### Pulling a published image

Kona docker images are published with every release on GitHub Container Registry.

You can obtain the latest `kona-node` image with:

```bash theme={null}
docker pull us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node
```

<Note>
  Specify a specific version (e.g. v0.1.0) like so.

  ```bash theme={null}
  docker pull us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:v0.1.0
  ```
</Note>

You can test the image with:

```bash theme={null}
docker run --rm us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node --version
```

If you can see the [latest release](https://github.com/ethereum-optimism/optimism/releases) version,
then you've successfully installed Kona via Docker.

### Building the Docker image

To build the image from source, navigate to the root of the
[kona directory](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona)
in the monorepo and run:

```bash theme={null}
just build-local kona-node
```

<Note>
  This will create an image with the tag `kona:local`. To specify a custom
  tag, just pass it in after `kona-node` in the command above, like so:

  ```bash theme={null}
  just build-local kona-node my-custom-tag
  ```
</Note>

The build will likely take several minutes. Once it's built, test it with:

```bash theme={null}
docker run kona:local --version
```

To use the locally built image with the recipe, update `docker-compose.yaml`
to use `kona:local` instead of the published image.

[monitoring]: ../monitoring.mdx

[recipe]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/docker/recipes/kona-node/README.md

[compose]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/docker/recipes/kona-node/docker-compose.yaml


# How it Works
Source: https://docs.optimism.io/node-operators/kona-node/run/mechanics



Kona brings together a powerful suite of `no-std` and `std` Rust components,
purpose-built for the OP Stack. At the heart of this ecosystem is the
`kona-node` — a modern, modular rollup node (L2 consensus node) that can
be used as a drop-in binary or as a foundation for custom services.

The `kona-node` is a fully compliant implementation of the ["Rollup Node"
Specifications][rollup-node] and is released as a [binary][package] in
the [kona repository][kona]. Whether you're running a production network,
building new rollup features, or experimenting with the OP Stack,
`kona-node` is built to be both robust and extensible.

### Background

A rollup node is responsible for deriving the canonical L2 chain from L1
blocks and their receipts. It validates these blocks using the
[Engine API][engine-api], passing them to the execution layer for processing.

Paired with an execution engine like op-reth or op-geth, `kona-node` tracks
the unsafe, safe, and finalized tips of the L2 OP Stack chain, ensuring the
node is always in sync with the latest state.

<Note>
  Rollup nodes hold minimal state. Unsafe and safe payloads alike are sent
  away to the execution engine client which holds the chain's db. This way,
  the rollup node holds a view of the tip of the chain - unsafe, safe, and
  finalized block info. All data otherwise needed is held in memory.
</Note>

There are a few core architectural pieces of the `kona-node`.

* **Derivation Pipeline:** Constructs L2 payload attributes from L1 blocks,
  forming the backbone of rollup logic.
* **Execution Engine Integration:** Executes L2 payload attributes via the
  [Engine API][engine-api], abstracting away different EL clients.
* **P2P Networking:** Enables block gossip and peer discovery.

For an in-depth breakdown of these three pillars and a detailed design
of the `kona-node`, visit the [Node Design section](/node-operators/kona-node/design/intro).

Additionally, an RPC server exposes essential methods, including the
[L2 Output RPC method][l2o-rpc].

### Syncing

The `kona-node` syncs the L2 chain in two main phases:

1. **Execution Layer (EL) Sync:**
   When starting, the node initially has an empty engine task queue.
   Once an unsafe block is received from P2P gossip, an `InsertTask`
   is executed. That task inserts the payload and sends a forkchoice
   update through the engine api. Since the engine state is lazily
   initialized (the safe and finalized heads are zero), the forkchoice
   update kicks off EL sync on the execution layer (EL) client (such
   as op-reth or op-geth). EL sync instructs the execution client to
   fetch and sync L2 blocks directly from peers. During this phase,
   the `kona-node` effectively waits for the EL client to reach the
   chain tip, when it returns that it is `synced`. No L2 blocks
   are derived from L1 during this period.

2. **Consensus Layer (CL) Sync:**
   Once the EL client is fully synced to the tip, the node transitions
   to consensus layer (CL) sync. In this phase, `kona-node` begins
   deriving new L2 payload attributes from the L1 chain, following
   the rollup derivation process. `OpAttributesWithParent` values
   derived this way are executed as an engine task which submits
   the payloads to the execution engine for validation and execution.

<Note>
  * `kona-node` does **not** support historical CL sync or backfilling
    L2 blocks from L1 for past chain history. It relies on the EL client
    to perform the initial sync of the L2 chain.
  * Only after the EL is fully synced does the node begin deriving and
    following new L2 blocks from L1.
</Note>

### Extensibility

The `kona-node` is designed as a modular, actor-based node SDK,
making it possible to extend or customize node behavior by adding
new actors or swapping out existing ones. This extensibility is
currently in **beta**, but the architecture is intentionally built
to support advanced use cases and custom integrations.

#### Actor Model

At the core of `kona-node` is the concept of **actors**: independent,
async services that communicate over channels. Each actor implements
the [`NodeActor` trait][node-actor], a minimal interface with a single
`step` method that the service drives in a loop until the actor reports
a fatal error or the node shuts down.

The [`RollupNode` service][node] builds and spawns a fixed set of
actors covering derivation, the execution engine and its read-only
engine RPC, the L1 watcher, P2P networking, the node's RPC server,
and, in sequencer mode, block building.

The [Node Design section](/node-operators/kona-node/design/intro) is
the canonical description of that actor set and of what each actor
does.

#### Extending with Custom Actors

You can write your own actor by implementing the `NodeActor` trait.
This allows you to introduce new background services, event
processors, or integrations with external systems.

The trait has one associated type and one method. Each call to `step`
handles a single inbound request, event, or scheduled tick. Returning
`Ok(())` means the actor is ready to be stepped again; returning an
error is fatal and stops the actor. Cancellation is handled by the
caller that drives the loop, so the actor itself does not own a
cancellation token.

**Example: Defining a Custom Actor**

```rust theme={null}
use async_trait::async_trait;
use kona_node_service::NodeActor;

struct MyCustomActor;

#[async_trait]
impl NodeActor for MyCustomActor {
    type Error = std::io::Error;

    async fn step(&mut self) -> Result<(), Self::Error> {
        // Your actor logic for one step here.
        Ok(())
    }
}
```

#### Running Custom Actors

There is no trait-based extension point for swapping actors into the
standard node today. [`RollupNode`][node] is a concrete type rather
than a trait, its actor set is fixed in that type's `start` method,
and the helper that spawns and supervises those actors is internal to
the `kona-node-service` crate.

Running a custom actor therefore means composing the node yourself.
The built-in actors are public API of the `kona-node-service` crate.
The request and payload types they exchange over channels are public
too, spread across `kona-node-service`, sibling kona crates such as
`kona-rpc` and `kona-gossip`, and the shared alloy engine types. A
custom binary can therefore construct the actors it needs, wire them
together over channels, add its own `NodeActor` implementations, and
drive each actor's `step` method in its own task.

#### Programmatic Node Construction

The [`RollupNodeBuilder`][builder] provides a convenient way to
construct a standard node, but for advanced use cases, you can build
your own node by composing actors directly, or by implementing your
own builder pattern.

#### Current Limitations

* The actor and service APIs are **beta** and may change.
* The standard `RollupNode` exposes no hook for overriding an
  individual actor or pipeline, so extending the node means composing
  actors in your own binary rather than wrapping `RollupNode`.
* Documentation and examples for advanced extensibility are still
  evolving—contributions and feedback are welcome!

#### Learn More

* See the [`NodeActor` trait documentation][node-actor] for details
  on implementing actors.
* Explore the [kona-node-service crate][service] for source code
  and more examples.

[cli-docs]: ../configuration.mdx

[subcommands]: ../subcommands.mdx

[service]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/crates/node/service

[node-actor]: https://docs.rs/kona-node-service/latest/kona_node_service/trait.NodeActor.html

[node]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/node.rs

[builder]: https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/node/service/src/service/builder.rs

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[packages]: https://github.com/orgs/op-rs/packages?repo_name=kona

[rollup-node]: https://specs.optimism.io/protocol/rollup-node.html

[package]: https://github.com/ethereum-optimism/optimism/pkgs/container/kona%2Fkona-node

[pdocs]: https://github.com/ethereum-optimism/optimism/pkgs/container/kona%2Fkona-node/446969659?tag=latest

[buildx]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/docker

[engine-api]: https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md

[l2o-rpc]: https://specs.optimism.io/protocol/rollup-node.html#l2-output-rpc-method


# Run a Node
Source: https://docs.optimism.io/node-operators/kona-node/run/overview



Now that you have [installed the `kona-node`](/node-operators/kona-node/install/overview),
it's time to run it.

In this section, we'll guide you through running the kona-node on
various networks and with different configurations.

## Supported Networks

Kona uses the [superchain-registry][scr] to dynamically load
chain configurations for the specified network. As such, Kona
can only support networks that are defined this way.

[scr]: https://github.com/ethereum-optimism/superchain-registry

To view available networks, the `kona-node` binary provides
a `registry` subcommand that lists all available networks:

```bash theme={null}
kona-node registry
```

<Tip>
  Want to add support for a new network?
  Feel free to [add a chain](https://github.com/ethereum-optimism/superchain-registry/blob/main/docs/ops.md#adding-a-chain)
  to the superchain-registry!
</Tip>

## Configuration & Monitoring

Learn how to configure and monitor your node:

* **[Configuration](/node-operators/kona-node/configuration)** - Configure your node
* **[Monitoring](/node-operators/kona-node/monitoring)** - Set up logs, metrics, and observability


# Configure RPC Trust
Source: https://docs.optimism.io/node-operators/kona-node/run/rpc-trust

Decide when to enable RPC response verification on kona-node and configure the --l1-trust-rpc and --l2-trust-rpc flags for trusted and untrusted providers.

The `--l1-trust-rpc` and `--l2-trust-rpc` flags control whether Kona performs additional verification on RPC responses to protect against malicious or faulty RPC providers. This guide helps you choose the right setting for your infrastructure and shows how to configure it.

## Trust Modes

**Default Behavior (trust enabled, `true`):**

* No additional block hash verification is performed
* Optimized for performance
* Suitable for local nodes and trusted infrastructure
* Assumes the RPC provider is reliable and honest

**Verification Mode (trust disabled, `false`):**

* All fetched blocks have their hashes verified against the requested hashes
* Protects against malicious RPC providers returning incorrect blocks
* Recommended for public or third-party RPC endpoints
* Small performance overhead due to hash verification

## Examples

**Using trusted local RPCs (default):**

```bash theme={null}
kona-node node \
  --l1-eth-rpc http://localhost:8545 \
  --l2-engine-rpc http://localhost:8551 \
  # trust-rpc defaults to true, no need to specify
```

**Using untrusted public RPCs:**

```bash theme={null}
kona-node node \
  --l1-eth-rpc https://public-eth-rpc.com \
  --l1-trust-rpc false \
  --l2-engine-rpc https://public-l2-rpc.com \
  --l2-trust-rpc false
```

**Mixed trust configuration:**

```bash theme={null}
kona-node node \
  --l1-eth-rpc https://public-eth-rpc.com \
  --l1-trust-rpc false \
  --l2-engine-rpc http://localhost:8551 \
  # L2 trust-rpc defaults to true for local engine
```

## Security Recommendations

1. **Local Infrastructure**: Keep the default `true` setting for RPCs you control
2. **Public RPCs**: Always set `--trust-rpc false` when using third-party endpoints
3. **Shared Infrastructure**: Consider setting `--trust-rpc false` as a precaution
4. **Performance Testing**: The verification overhead is minimal but can be measured in high-throughput scenarios

## Next Steps

* Both flags are catalogued with the rest of the node's options in the [Kona node CLI reference](/node-operators/kona-node/configuration).
* To get a node running end to end, follow the [binary guide](/node-operators/kona-node/run/binary) or the [Docker guide](/node-operators/kona-node/run/docker).


# Run a Sequencer Node
Source: https://docs.optimism.io/node-operators/kona-node/run/sequencer

Run kona-node in sequencer mode from the command line, including required arguments, sequencer-specific flags, and example configurations.

This guide shows how to run `kona-node` in **sequencer mode** from the command line. For how sequencer mode works internally and how to configure it programmatically through the Node SDK, see the [sequencer mode design](/node-operators/kona-node/design/sequencer) page.

<Info>
  Sequencer mode is an advanced configuration primarily used by rollup operators. Most users will run nodes in the default validator mode.
</Info>

## Basic Sequencer Setup

To run a Kona node in sequencer mode:

```bash theme={null}
kona-node node \
  --mode=Sequencer \
  --l1-eth-rpc=http://l1-node:8545 \
  --l1-beacon=http://l1-beacon:5052 \
  --l2-engine-rpc=http://l2-execution:8551 \
  --l2.jwt-secret=./jwt.hex \
  --chain=123456
```

## Required Arguments

<Warning>
  **Required Configuration**

  Sequencer mode requires all standard node arguments plus the `--mode=Sequencer` flag. Missing any required argument will prevent the node from starting.
</Warning>

| Argument       | Flag              | Environment Variable       | Description                 |
| -------------- | ----------------- | -------------------------- | --------------------------- |
| **Mode**       | `--mode`          | `KONA_NODE_MODE`           | Must be set to `Sequencer`  |
| **L1 RPC**     | `--l1-eth-rpc`    | `KONA_NODE_L1_ETH_RPC`     | L1 execution client RPC URL |
| **L1 Beacon**  | `--l1-beacon`     | `KONA_NODE_L1_BEACON`      | L1 beacon API URL           |
| **L2 Engine**  | `--l2-engine-rpc` | `KONA_NODE_L2_ENGINE_RPC`  | L2 engine API endpoint      |
| **JWT Secret** | `--l2.jwt-secret` | `KONA_NODE_L2_ENGINE_AUTH` | Path to JWT secret file     |
| **Chain ID**   | `--chain`         | `KONA_NODE_L2_CHAIN_ID`    | L2 chain identifier         |

## Sequencer-Specific Flags

| Flag                       | Environment Variable               | Default | Description                                 |
| -------------------------- | ---------------------------------- | ------- | ------------------------------------------- |
| `--sequencer.stopped`      | `KONA_NODE_SEQUENCER_STOPPED`      | `false` | Start sequencer in stopped state            |
| `--sequencer.max-safe-lag` | `KONA_NODE_SEQUENCER_MAX_SAFE_LAG` | `0`     | Max L2 blocks between safe and unsafe heads |
| `--sequencer.l1-confs`     | `KONA_NODE_SEQUENCER_L1_CONFS`     | `4`     | L1 confirmations for origin selection       |
| `--sequencer.recover`      | `KONA_NODE_SEQUENCER_RECOVER`      | `false` | Force recovery mode operation               |
| `--conductor.rpc`          | `KONA_NODE_CONDUCTOR_RPC`          | -       | Conductor service RPC endpoint              |
| `--conductor.rpc.timeout`  | `KONA_NODE_CONDUCTOR_RPC_TIMEOUT`  | `1`     | Conductor RPC timeout (seconds)             |

The full flag catalogue, including the standard node arguments shared with validator mode, lives in the [Kona node CLI reference](/node-operators/kona-node/configuration).

## Example Configurations

### Basic Sequencer

```bash theme={null}
kona-node node \
  --mode=Sequencer \
  --l1-eth-rpc=http://localhost:8545 \
  --l1-beacon=http://localhost:5052 \
  --l2-engine-rpc=http://localhost:8551 \
  --chain=42161
```

### Sequencer with Conductor

```bash theme={null}
kona-node node \
  --mode=Sequencer \
  --conductor.rpc=http://conductor:8080 \
  --conductor.rpc.timeout=5 \
  --sequencer.l1-confs=6 \
  --l1-eth-rpc=http://l1-node:8545 \
  --l1-beacon=http://l1-beacon:5052 \
  --l2-engine-rpc=http://l2-execution:8551 \
  --chain=123456
```

### Recovery Mode Sequencer

```bash theme={null}
kona-node node \
  --mode=Sequencer \
  --sequencer.recover=true \
  --sequencer.max-safe-lag=100 \
  --l1-eth-rpc=http://localhost:8545 \
  --l1-beacon=http://localhost:5052 \
  --l2-engine-rpc=http://localhost:8551 \
  --chain=42161
```

## Key Considerations

<Tip>
  **Sequencer Operation**

  * **L1 Confirmations**: The `--sequencer.l1-confs` setting determines how many L1 blocks the sequencer waits before using an L1 block as an origin. Higher values provide more safety but increase latency.
  * **Recovery Mode**: Use `--sequencer.recover=true` when the sequencer needs to catch up after being offline.
  * **Conductor Integration**: For multi-sequencer deployments, configure the conductor service for proper leader election.
</Tip>

Running a sequencer in production requires careful consideration of infrastructure, monitoring, and failover procedures. Ensure proper JWT secret management and secure network configuration.


# `kona-node` Subcommands
Source: https://docs.optimism.io/node-operators/kona-node/subcommands



Below are the available subcommands for `kona-node`:

* **node**: Runs the main consensus node service. This is the primary subcommand for operating a rollup node.
* **info**: Displays information about the node, build, and environment.
* **bootstore**: Manages the P2P bootstore (used for peer discovery and persistence).
* **net**: Provides network-related utilities and diagnostics.
* **registry**: Interacts with the chain registry for configuration and metadata.

For more details on each subcommand and their flags, run:

```
kona-node <subcommand> --help
```


# op-reth
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth



Reth

```bash theme={null}
$ op-reth --help
```

```txt theme={null}
Usage: op-reth [OPTIONS] <COMMAND>

Commands:
  node                Start the node
  init                Initialize the database from a genesis file
  init-state          Initialize the database from a state dump file
  import-op           This syncs RLP encoded OP blocks below Bedrock from a file, without executing
  import-receipts-op  This imports RLP encoded receipts from a file
  dump-genesis        Dumps genesis block JSON configuration to stdout
  db                  Database debugging utilities
  stage               Manipulate individual stages
  p2p                 P2P Debugging utilities
  config              Write config to stdout
  prune               Prune according to the configuration without any limits
  re-execute          Re-execute blocks in parallel to verify historical sync correctness
  proofs              Manage storage of historical proofs in expanded trie db in fault proof window
  help                Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth config
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/config



Write config to stdout

```bash theme={null}
$ op-reth config --help
```

```txt theme={null}
Usage: op-reth config [OPTIONS]

Options:
      --config <FILE>
          The path to the configuration file to use.

      --default
          Show the default config

  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db



Database debugging utilities

```bash theme={null}
$ op-reth db --help
```

```txt theme={null}
Usage: op-reth db [OPTIONS] <COMMAND>

Commands:
  stats               Lists all the tables, their entry count and their size
  list                Lists the contents of a table
  checksum            Calculates the content checksum of a table or static file segment
  copy                Copies the MDBX database to a new location (bundled mdbx_copy)
  diff                Create a diff between two database tables or two entire databases
  get                 Gets the content of a table for the given key
  drop                Deletes all database entries
  clear               Deletes all table entries
  repair-trie         Verifies trie consistency and outputs any inconsistencies
  static-file-header  Reads and displays the static file segment header
  version             Lists current and local database versions
  path                Returns the full database path
  settings            Manage storage settings
  prune-checkpoints   View or set prune checkpoints
  stage-checkpoints   `reth db stage-checkpoints` subcommand
  account-storage     Gets storage size information for an account
  state               Gets account state and storage at a specific block
  migrate-v2          Migrate storage layout from v1 (MDBX-only) to v2 (static files + RocksDB)
  help                Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db account-storage
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/account-storage



Gets storage size information for an account

```bash theme={null}
$ op-reth db account-storage --help
```

```txt theme={null}
Usage: op-reth db account-storage [OPTIONS] <ADDRESS>

Arguments:
  <ADDRESS>
          The account address to check storage for

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db checksum
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/checksum



Calculates the content checksum of a table or static file segment

```bash theme={null}
$ op-reth db checksum --help
```

```txt theme={null}
Usage: op-reth db checksum [OPTIONS] <COMMAND>

Commands:
  mdbx         Calculates the checksum of a database table
  static-file  Calculates the checksum of a static file segment
  rocksdb      Calculates the checksum of a RocksDB table
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db checksum mdbx
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/checksum/mdbx



Calculates the checksum of a database table

```bash theme={null}
$ op-reth db checksum mdbx --help
```

```txt theme={null}
Usage: op-reth db checksum mdbx [OPTIONS] <TABLE>

Arguments:
  <TABLE>
          The table name

Options:
      --start-key <START_KEY>
          The start of the range to checksum

      --end-key <END_KEY>
          The end of the range to checksum

      --limit <LIMIT>
          The maximum number of records that are queried and used to compute the checksum

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db checksum rocksdb
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/checksum/rocksdb



Calculates the checksum of a RocksDB table

```bash theme={null}
$ op-reth db checksum rocksdb --help
```

```txt theme={null}
Usage: op-reth db checksum rocksdb [OPTIONS] <TABLE>

Arguments:
  <TABLE>
          The RocksDB table

          Possible values:
          - transaction-hash-numbers: Transaction hash to transaction number mapping
          - accounts-history:         Account history indices
          - storages-history:         Storage history indices

Options:
      --limit <LIMIT>
          The maximum number of records to checksum

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db checksum static-file
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/checksum/static-file



Calculates the checksum of a static file segment

```bash theme={null}
$ op-reth db checksum static-file --help
```

```txt theme={null}
Usage: op-reth db checksum static-file [OPTIONS] <SEGMENT>

Arguments:
  <SEGMENT>
          The static file segment

          Possible values:
          - headers:             Static File segment responsible for the `CanonicalHeaders`, `Headers`, `HeaderTerminalDifficulties` tables
          - transactions:        Static File segment responsible for the `Transactions` table
          - receipts:            Static File segment responsible for the `Receipts` table
          - transaction-senders: Static File segment responsible for the `TransactionSenders` table
          - account-change-sets: Static File segment responsible for the `AccountChangeSets` table
          - storage-change-sets: Static File segment responsible for the `StorageChangeSets` table

Options:
      --start-block <START_BLOCK>
          The block number to start from (inclusive)

      --end-block <END_BLOCK>
          The block number to end at (inclusive)

      --limit <LIMIT>
          The maximum number of rows to checksum

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db clear
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/clear



Deletes all table entries

```bash theme={null}
$ op-reth db clear --help
```

```txt theme={null}
Usage: op-reth db clear [OPTIONS] <COMMAND>

Commands:
  mdbx         Deletes all database table entries
  static-file  Deletes all static file segment entries
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db clear mdbx
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/clear/mdbx



Deletes all database table entries

```bash theme={null}
$ op-reth db clear mdbx --help
```

```txt theme={null}
Usage: op-reth db clear mdbx [OPTIONS] <TABLE>

Arguments:
  <TABLE>


Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db clear static-file
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/clear/static-file



Deletes all static file segment entries

```bash theme={null}
$ op-reth db clear static-file --help
```

```txt theme={null}
Usage: op-reth db clear static-file [OPTIONS] <SEGMENT>

Arguments:
  <SEGMENT>
          Possible values:
          - headers:             Static File segment responsible for the `CanonicalHeaders`, `Headers`, `HeaderTerminalDifficulties` tables
          - transactions:        Static File segment responsible for the `Transactions` table
          - receipts:            Static File segment responsible for the `Receipts` table
          - transaction-senders: Static File segment responsible for the `TransactionSenders` table
          - account-change-sets: Static File segment responsible for the `AccountChangeSets` table
          - storage-change-sets: Static File segment responsible for the `StorageChangeSets` table

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db copy
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/copy



Copies the MDBX database to a new location (bundled mdbx\_copy)

```bash theme={null}
$ op-reth db copy --help
```

```txt theme={null}
Usage: op-reth db copy [OPTIONS] <DEST>

Arguments:
  <DEST>
          Destination path for the database copy

Options:
  -c, --compact
          Compact the database while copying (reclaims free space)

  -d, --force-dynamic-size
          Force dynamic size for the destination database

  -p, --throttle-mvcc
          Throttle to avoid MVCC pressure on writers

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db diff
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/diff



Create a diff between two database tables or two entire databases

```bash theme={null}
$ op-reth db diff --help
```

```txt theme={null}
Usage: op-reth db diff [OPTIONS] --secondary-datadir <SECONDARY_DATADIR> --output <OUTPUT>

Options:
      --secondary-datadir <SECONDARY_DATADIR>
          The path to the data dir for all reth files and subdirectories.

  -h, --help
          Print help (see a summary with '-h')

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

      --table <TABLE>
          The table name to diff. If not specified, all tables are diffed.

      --output <OUTPUT>
          The output directory for the diff report.

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db drop
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/drop



Deletes all database entries

```bash theme={null}
$ op-reth db drop --help
```

```txt theme={null}
Usage: op-reth db drop [OPTIONS]

Options:
  -f, --force
          Bypasses the interactive confirmation and drops the database directly

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db get
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/get



Gets the content of a table for the given key

```bash theme={null}
$ op-reth db get --help
```

```txt theme={null}
Usage: op-reth db get [OPTIONS] <COMMAND>

Commands:
  mdbx         Gets the content of a database table for the given key
  static-file  Gets the content of a static file segment for the given key
  rocksdb      Gets the content of a RocksDB table for the given key
  help         Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db get mdbx
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/get/mdbx



Gets the content of a database table for the given key

```bash theme={null}
$ op-reth db get mdbx --help
```

```txt theme={null}
Usage: op-reth db get mdbx [OPTIONS] <TABLE> <KEY> [SUBKEY] [END_KEY] [END_SUBKEY]

Arguments:
  <TABLE>


  <KEY>
          The key to get content for

  [SUBKEY]
          The subkey to get content for

  [END_KEY]
          Optional end key for range query (exclusive upper bound)

  [END_SUBKEY]
          Optional end subkey for range query (exclusive upper bound)

Options:
      --raw
          Output bytes instead of human-readable decoded value

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db get rocksdb
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/get/rocksdb



Gets the content of a RocksDB table for the given key

```bash theme={null}
$ op-reth db get rocksdb --help
```

```txt theme={null}
Usage: op-reth db get rocksdb [OPTIONS] <TABLE> <KEY>

Arguments:
  <TABLE>
          The RocksDB table

          Possible values:
          - transaction-hash-numbers: Transaction hash to transaction number mapping
          - accounts-history:         Account history indices
          - storages-history:         Storage history indices

  <KEY>
          The key to get content for. For history tables, this can be a plain address

Options:
      --block <BLOCK>
          Target block number for history tables. Seeks to the shard containing this block. Defaults to the latest shard if not specified

      --storage-key <STORAGE_KEY>
          Storage key for storages-history table lookups

      --all-shards
          List all shards for the given key (history tables only)

      --raw
          Output bytes instead of human-readable decoded value

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db get static-file
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/get/static-file



Gets the content of a static file segment for the given key

```bash theme={null}
$ op-reth db get static-file --help
```

```txt theme={null}
Usage: op-reth db get static-file [OPTIONS] <SEGMENT> <KEY> [SUBKEY]

Arguments:
  <SEGMENT>
          Possible values:
          - headers:             Static File segment responsible for the `CanonicalHeaders`, `Headers`, `HeaderTerminalDifficulties` tables
          - transactions:        Static File segment responsible for the `Transactions` table
          - receipts:            Static File segment responsible for the `Receipts` table
          - transaction-senders: Static File segment responsible for the `TransactionSenders` table
          - account-change-sets: Static File segment responsible for the `AccountChangeSets` table
          - storage-change-sets: Static File segment responsible for the `StorageChangeSets` table

  <KEY>
          The key to get content for

  [SUBKEY]
          The subkey to get content for, for example address in changeset

Options:
      --raw
          Output bytes instead of human-readable decoded value

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db list
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/list



Lists the contents of a table

```bash theme={null}
$ op-reth db list --help
```

```txt theme={null}
Usage: op-reth db list [OPTIONS] <TABLE>

Arguments:
  <TABLE>
          The table name

Options:
  -s, --skip <SKIP>
          Skip first N entries

          [default: 0]

  -r, --reverse
          Reverse the order of the entries. If enabled last table entries are read

  -l, --len <LEN>
          How many items to take from the walker

          [default: 5]

      --search <SEARCH>
          Search parameter for both keys and values. Prefix it with `0x` to search for binary data, and text otherwise.

          ATTENTION! For compressed tables (`Transactions` and `Receipts`), there might be missing results since the search uses the raw uncompressed value from the database.

      --min-row-size <MIN_ROW_SIZE>
          Minimum size of row in bytes

          [default: 0]

      --min-key-size <MIN_KEY_SIZE>
          Minimum size of key in bytes

          [default: 0]

      --min-value-size <MIN_VALUE_SIZE>
          Minimum size of value in bytes

          [default: 0]

  -c, --count
          Returns the number of rows found

  -j, --json
          Dump as JSON instead of using TUI

      --raw
          Output bytes instead of human-readable decoded value

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db migrate-v2
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/migrate-v2



Migrate storage layout from v1 (MDBX-only) to v2 (static files + RocksDB)

```bash theme={null}
$ op-reth db migrate-v2 --help
```

```txt theme={null}
Usage: op-reth db migrate-v2 [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db path
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/path



Returns the full database path

```bash theme={null}
$ op-reth db path --help
```

```txt theme={null}
Usage: op-reth db path [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db prune-checkpoints
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/prune-checkpoints



View or set prune checkpoints

```bash theme={null}
$ op-reth db prune-checkpoints --help
```

```txt theme={null}
Usage: op-reth db prune-checkpoints [OPTIONS] <COMMAND>

Commands:
  get   Get prune checkpoint(s) from database
  set   Set a prune checkpoint for a segment
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db prune-checkpoints get
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/prune-checkpoints/get



Get prune checkpoint(s) from database.

```bash theme={null}
$ op-reth db prune-checkpoints get --help
```

```txt theme={null}
Usage: op-reth db prune-checkpoints get [OPTIONS]

Options:
      --segment <SEGMENT>
          Specific segment to query. If omitted, shows all segments

          [possible values: sender-recovery, transaction-lookup, receipts, contract-logs, account-history, storage-history, bodies]

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db prune-checkpoints set
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/prune-checkpoints/set



Set a prune checkpoint for a segment.

```bash theme={null}
$ op-reth db prune-checkpoints set --help
```

```txt theme={null}
Usage: op-reth db prune-checkpoints set [OPTIONS] --segment <SEGMENT> --mode <MODE>

Options:
      --segment <SEGMENT>
          The prune segment to update

          [possible values: sender-recovery, transaction-lookup, receipts, contract-logs, account-history, storage-history, bodies]

      --block-number <BLOCK_NUMBER>
          Highest pruned block number

      --tx-number <TX_NUMBER>
          Highest pruned transaction number

      --mode <MODE>
          Prune mode to write: full, distance, or before

          Possible values:
          - full:     Prune all blocks
          - distance: Keep the last N blocks (requires --mode-value)
          - before:   Prune blocks before a specific block number (requires --mode-value)

      --mode-value <MODE_VALUE>
          Value for distance or before mode (required unless mode is full)

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db repair-trie
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/repair-trie



Verifies trie consistency and outputs any inconsistencies

```bash theme={null}
$ op-reth db repair-trie --help
```

```txt theme={null}
Usage: op-reth db repair-trie [OPTIONS]

Options:
      --dry-run
          Only show inconsistencies without making any repairs

      --metrics <ADDR:PORT>
          Enable Prometheus metrics.

          The metrics will be served at the given interface and port.

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db settings
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/settings



Manage storage settings

```bash theme={null}
$ op-reth db settings --help
```

```txt theme={null}
Usage: op-reth db settings [OPTIONS] <COMMAND>

Commands:
  get   Get current storage settings from database
  set   Set storage settings in database
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db settings get
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/settings/get



Get current storage settings from database

```bash theme={null}
$ op-reth db settings get --help
```

```txt theme={null}
Usage: op-reth db settings get [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db settings set
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/settings/set



Set storage settings in database

```bash theme={null}
$ op-reth db settings set --help
```

```txt theme={null}
Usage: op-reth db settings set [OPTIONS] <COMMAND>

Commands:
  v2    Enable or disable v2 storage layout
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db settings set v2
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/settings/set/v2



Enable or disable v2 storage layout

```bash theme={null}
$ op-reth db settings set v2 --help
```

```txt theme={null}
Usage: op-reth db settings set v2 [OPTIONS] <VALUE>

Arguments:
  <VALUE>
          [possible values: true, false]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db stage-checkpoints
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/stage-checkpoints



`reth db stage-checkpoints` subcommand

```bash theme={null}
$ op-reth db stage-checkpoints --help
```

```txt theme={null}
Usage: op-reth db stage-checkpoints [OPTIONS] <COMMAND>

Commands:
  get   Get stage checkpoint(s) from database
  set   Set a stage checkpoint
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db stage-checkpoints get
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/stage-checkpoints/get



Get stage checkpoint(s) from database

```bash theme={null}
$ op-reth db stage-checkpoints get --help
```

```txt theme={null}
Usage: op-reth db stage-checkpoints get [OPTIONS]

Options:
      --stage <STAGE>
          Specific stage to query. If omitted, shows all stages

          [possible values: era, headers, bodies, sender-recovery, execution, prune-sender-recovery, merkle-unwind, account-hashing, storage-hashing, merkle-execute, transaction-lookup, index-storage-history, index-account-history, prune, finish]

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db stage-checkpoints set
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/stage-checkpoints/set



Set a stage checkpoint

```bash theme={null}
$ op-reth db stage-checkpoints set --help
```

```txt theme={null}
Usage: op-reth db stage-checkpoints set [OPTIONS] --stage <STAGE> --block-number <BLOCK_NUMBER>

Options:
      --stage <STAGE>
          Stage to update

          [possible values: era, headers, bodies, sender-recovery, execution, prune-sender-recovery, merkle-unwind, account-hashing, storage-hashing, merkle-execute, transaction-lookup, index-storage-history, index-account-history, prune, finish]

      --block-number <BLOCK_NUMBER>
          Block number to set as stage checkpoint

      --clear-stage-unit
          Clear stage-specific unit checkpoint payload

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db state
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/state



Gets account state and storage at a specific block

```bash theme={null}
$ op-reth db state --help
```

```txt theme={null}
Usage: op-reth db state [OPTIONS] <ADDRESS>

Arguments:
  <ADDRESS>
          The account address to get state for

Options:
  -b, --block <BLOCK>
          Block number to query state at (uses current state if not provided)

  -l, --limit <LIMIT>
          Maximum number of storage slots to display

          [default: 100]

  -f, --format <FORMAT>
          Output format (table, json, csv)

          [default: table]
          [possible values: table, json, csv]

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db static-file-header
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/static-file-header



Reads and displays the static file segment header

```bash theme={null}
$ op-reth db static-file-header --help
```

```txt theme={null}
Usage: op-reth db static-file-header [OPTIONS] <COMMAND>

Commands:
  block  Query by segment and block number
  path   Query by path to static file
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db static-file-header block
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/static-file-header/block



Query by segment and block number

```bash theme={null}
$ op-reth db static-file-header block --help
```

```txt theme={null}
Usage: op-reth db static-file-header block [OPTIONS] <SEGMENT> <BLOCK>

Arguments:
  <SEGMENT>
          Static file segment

          Possible values:
          - headers:             Static File segment responsible for the `CanonicalHeaders`, `Headers`, `HeaderTerminalDifficulties` tables
          - transactions:        Static File segment responsible for the `Transactions` table
          - receipts:            Static File segment responsible for the `Receipts` table
          - transaction-senders: Static File segment responsible for the `TransactionSenders` table
          - account-change-sets: Static File segment responsible for the `AccountChangeSets` table
          - storage-change-sets: Static File segment responsible for the `StorageChangeSets` table

  <BLOCK>
          Block number to query

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db static-file-header path
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/static-file-header/path



Query by path to static file

```bash theme={null}
$ op-reth db static-file-header path --help
```

```txt theme={null}
Usage: op-reth db static-file-header path [OPTIONS] <PATH>

Arguments:
  <PATH>
          Path to the static file

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db stats
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/stats



Lists all the tables, their entry count and their size

```bash theme={null}
$ op-reth db stats --help
```

```txt theme={null}
Usage: op-reth db stats [OPTIONS]

Options:
      --skip-consistency-checks
          Skip consistency checks for static files

      --detailed-sizes
          Show only the total size for static files

      --detailed-segments
          Show detailed information per static file segment

      --checksum
          Show a checksum of each table in the database.

          WARNING: this option will take a long time to run, as it needs to traverse and hash the entire database.

          For individual table checksums, use the `reth db checksum` command.

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth db version
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/db/version



Lists current and local database versions

```bash theme={null}
$ op-reth db version --help
```

```txt theme={null}
Usage: op-reth db version [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth dump-genesis
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/dump-genesis



Dumps genesis block JSON configuration to stdout

```bash theme={null}
$ op-reth dump-genesis --help
```

```txt theme={null}
Usage: op-reth dump-genesis [OPTIONS]

Options:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth import-op
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/import-op



This syncs RLP encoded OP blocks below Bedrock from a file, without executing

```bash theme={null}
$ op-reth import-op --help
```

```txt theme={null}
Usage: op-reth import-op [OPTIONS] <IMPORT_PATH>

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --chunk-len <CHUNK_LEN>
          Chunk byte length to read from file.

  <IMPORT_PATH>
          The path to a block file for import.

          The online stages (headers and bodies) are replaced by a file import, after which the
          remaining stages are executed.

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth import-receipts-op
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/import-receipts-op



This imports RLP encoded receipts from a file

```bash theme={null}
$ op-reth import-receipts-op --help
```

```txt theme={null}
Usage: op-reth import-receipts-op [OPTIONS] <IMPORT_PATH>

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --chunk-len <CHUNK_LEN>
          Chunk byte length to read from file.

  <IMPORT_PATH>
          The path to a receipts file for import. File must use `OpGethReceiptFileCodec` (used for
          exporting OP chain segment below Bedrock block via testinprod/op-geth).

          <https://github.com/testinprod-io/op-geth/pull/1>

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth init
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/init



Initialize the database from a genesis file

```bash theme={null}
$ op-reth init --help
```

```txt theme={null}
Usage: op-reth init [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth init-state
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/init-state



Initialize the database from a state dump file

```bash theme={null}
$ op-reth init-state --help
```

```txt theme={null}
Usage: op-reth init-state [OPTIONS] <STATE_DUMP_FILE>

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --without-evm
          Specifies whether to initialize the state without relying on EVM historical data.

          When enabled, and before inserting the state, it creates a dummy chain up to the last EVM block specified. It then appends the first provided block.

          - **Note**: **Do not** import receipts and blocks beforehand, or this will fail or be ignored.

      --header <HEADER_FILE>
          Header file containing the header in an RLP encoded format.

      --header-hash <HEADER_HASH>
          Hash of the header.

      --without-ovm
          Specifies whether to initialize the state without relying on OVM or EVM historical data.

          When enabled, and before inserting the state, it creates a dummy chain up to the last OVM block (#105235062) (14GB / 90 seconds). It then, appends the Bedrock block. This is hardcoded for OP mainnet, for other OP chains you will need to pass in a header.

          - **Note**: **Do not** import receipts and blocks beforehand, or this will fail or be ignored.

  <STATE_DUMP_FILE>
          JSONL file with state dump.

          Must contain accounts in following format, additional account fields are ignored. Must
          also contain { "root": \<state-root\> } as first line.
          {
              "balance": "\<balance\>",
              "nonce": \<nonce\>,
              "code": "\<bytecode\>",
              "storage": {
                  "\<key\>": "\<value\>",
                  ..
              },
              "address": "\<address\>",
          }

          Allows init at a non-genesis block. Caution! Blocks must be manually imported up until
          and including the non-genesis block to init chain at. See 'import' command.

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth node
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/node



Start the node

```bash theme={null}
$ op-reth node --help
```

```txt theme={null}
Usage: op-reth node [OPTIONS]

Options:
      --config <FILE>
          The path to the configuration file to use.

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

      --instance <INSTANCE>
          Add a new instance of a node.

          Configures the ports of the node to avoid conflicts with the defaults. This is useful for running multiple nodes on the same machine.

          Max number of instances is 200. It is chosen in a way so that it's not possible to have port numbers that conflict with each other.

          Changes to the following port numbers: - `DISCOVERY_PORT`: default + `instance` - 1 - `AUTH_PORT`: default + `instance` * 100 - 100 - `HTTP_RPC_PORT`: default - `instance` + 1 - `WS_RPC_PORT`: default + `instance` * 2 - 2 - `IPC_PATH`: default + `-instance`

      --with-unused-ports
          Sets all ports to unused, allowing the OS to choose random unused ports when sockets are bound.

          Mutually exclusive with `--instance`.

  -h, --help
          Print help (see a summary with '-h')

Metrics:
      --metrics <PROMETHEUS>
          Enable Prometheus metrics.

          The metrics will be served at the given interface and port.

      --metrics.prometheus.push.url <PUSH_GATEWAY_URL>
          URL for pushing Prometheus metrics to a push gateway.

          If set, the node will periodically push metrics to the specified push gateway URL.

      --metrics.prometheus.push.interval <SECONDS>
          Interval in seconds for pushing metrics to push gateway.

          Default: 5 seconds

          [default: 5]

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

Networking:
  -d, --disable-discovery
          Disable the discovery service

      --disable-dns-discovery
          Disable the DNS discovery

      --disable-discv4-discovery
          Disable Discv4 discovery

      --disable-discv5-discovery
          Disable Discv5 discovery

      --disable-nat
          Disable Nat discovery

      --discovery.addr <DISCOVERY_ADDR>
          The UDP address to use for devp2p peer discovery version 4.

          If unset and `--net-if.experimental` is used, discv4 binds to the resolved interface address.

          [default: 0.0.0.0]

      --discovery.port <DISCOVERY_PORT>
          The UDP port to use for devp2p peer discovery version 4

          [default: 30303]

      --discovery.v5.addr <DISCOVERY_V5_ADDR>
          The UDP IPv4 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv4

      --discovery.v5.addr.ipv6 <DISCOVERY_V5_ADDR_IPV6>
          The UDP IPv6 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv6

      --discovery.v5.port <DISCOVERY_V5_PORT>
          The UDP IPv4 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv4, or `--discovery.v5.addr` is set

          [default: 9200]

      --discovery.v5.port.ipv6 <DISCOVERY_V5_PORT_IPV6>
          The UDP IPv6 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv6, or `--discovery.addr.ipv6` is set.

          If not provided, discovery V5 defaults to same port as discovery V4 (--discovery.port).

          [default: 9200]

      --discovery.v5.lookup-interval <DISCOVERY_V5_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out periodic lookup queries, for the whole run of the program

          [default: 20]

      --discovery.v5.bootstrap.lookup-interval <DISCOVERY_V5_BOOTSTRAP_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out boost lookup queries, for a fixed number of times, at bootstrap

          [default: 5]

      --discovery.v5.bootstrap.lookup-countdown <DISCOVERY_V5_BOOTSTRAP_LOOKUP_COUNTDOWN>
          The number of times to carry out boost lookup queries at bootstrap

          [default: 200]

      --trusted-peers <TRUSTED_PEERS>
          Comma separated enode URLs of trusted peers for P2P connections.

          --trusted-peers enode://abcd@192.168.0.1:30303

      --trusted-only
          Connect to or accept from trusted peers only

      --bootnodes <BOOTNODES>
          Comma separated enode URLs for P2P discovery bootstrap.

          Will fall back to a network-specific default if not specified.

      --dns-retries <DNS_RETRIES>
          Amount of DNS resolution requests retries to perform when peering

          [default: 0]

      --peers-file <FILE>
          The path to the known peers file. Connected peers are dumped to this file on nodes
          shutdown, and read on startup. Cannot be used with `--no-persist-peers`.

      --identity <IDENTITY>
          Custom node identity

          [default: op-reth/<VERSION>-<SHA>/<ARCH>]

      --p2p-secret-key <PATH>
          Secret key to use for this node.

          This will also deterministically set the peer ID. If not specified, it will be set in the data dir for the chain being used.

      --p2p-secret-key-hex <HEX>
          Hex encoded secret key to use for this node.

          This will also deterministically set the peer ID. Cannot be used together with `--p2p-secret-key`.

      --no-persist-peers
          Do not persist peers.

      --nat <NAT>
          NAT resolution method (any|none|upnp|publicip|extip:\<IP\>)

          [default: any]

      --addr <ADDR>
          Network listening address

          [default: 0.0.0.0]

      --port <PORT>
          Network listening port

          [default: 30303]

      --max-outbound-peers <MAX_OUTBOUND_PEERS>
          Maximum number of outbound peers. default: 100

      --max-inbound-peers <MAX_INBOUND_PEERS>
          Maximum number of inbound peers. default: 30

      --max-peers <COUNT>
          Maximum number of total peers (inbound + outbound).

          Splits peers using approximately 2:1 inbound:outbound ratio. Cannot be used together with `--max-outbound-peers` or `--max-inbound-peers`.

      --max-tx-reqs <COUNT>
          Max concurrent `GetPooledTransactions` requests.

          [default: 130]

      --max-tx-reqs-peer <COUNT>
          Max concurrent `GetPooledTransactions` requests per peer.

          [default: 1]

      --max-seen-tx-history <COUNT>
          Max number of seen transactions to remember per peer.

          Default is 320 transaction hashes.

          [default: 320]

      --max-pending-imports <COUNT>
          Max number of transactions to import concurrently.

          [default: 4096]

      --pooled-tx-response-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions
          to pack in one response.
          Spec'd at 2MiB.

          [default: 2097152]

      --pooled-tx-pack-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions to
          request in one request.

          Since `RLPx` protocol version 68, the byte size of a transaction is shared as metadata in a
          transaction announcement (see `RLPx` specs). This allows a node to request a specific size
          response.

          By default, nodes request only 128 KiB worth of transactions, but should a peer request
          more, up to 2 MiB, a node will answer with more than 128 KiB.

          Default is 128 KiB.

          [default: 131072]

      --max-tx-pending-fetch <COUNT>
          Max capacity of cache of hashes for transactions pending fetch.

          [default: 25600]

      --tx-channel-memory-limit <BYTES>
          Memory limit (in bytes) for the channel that buffers transaction events flowing
          from the network manager to the transactions manager.

          When the budget is exhausted, new events are dropped (see metric
          `total_dropped_tx_events_at_full_capacity`). Acts as a backstop against unbounded
          memory growth under sustained P2P transaction flooding.

          [default: 1073741824]

      --net-if.experimental <IF_NAME>
          Name of network interface used to communicate with peers.

          If flag is set, but no value is passed, the default interface for docker `eth0` is tried. If `--discovery.addr` is left at its default, discv4 will also bind to the resolved interface address.

      --tx-propagation-policy <TX_PROPAGATION_POLICY>
          Transaction Propagation Policy

          The policy determines which peers transactions are gossiped to.

          [default: All]

      --tx-ingress-policy <TX_INGRESS_POLICY>
          Transaction ingress policy

          Determines which peers' transactions are accepted over P2P.

          [default: All]

      --disable-tx-gossip
          Disable transaction pool gossip

          Disables gossiping of transactions in the mempool to peers. This can be omitted for personal nodes, though providers should always opt to enable this flag.

      --tx-propagation-mode <PROPAGATION_MODE>
          Sets the transaction propagation mode by determining how new pending transactions are propagated to other peers in full.

          Examples: sqrt, all, max:10

          [default: sqrt]

      --required-block-hashes <REQUIRED_BLOCK_HASHES>
          Comma separated list of required block hashes or block number=hash pairs. Peers that don't have these blocks will be filtered out. Format: hash or `block_number=hash` (e.g., 23115201=0x1234...)

      --network-id <NETWORK_ID>
          Optional network ID to override the chain specification's network ID for P2P connections

      --eth-max-message-size <BYTES>
          Maximum allowed ETH message size in bytes. Default is 10 MiB

      --netrestrict <NETRESTRICT>
          Restrict network communication to the given IP networks (CIDR masks).

          Comma separated list of CIDR network specifications. Only peers with IP addresses within these ranges will be allowed to connect.

          Example: --netrestrict "192.168.0.0/16,10.0.0.0/8"

      --enforce-enr-fork-id
          Enforce EIP-868 ENR fork ID validation for discovered peers.

          When enabled, peers discovered without a confirmed fork ID are not added to the peer set until their fork ID is verified via EIP-868 ENR request. This filters out peers from other networks that pollute the discovery table.

RPC:
      --http
          Enable the HTTP-RPC server

      --http.addr <HTTP_ADDR>
          Http server address to listen on

          [default: 127.0.0.1]

      --http.port <HTTP_PORT>
          Http server port to listen on

          [default: 8545]

      --http.disable-compression
          Disable compression for HTTP responses

      --http.api <HTTP_API>
          Rpc Modules to be configured for the HTTP server

          [possible values: admin, debug, eth, net, trace, txpool, web3, rpc, reth, ots, flashbots, miner, mev, testing]

      --http.corsdomain <HTTP_CORSDOMAIN>
          Http Corsdomain to allow request from

      --ws
          Enable the WS-RPC server

      --ws.addr <WS_ADDR>
          Ws server address to listen on

          [default: 127.0.0.1]

      --ws.port <WS_PORT>
          Ws server port to listen on

          [default: 8546]

      --ws.origins <ws.origins>
          Origins from which to accept `WebSocket` requests

      --ws.api <WS_API>
          Rpc Modules to be configured for the WS server

          [possible values: admin, debug, eth, net, trace, txpool, web3, rpc, reth, ots, flashbots, miner, mev, testing]

      --ipcdisable
          Disable the IPC-RPC server

      --ipcpath <IPCPATH>
          Filename for IPC socket/pipe within the datadir

          [default: <CACHE_DIR>.ipc]

      --ipc.permissions <IPC_SOCKET_PERMISSIONS>
          Set the permissions for the IPC socket file, in octal format.

          If not specified, the permissions will be set by the system's umask.

      --authrpc.addr <AUTH_ADDR>
          Auth server address to listen on

          [default: 127.0.0.1]

      --authrpc.port <AUTH_PORT>
          Auth server port to listen on

          [default: 8551]

      --authrpc.jwtsecret <PATH>
          Path to a JWT secret to use for the authenticated engine-API RPC server.

          This will enforce JWT authentication for all requests coming from the consensus layer.

          If no path is provided, a secret will be generated and stored in the datadir under `<DIR>/<CHAIN_ID>/jwt.hex`. For mainnet this would be `~/.local/share/reth/mainnet/jwt.hex` by default.

      --auth-ipc
          Enable auth engine API over IPC

      --auth-ipc.path <AUTH_IPC_PATH>
          Filename for auth IPC socket/pipe within the datadir

          [default: <CACHE_DIR>_engine_api.ipc]

      --disable-auth-server
          Disable the auth/engine API server.

          This will prevent the authenticated engine-API server from starting. Use this if you're running a node that doesn't need to serve engine API requests.

      --rpc.jwtsecret <HEX>
          Hex encoded JWT secret to authenticate the regular RPC server(s), see `--http.api` and `--ws.api`.

          This is __not__ used for the authenticated engine-API RPC server, see `--authrpc.jwtsecret`.

      --rpc.disable-metrics
          Disable built-in RPC request metrics

      --rpc.max-request-size <RPC_MAX_REQUEST_SIZE>
          Set the maximum RPC request payload size for both HTTP and WS in megabytes

          [default: 15]

      --rpc.max-response-size <RPC_MAX_RESPONSE_SIZE>
          Set the maximum RPC response payload size for both HTTP and WS in megabytes

          [default: 160]
          [aliases: --rpc.returndata.limit]

      --rpc.max-subscriptions-per-connection <RPC_MAX_SUBSCRIPTIONS_PER_CONNECTION>
          Set the maximum concurrent subscriptions per connection

          [default: 1024]

      --rpc.max-connections <COUNT>
          Maximum number of RPC server connections

          [default: 500]

      --rpc.max-tracing-requests <COUNT>
          Maximum number of concurrent tracing requests.

          By default this chooses a sensible value based on the number of available cores. Tracing requests are generally CPU bound. Choosing a value that is higher than the available CPU cores can have a negative impact on the performance of the node and affect the node's ability to maintain sync.

          [default: <NUM CPU CORES-2>]

      --rpc.max-blocking-io-requests <COUNT>
          Maximum number of concurrent blocking IO requests.

          Blocking IO requests include `eth_call`, `eth_estimateGas`, and similar methods that require EVM execution. These are spawned as blocking tasks to avoid blocking the async runtime.

          [default: 256]

      --rpc.max-trace-filter-blocks <COUNT>
          Maximum number of blocks for `trace_filter` requests

          [default: 100]

      --rpc.max-blocks-per-filter <COUNT>
          Maximum number of blocks that could be scanned per filter request. (0 = entire chain)

          [default: 100000]

      --rpc.max-logs-per-response <COUNT>
          Maximum number of logs that can be returned in a single response. (0 = no limit)

          [default: 20000]

      --rpc.gascap <GAS_CAP>
          Maximum gas limit for `eth_call` and call tracing RPC methods

          [default: 50000000]

      --rpc.evm-memory-limit <MEMORY_LIMIT>
          Maximum memory the EVM can allocate per RPC request

          [default: 4294967295]

      --rpc.txfeecap <TX_FEE_CAP>
          Maximum eth transaction fee (in ether) that can be sent via the RPC APIs (0 = no cap)

          [default: 1.0]

      --rpc.max-simulate-blocks <BLOCKS_COUNT>
          Maximum number of blocks for `eth_simulateV1` call

          [default: 256]

      --rpc.compute-state-root-for-eth-simulate
          Compute state roots for `eth_simulateV1` responses

          [env: RETH_RPC_COMPUTE_STATE_ROOT_FOR_ETH_SIMULATE=]

      --rpc.eth-proof-window <RPC_ETH_PROOF_WINDOW>
          The maximum proof window for historical proof generation. This value allows for generating historical proofs up to configured number of blocks from current tip (up to `tip - window`)

          [default: 0]

      --rpc.proof-permits <COUNT>
          Maximum number of concurrent getproof requests

          [default: 25]

      --rpc.pending-block <KIND>
          Configures the pending block behavior for RPC responses.

          Options: full (include all transactions), empty (header only), none (disable pending blocks).

          [default: full]

      --rpc.forwarder <FORWARDER>
          Endpoint to forward transactions to

      --builder.disallow <PATH>
          Path to file containing disallowed addresses, json-encoded list of strings. Block validation API will reject blocks containing transactions from these addresses

RPC State Cache:
      --rpc-cache.max-blocks <MAX_BLOCKS>
          Max number of blocks in cache

          [default: 5000]

      --rpc-cache.max-receipts <MAX_RECEIPTS>
          Max number receipts in cache

          [default: 2000]

      --rpc-cache.max-headers <MAX_HEADERS>
          Max number of headers in cache

          [default: 1000]

      --rpc-cache.max-bals <MAX_BALS>
          Max number of revm block access lists in cache

          [default: 1000]

      --rpc-cache.max-concurrent-db-requests <MAX_CONCURRENT_DB_REQUESTS>
          Max number of concurrent database requests

          [default: 512]

      --rpc-cache.max-cached-tx-hashes <MAX_CACHED_TX_HASHES>
          Maximum number of transaction hashes to cache for transaction lookups

          [default: 30000]

Gas Price Oracle:
      --gpo.blocks <BLOCKS>
          Number of recent blocks to check for gas price

          [default: 20]

      --gpo.ignoreprice <IGNORE_PRICE>
          Gas Price below which gpo will ignore transactions

          [default: 0]

      --gpo.maxprice <MAX_PRICE>
          Maximum transaction priority fee(or gasprice before London Fork) to be recommended by gpo

          [default: 500000000000]

      --gpo.percentile <PERCENTILE>
          The percentile of gas prices to use for the estimate

          [default: 60]

      --gpo.default-suggested-fee <DEFAULT_SUGGESTED_FEE>
          The default gas price to use if there are no blocks to use

      --rpc.send-raw-transaction-sync-timeout <SECONDS>
          Timeout for `send_raw_transaction_sync` RPC method

          [default: 30s]

      --testing.skip-invalid-transactions
          Skip invalid transactions in `testing_buildBlockV1` instead of failing.

          When enabled, transactions that fail execution will be skipped, and all subsequent transactions from the same sender will also be skipped.

      --rpc.force-blob-sidecar-upcasting
          Force upcasting EIP-4844 blob sidecars to EIP-7594 format when Osaka is active.

          When enabled, blob transactions submitted via `eth_sendRawTransaction` with EIP-4844 sidecars will be automatically converted to EIP-7594 format if the next block is Osaka. By default this is disabled, meaning transactions are submitted as-is.

TxPool:
      --txpool.pending-max-count <PENDING_MAX_COUNT>
          Max number of transactions in the pending sub-pool

          [default: 10000]

      --txpool.pending-max-size <PENDING_MAX_SIZE>
          Max size of the pending sub-pool in megabytes

          [default: 20]

      --txpool.basefee-max-count <BASEFEE_MAX_COUNT>
          Max number of transactions in the basefee sub-pool

          [default: 10000]

      --txpool.basefee-max-size <BASEFEE_MAX_SIZE>
          Max size of the basefee sub-pool in megabytes

          [default: 20]

      --txpool.queued-max-count <QUEUED_MAX_COUNT>
          Max number of transactions in the queued sub-pool

          [default: 10000]

      --txpool.queued-max-size <QUEUED_MAX_SIZE>
          Max size of the queued sub-pool in megabytes

          [default: 20]

      --txpool.blobpool-max-count <BLOBPOOL_MAX_COUNT>
          Max number of transactions in the blobpool

          [default: 10000]

      --txpool.blobpool-max-size <BLOBPOOL_MAX_SIZE>
          Max size of the blobpool in megabytes

          [default: 20]

      --txpool.blob-cache-size <BLOB_CACHE_SIZE>
          Max number of entries for the in memory cache of the blob store

      --txpool.disable-blobs-support
          Disable EIP-4844 blob transaction support

      --txpool.max-account-slots <MAX_ACCOUNT_SLOTS>
          Max number of executable transaction slots guaranteed per account

          [default: 16]

      --txpool.pricebump <PRICE_BUMP>
          Price bump (in %) for the transaction pool underpriced check

          [default: 10]

      --txpool.minimal-protocol-fee <MINIMAL_PROTOCOL_BASEFEE>
          Minimum base fee required by the protocol

          [default: 7]

      --txpool.minimum-priority-fee <MINIMUM_PRIORITY_FEE>
          Minimum priority fee required for transaction acceptance into the pool. Transactions with priority fee below this value will be rejected

      --txpool.gas-limit <ENFORCED_GAS_LIMIT>
          The default enforced gas limit for transactions entering the pool

          [default: 30000000]

      --txpool.max-tx-gas <MAX_TX_GAS_LIMIT>
          Maximum gas limit for individual transactions. Transactions exceeding this limit will be rejected by the transaction pool

      --blobpool.pricebump <BLOB_TRANSACTION_PRICE_BUMP>
          Price bump percentage to replace an already existing blob transaction

          [default: 100]

      --txpool.max-tx-input-bytes <MAX_TX_INPUT_BYTES>
          Max size in bytes of a single transaction allowed to enter the pool

          [default: 131072]

      --txpool.max-cached-entries <MAX_CACHED_ENTRIES>
          The maximum number of blobs to keep in the in memory blob cache

          [default: 100]

      --txpool.nolocals
          Flag to disable local transaction exemptions

      --txpool.locals <LOCALS>
          Flag to allow certain addresses as local

      --txpool.no-local-transactions-propagation
          Flag to toggle local transaction propagation

      --txpool.additional-validation-tasks <ADDITIONAL_VALIDATION_TASKS>
          Number of additional transaction validation tasks to spawn

          [default: 1]

      --txpool.max-pending-txns <PENDING_TX_LISTENER_BUFFER_SIZE>
          Maximum number of pending transactions from the network to buffer

          [default: 2048]

      --txpool.max-new-txns <NEW_TX_LISTENER_BUFFER_SIZE>
          Maximum number of new transactions to buffer

          [default: 1024]

      --txpool.max-new-pending-txs-notifications <MAX_NEW_PENDING_TXS_NOTIFICATIONS>
          How many new pending transactions to buffer and send to in progress pending transaction iterators

          [default: 200]

      --txpool.lifetime <DURATION>
          Maximum amount of time non-executable transaction are queued

          [default: 10800]

      --txpool.transactions-backup <PATH>
          Path to store the local transaction backup at, to survive node restarts

      --txpool.disable-transactions-backup
          Disables transaction backup to disk on node shutdown

      --txpool.max-batch-size <MAX_BATCH_SIZE>
          Max batch size for transaction pool insertions

          [default: 1]

Builder:
      --builder.extradata <EXTRA_DATA>
          Block extra data set by the payload builder.

          If the value is a `0x`-prefixed hex string, it is decoded into raw bytes. Otherwise, the raw UTF-8 bytes of the string are used.

          [default: reth/<VERSION>/<OS>]

      --builder.gaslimit <GAS_LIMIT>
          Target gas limit for built blocks

      --builder.interval <DURATION>
          The interval at which the job should build a new payload after the last.

          Interval is specified in seconds or in milliseconds if the value ends with `ms`: * `50ms` -> 50 milliseconds * `1` -> 1 second

          [default: 1]

      --builder.deadline <SECONDS>
          The deadline for when the payload builder job should resolve

          [default: 12]

      --builder.max-tasks <MAX_PAYLOAD_TASKS>
          Maximum number of tasks to spawn for building a payload

          [default: 3]

      --builder.max-blobs <COUNT>
          Maximum number of blobs to include per block

Debug:
      --debug.terminate
          Flag indicating whether the node should be terminated after the pipeline sync

      --debug.tip <TIP>
          Set the chain tip manually for testing purposes.

          NOTE: This is a temporary flag

      --debug.max-block <MAX_BLOCK>
          Runs the sync only up to the specified block

      --debug.etherscan [<ETHERSCAN_API_URL>]
          Runs a fake consensus client that advances the chain using recent block hashes on Etherscan. If specified, requires an `ETHERSCAN_API_KEY` environment variable

      --debug.rpc-consensus-url <RPC_URL>
          Runs a fake consensus client using blocks fetched from an RPC endpoint. Supports both HTTP and `WebSocket` endpoints - `WebSocket` endpoints will use subscriptions, while HTTP endpoints will poll for new blocks

      --debug.skip-fcu <SKIP_FCU>
          If provided, the engine will skip `n` consecutive FCUs

      --debug.skip-new-payload <SKIP_NEW_PAYLOAD>
          If provided, the engine will skip `n` consecutive new payloads

      --debug.skip-genesis-validation
          If set, bypasses genesis hash validation during init. Intended for tools that direct-write the database (e.g. snapshot importers, state-actor) and want reth to trust the DB-resident genesis state instead of recomputing it from the chainspec's alloc. When the bypass fires, a structured `tracing::warn!` is emitted so the divergence stays observable in operator logs

      --debug.reorg-frequency <REORG_FREQUENCY>
          If provided, the chain will be reorged at specified frequency

      --debug.reorg-depth <REORG_DEPTH>
          The reorg depth for chain reorgs

      --debug.engine-api-store <PATH>
          The path to store engine API messages at. If specified, all of the intercepted engine API messages will be written to specified location

      --debug.invalid-block-hook <INVALID_BLOCK_HOOK>
          Determines which type of invalid block hook to install

          Example: `witness,prestate`

          [default: witness]
          [possible values: witness, pre-state, opcode]

      --debug.healthy-node-rpc-url <URL>
          The RPC URL of a healthy node to use for comparing invalid block hook results against.

          Debug setting that enables execution witness comparison for troubleshooting bad blocks.
          When enabled, the node will collect execution witnesses from the specified source and
          compare them against local execution when a bad block is encountered, helping identify
          discrepancies in state execution.

      --ethstats <ETHSTATS>
          The URL of the ethstats server to connect to. Example: `nodename:secret@host:port`

      --debug.startup-sync-state-idle
          Set the node to idle state when the backfill is not running.

          This makes the `eth_syncing` RPC return "Idle" when the node has just started or finished the backfill, but did not yet receive any new blocks.

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Dev testnet:
      --dev
          Start the node in dev mode

          This mode uses a local proof-of-authority consensus engine with either fixed block times
          or automatically mined blocks.
          Disables network discovery and enables local http server.
          Prefunds 20 accounts derived by mnemonic "test test test test test test test test test test
          test junk" with 10 000 ETH each.

      --dev.block-max-transactions <BLOCK_MAX_TRANSACTIONS>
          How many transactions to mine per block

      --dev.block-time <BLOCK_TIME>
          Interval between blocks.

          Parses strings using [`humantime::parse_duration`]
          --dev.block-time 12s

      --dev.payload-wait-time <PAYLOAD_WAIT_TIME>
          Time to wait after initiating payload building before resolving.

          Introduces a sleep between `fork_choice_updated` and `resolve_kind` in the
          local miner, giving the payload job time for multiple rebuild attempts with
          new transactions from the pool.

          Parses strings using [`humantime::parse_duration`]
          --dev.payload-wait-time 450ms

      --dev.mnemonic <MNEMONIC>
          Derive dev accounts from a fixed mnemonic instead of random ones.

          [default: "test test test test test test test test test test test junk"]

Pruning:
      --full
          Run full node. Only the most recent [`MINIMUM_UNWIND_SAFE_DISTANCE`] block states are stored

      --minimal
          Run minimal storage mode with maximum pruning and smaller static files.

          This mode configures the node to use minimal disk space by: - Fully pruning sender recovery, transaction lookup, receipts - Leaving 10,064 blocks for account, storage history and block bodies - Using 10,000 blocks per static file segment

      --prune.block-interval <BLOCK_INTERVAL>
          Minimum pruning interval measured in blocks

      --prune.sender-recovery.full
          Prunes all sender recovery data

      --prune.sender-recovery.distance <BLOCKS>
          Prune sender recovery data before the `head-N` block number. In other words, keep last N + 1 blocks

      --prune.sender-recovery.before <BLOCK_NUMBER>
          Prune sender recovery data before the specified block number. The specified block number is not pruned

      --prune.transaction-lookup.full
          Prunes all transaction lookup data

      --prune.transaction-lookup.distance <BLOCKS>
          Prune transaction lookup data before the `head-N` block number. In other words, keep last N + 1 blocks

      --prune.transaction-lookup.before <BLOCK_NUMBER>
          Prune transaction lookup data before the specified block number. The specified block number is not pruned

      --prune.receipts.full
          Prunes all receipt data

      --prune.receipts.pre-merge
          Prune receipts before the merge block

      --prune.receipts.distance <BLOCKS>
          Prune receipts before the `head-N` block number. In other words, keep last N + 1 blocks

      --prune.receipts.before <BLOCK_NUMBER>
          Prune receipts before the specified block number. The specified block number is not pruned

      --prune.receiptslogfilter <FILTER_CONFIG>
          Configure receipts log filter. Format: <`address`>:<`prune_mode`>... where <`prune_mode`> can be 'full', 'distance:<`blocks`>', or 'before:<`block_number`>'

      --prune.account-history.full
          Prunes all account history

      --prune.account-history.distance <BLOCKS>
          Prune account before the `head-N` block number. In other words, keep last N + 1 blocks

      --prune.account-history.before <BLOCK_NUMBER>
          Prune account history before the specified block number. The specified block number is not pruned

      --prune.storage-history.full
          Prunes all storage history data

      --prune.storage-history.distance <BLOCKS>
          Prune storage history before the `head-N` block number. In other words, keep last N + 1 blocks

      --prune.storage-history.before <BLOCK_NUMBER>
          Prune storage history before the specified block number. The specified block number is not pruned

      --prune.bodies.pre-merge
          Prune bodies before the merge block

      --prune.bodies.distance <BLOCKS>
          Prune bodies before the `head-N` block number. In other words, keep last N + 1 blocks

      --prune.bodies.before <BLOCK_NUMBER>
          Prune storage history before the specified block number. The specified block number is not pruned

      --prune.minimum-distance <BLOCKS>
          Minimum pruning distance from the tip. This controls the safety margin for reorgs and manual unwinds

Engine:
      --engine.persistence-threshold <PERSISTENCE_THRESHOLD>
          Configure persistence threshold for the engine. This determines how many canonical blocks must be in-memory, ahead of the last persisted block, before flushing canonical blocks to disk again.

          To persist blocks as fast as the node receives them, set this value to zero. This will cause more frequent DB writes.

          [default: 2]

      --engine.persistence-backpressure-threshold <PERSISTENCE_BACKPRESSURE_THRESHOLD>
          Configure the maximum canonical-minus-persisted gap before engine API processing stalls.

          If omitted, this defaults to the larger of the default backpressure threshold and twice `--engine.persistence-threshold`.

          This value must be greater than `--engine.persistence-threshold`.

      --engine.memory-block-buffer-target <MEMORY_BLOCK_BUFFER_TARGET>
          Configure the target number of blocks to keep in memory

          [default: 0]

      --engine.invalid-header-cache-hit-eviction-threshold <INVALID_HEADER_HIT_EVICTION_THRESHOLD>
          Configure how many cache hits an invalid header can accumulate before it is evicted and reprocessed.

          Set to `0` to effectively disable the cache because entries are evicted on the first lookup.

          [default: 128]

      --engine.disable-state-cache
          Disable state cache

      --engine.disable-prewarming
          Disable parallel prewarming

      --engine.state-provider-metrics
          Enable state provider latency metrics. This allows the engine to collect and report stats about how long state provider calls took during execution, but this does introduce slight overhead to state provider calls

      --engine.cross-block-cache-size <CROSS_BLOCK_CACHE_SIZE>
          Configure the size of cross-block cache in megabytes

          [default: 4096]

      --engine.state-root-task-compare-updates
          Enable comparing trie updates from the state root task to the trie updates from the regular state root calculation

      --engine.accept-execution-requests-hash
          Enables accepting requests hash instead of an array of requests in `engine_newPayloadV4`

      --engine.multiproof-chunk-size <MULTIPROOF_CHUNK_SIZE>
          Multiproof task chunk size for proof targets

          [default: 5]

      --engine.reserved-cpu-cores <RESERVED_CPU_CORES>
          Configure the number of reserved CPU cores for non-reth processes

          [default: 1]

      --engine.disable-precompile-cache
          Disable precompile cache

      --engine.state-root-fallback
          Enable state root fallback, useful for testing

      --engine.always-process-payload-attributes-on-canonical-head
          Always process payload attributes and begin a payload build process even if `forkchoiceState.headBlockHash` is already the canonical head or an ancestor. See `TreeConfig::always_process_payload_attributes_on_canonical_head` for more details.

          Note: This is a no-op on OP Stack.

      --engine.allow-unwind-canonical-header
          Allow unwinding canonical header to ancestor during forkchoice updates. See `TreeConfig::unwind_canonical_header` for more details

      --engine.storage-worker-count <STORAGE_WORKER_COUNT>
          Configure the number of storage proof workers in the Tokio blocking pool. If not specified, defaults to 2x available parallelism

      --engine.account-worker-count <ACCOUNT_WORKER_COUNT>
          Configure the number of account proof workers in the Tokio blocking pool. If not specified, defaults to the same count as storage workers

      --engine.prewarming-threads <PREWARMING_THREADS>
          Configure the number of prewarming threads. If not specified, defaults to available parallelism

      --engine.disable-cache-metrics
          Disable cache metrics recording, which can take up to 50ms with large cached state

      --engine.sparse-trie-max-hot-slots <SPARSE_TRIE_MAX_HOT_SLOTS>
          LFU hot-slot capacity: max storage slots retained across sparse trie prune cycles

          [default: 1500]

      --engine.sparse-trie-max-hot-accounts <SPARSE_TRIE_MAX_HOT_ACCOUNTS>
          LFU hot-account capacity: max account addresses retained across sparse trie prune cycles

          [default: 1000]

      --engine.slow-block-threshold <DURATION>
          Configure the slow block logging threshold in milliseconds.

          When set, blocks that take longer than this threshold to execute will be logged with detailed metrics including timing, state operations, and cache statistics.

          Set to 0 to log all blocks (useful for debugging/profiling).

          When not set, slow block logging is disabled (default).

      --engine.disable-sparse-trie-cache-pruning
          Fully disable sparse trie cache pruning. When set, the cached sparse trie is preserved without any node pruning or storage trie eviction between blocks. Useful for benchmarking the effects of retaining the full trie cache

      --engine.state-root-task-timeout <STATE_ROOT_TASK_TIMEOUT>
          Configure the timeout for the state root task before spawning a sequential fallback. If the state root task takes longer than this, a sequential computation starts in parallel and whichever finishes first is used.

          --engine.state-root-task-timeout 4s --engine.state-root-task-timeout 400ms

          Set to 0s to disable.

          [default: 4s]

      --engine.share-execution-cache-with-payload-builder
          Whether to share execution cache with the payload builder.

          When enabled, each payload job will get an instance of cross-block execution cache from the engine.

          Note: this should only be enabled if node would not be requested to process any payloads in parallel with payload building.

      --engine.share-sparse-trie-with-payload-builder
          Whether to share the sparse trie with the payload builder.

          Replaces the payload builder's blocking `state_root_with_updates()` call with the sparse trie, computing the state root concurrently with transaction execution.

          The engine and payload builder contend for the same trie — if a builder task is still running when `newPayload` arrives, the engine will block until the trie is stored back.

          The builder also anchors the trie at the built block's state root, so if the next `newPayload` is not on top of that block, the trie cache is invalidated and cleared.

      --engine.suppress-persistence-during-build
          Suppress persistence while building a payload.

          When enabled, persistence cycles are deferred from the moment an FCU with payload attributes arrives until the next FCU clears the build. Useful on chains with short block times where persistence I/O can interfere with block building latency.

      --engine.disable-bal-parallel-execution
          Disable BAL (Block Access List, EIP-7928) based parallel execution

      --engine.disable-bal-parallel-state-root
          Disable BAL-driven parallel state root computation. This is only valid together with `--engine.disable-bal-parallel-execution`

      --engine.disable-bal-batch-io
          Disable BAL (Block Access List) storage prefetch IO during prewarming. When set, BAL storage slots are not read into the execution cache

ERA:
      --era.enable
          Enable import from ERA1 files

      --era.path <ERA_PATH>
          The path to a directory for import.

          The ERA1 files are read from the local directory parsing headers and bodies.

      --era.url <ERA_URL>
          The URL to a remote host where the ERA1 files are hosted.

          The ERA1 files are read from the remote host using HTTP GET requests parsing headers
          and bodies.

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

JIT:
      --jit
          Enable JIT compilation of EVM bytecode

      --jit.hot-threshold <HOT_THRESHOLD>
          Number of observed misses before a bytecode is promoted to JIT compilation

          [default: 8]

      --jit.worker-count <WORKER_COUNT>
          Number of JIT compilation worker threads

      --jit.channel-capacity <CHANNEL_CAPACITY>
          Capacity of the lookup-observed event channel. Events are silently dropped when the channel is full

          [default: 4096]

      --jit.max-pending-jobs <MAX_PENDING_JOBS>
          Maximum number of pending JIT compilation jobs

          [default: 2048]

      --jit.max-bytecode-len <MAX_BYTECODE_LEN>
          Maximum bytecode length eligible for JIT compilation. Contracts with bytecode larger than this are never promoted to JIT. 0 means no limit

          [default: 0]

      --jit.code-cache-bytes <CODE_CACHE_BYTES>
          Maximum total resident compiled code size in bytes. When exceeded, the backend evicts least-recently-used entries. 0 means no limit

          [default: 1073741824]

      --jit.idle-evict-duration <IDLE_EVICT_DURATION>
          Duration after which a compiled program with no lookup hits is evicted

          [default: 1h]

      --jit.debug
          Enable compiler debug dumps.

          IR, assembly, and bytecode are written to `<datadir>/jit/<spec_id>/<code_hash>/` for each compiled contract. Note that this is not ever cleaned up, and has a non negligible performance overhead.

Rollup:
      --rollup.sequencer <SEQUENCER>
          Endpoint for the sequencer mempool (can be both HTTP and WS)

          [aliases: --rollup.sequencer-http, --rollup.sequencer-ws]

      --rollup.disable-tx-pool-gossip
          Disable transaction pool gossip

      --rollup.compute-pending-block
          By default the pending block equals the latest block to save resources and not leak txs from the tx-pool, this flag enables computing of the pending block from the tx-pool instead.

          If `compute_pending_block` is not enabled, the payload builder will use the payload attributes from the latest block. Note that this flag is not yet functional.

      --rollup.discovery.v4
          enables discovery v4 if provided

      --rollup.enable-tx-conditional
          Enable transaction conditional support on sequencer

      --rollup.retain-forwarded-txs
          Retain RPC-submitted transactions in the local pool after forwarding them to the sequencer.

          This flag only has an effect when `rollup.sequencer` is present.

      --rollup.operator-sdm-opt-in <OPERATOR_SDM_OPT_IN>
          Local operator opt-in for SDM `PostExec` production at process boot. The admin RPC (`admin_setOperatorSdmOptIn`) can still toggle it at runtime. Defaults to disabled

          [env: OP_RETH_OPERATOR_SDM_OPT_IN=]
          [default: false]
          [possible values: true, false]

      --rollup.interop-http <INTEROP_HTTP_URL>
          HTTP endpoint(s) for the interop filter, used to validate the interop messages referenced by incoming transactions. Repeat the flag to configure multiple endpoints; each check is fanned out to all of them and combined by quorum agreement (see `--rollup.interop-min-responses`). When none are set, interop transaction validation is disabled: a node that builds blocks will then include transactions carrying invalid interop messages, producing invalid blocks. It is only safe to leave this unset on nodes that do not build blocks

      --rollup.interop-min-responses <INTEROP_MIN_RESPONSES>
          Minimum number of definitive verdicts required to decide an interop check across the configured `--rollup.interop-http` endpoints. A transaction is accepted only when this many endpoints return a definitive verdict and all of them agree it is valid; if they disagree the transaction is rejected.

          Defaults to the number of endpoints (unanimity, fail-closed). Note this means any single unreachable or out-of-sync endpoint blocks ALL interop admission until it recovers, so adding endpoints under the default REDUCES availability. Set a majority quorum (e.g. N/2+1) to tolerate a degraded endpoint while still only accepting on unanimous agreement among responders.

          Disagreement detection is best-effort: once the quorum is reached the remaining endpoints are not awaited, so a slow dissenter beyond the quorum may go unseen.

      --rollup.interop-safety-level <INTEROP_SAFETY_LEVEL>
          Safety level for interop filter validation

          [default: CrossUnsafe]

      --rollup.sequencer-headers <SEQUENCER_HEADERS>
          Optional headers to use when connecting to the sequencer

      --rollup.historicalrpc <HISTORICAL_HTTP_URL>
          RPC endpoint for historical data

      --min-suggested-priority-fee <MIN_SUGGESTED_PRIORITY_FEE>
          Minimum suggested priority fee (tip) in wei, default `1_000_000`

          [default: 1000000]

      --rollup.max-uncompressed-block-size <MAX_UNCOMPRESSED_BLOCK_SIZE>
          Maximum cumulative uncompressed (EIP-2718 encoded) block size in bytes.

          When set, the payload builder stops including mempool transactions once the block's total uncompressed transaction size would exceed this value. This bounds the size of the `engine_getPayload` response so it stays within the limits assumed by consensus-layer clients (e.g. the common 10 MiB JSON payload cap). Unset means no limit.

      --flashblocks-url <FLASHBLOCKS_URL>
          A URL pointing to a secure websocket subscription that streams out flashblocks.

          If given, the flashblocks are received to build pending block. All request with "pending" block tag will use the pending state based on flashblocks.

      --flashblock-consensus
          Enable flashblock consensus client to drive the chain forward

          When enabled, the flashblock consensus client will process flashblock sequences and submit them to the engine API to advance the chain. Requires `flashblocks_url` to be set.

      --proofs-history
          If true, initialize external-proofs exex to save and serve trie nodes to provide proofs faster

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

      --proofs-history.window <PROOFS_HISTORY_WINDOW>
          The window to span blocks for proofs history. Value is the number of blocks. Default is 1 month of blocks based on 2 seconds block time (`30 * 24 * 60 * 60 / 2 = 1_296_000`)

          [default: 1296000]

      --proofs-history.verification-interval <PROOFS_HISTORY_VERIFICATION_INTERVAL>
          Verification interval: perform full block execution every N blocks for data integrity. - 0: Disabled (Default) (always use fast path with pre-computed data from notifications) - 1: Always verify (always execute blocks, slowest) - N: Verify every Nth block (e.g., 100 = every 100 blocks)

          Periodic verification helps catch data corruption or consensus bugs while maintaining good performance.

          CLI: `--proofs-history.verification-interval 100`

          [default: 0]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p



P2P Debugging utilities

```bash theme={null}
$ op-reth p2p --help
```

```txt theme={null}
Usage: op-reth p2p [OPTIONS] <COMMAND>

Commands:
  header    Download block header
  body      Download block body
  rlpx      RLPx commands
  bootnode  Bootnode command
  enode     Print enode identifier
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p body
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p/body



Download block body

```bash theme={null}
$ op-reth p2p body --help
```

```txt theme={null}
Usage: op-reth p2p body [OPTIONS] <ID>

Options:
      --retries <RETRIES>
          The number of retries per request

          [default: 5]

  -h, --help
          Print help (see a summary with '-h')

Networking:
  -d, --disable-discovery
          Disable the discovery service

      --disable-dns-discovery
          Disable the DNS discovery

      --disable-discv4-discovery
          Disable Discv4 discovery

      --disable-discv5-discovery
          Disable Discv5 discovery

      --disable-nat
          Disable Nat discovery

      --discovery.addr <DISCOVERY_ADDR>
          The UDP address to use for devp2p peer discovery version 4.

          If unset and `--net-if.experimental` is used, discv4 binds to the resolved interface address.

          [default: 0.0.0.0]

      --discovery.port <DISCOVERY_PORT>
          The UDP port to use for devp2p peer discovery version 4

          [default: 30303]

      --discovery.v5.addr <DISCOVERY_V5_ADDR>
          The UDP IPv4 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv4

      --discovery.v5.addr.ipv6 <DISCOVERY_V5_ADDR_IPV6>
          The UDP IPv6 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv6

      --discovery.v5.port <DISCOVERY_V5_PORT>
          The UDP IPv4 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv4, or `--discovery.v5.addr` is set

          [default: 9200]

      --discovery.v5.port.ipv6 <DISCOVERY_V5_PORT_IPV6>
          The UDP IPv6 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv6, or `--discovery.addr.ipv6` is set.

          If not provided, discovery V5 defaults to same port as discovery V4 (--discovery.port).

          [default: 9200]

      --discovery.v5.lookup-interval <DISCOVERY_V5_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out periodic lookup queries, for the whole run of the program

          [default: 20]

      --discovery.v5.bootstrap.lookup-interval <DISCOVERY_V5_BOOTSTRAP_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out boost lookup queries, for a fixed number of times, at bootstrap

          [default: 5]

      --discovery.v5.bootstrap.lookup-countdown <DISCOVERY_V5_BOOTSTRAP_LOOKUP_COUNTDOWN>
          The number of times to carry out boost lookup queries at bootstrap

          [default: 200]

      --trusted-peers <TRUSTED_PEERS>
          Comma separated enode URLs of trusted peers for P2P connections.

          --trusted-peers enode://abcd@192.168.0.1:30303

      --trusted-only
          Connect to or accept from trusted peers only

      --bootnodes <BOOTNODES>
          Comma separated enode URLs for P2P discovery bootstrap.

          Will fall back to a network-specific default if not specified.

      --dns-retries <DNS_RETRIES>
          Amount of DNS resolution requests retries to perform when peering

          [default: 0]

      --peers-file <FILE>
          The path to the known peers file. Connected peers are dumped to this file on nodes
          shutdown, and read on startup. Cannot be used with `--no-persist-peers`.

      --identity <IDENTITY>
          Custom node identity

          [default: op-reth/<VERSION>-<SHA>/<ARCH>]

      --p2p-secret-key <PATH>
          Secret key to use for this node.

          This will also deterministically set the peer ID. If not specified, it will be set in the data dir for the chain being used.

      --p2p-secret-key-hex <HEX>
          Hex encoded secret key to use for this node.

          This will also deterministically set the peer ID. Cannot be used together with `--p2p-secret-key`.

      --no-persist-peers
          Do not persist peers.

      --nat <NAT>
          NAT resolution method (any|none|upnp|publicip|extip:\<IP\>)

          [default: any]

      --addr <ADDR>
          Network listening address

          [default: 0.0.0.0]

      --port <PORT>
          Network listening port

          [default: 30303]

      --max-outbound-peers <MAX_OUTBOUND_PEERS>
          Maximum number of outbound peers. default: 100

      --max-inbound-peers <MAX_INBOUND_PEERS>
          Maximum number of inbound peers. default: 30

      --max-peers <COUNT>
          Maximum number of total peers (inbound + outbound).

          Splits peers using approximately 2:1 inbound:outbound ratio. Cannot be used together with `--max-outbound-peers` or `--max-inbound-peers`.

      --max-tx-reqs <COUNT>
          Max concurrent `GetPooledTransactions` requests.

          [default: 130]

      --max-tx-reqs-peer <COUNT>
          Max concurrent `GetPooledTransactions` requests per peer.

          [default: 1]

      --max-seen-tx-history <COUNT>
          Max number of seen transactions to remember per peer.

          Default is 320 transaction hashes.

          [default: 320]

      --max-pending-imports <COUNT>
          Max number of transactions to import concurrently.

          [default: 4096]

      --pooled-tx-response-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions
          to pack in one response.
          Spec'd at 2MiB.

          [default: 2097152]

      --pooled-tx-pack-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions to
          request in one request.

          Since `RLPx` protocol version 68, the byte size of a transaction is shared as metadata in a
          transaction announcement (see `RLPx` specs). This allows a node to request a specific size
          response.

          By default, nodes request only 128 KiB worth of transactions, but should a peer request
          more, up to 2 MiB, a node will answer with more than 128 KiB.

          Default is 128 KiB.

          [default: 131072]

      --max-tx-pending-fetch <COUNT>
          Max capacity of cache of hashes for transactions pending fetch.

          [default: 25600]

      --tx-channel-memory-limit <BYTES>
          Memory limit (in bytes) for the channel that buffers transaction events flowing
          from the network manager to the transactions manager.

          When the budget is exhausted, new events are dropped (see metric
          `total_dropped_tx_events_at_full_capacity`). Acts as a backstop against unbounded
          memory growth under sustained P2P transaction flooding.

          [default: 1073741824]

      --net-if.experimental <IF_NAME>
          Name of network interface used to communicate with peers.

          If flag is set, but no value is passed, the default interface for docker `eth0` is tried. If `--discovery.addr` is left at its default, discv4 will also bind to the resolved interface address.

      --tx-propagation-policy <TX_PROPAGATION_POLICY>
          Transaction Propagation Policy

          The policy determines which peers transactions are gossiped to.

          [default: All]

      --tx-ingress-policy <TX_INGRESS_POLICY>
          Transaction ingress policy

          Determines which peers' transactions are accepted over P2P.

          [default: All]

      --disable-tx-gossip
          Disable transaction pool gossip

          Disables gossiping of transactions in the mempool to peers. This can be omitted for personal nodes, though providers should always opt to enable this flag.

      --tx-propagation-mode <PROPAGATION_MODE>
          Sets the transaction propagation mode by determining how new pending transactions are propagated to other peers in full.

          Examples: sqrt, all, max:10

          [default: sqrt]

      --required-block-hashes <REQUIRED_BLOCK_HASHES>
          Comma separated list of required block hashes or block number=hash pairs. Peers that don't have these blocks will be filtered out. Format: hash or `block_number=hash` (e.g., 23115201=0x1234...)

      --network-id <NETWORK_ID>
          Optional network ID to override the chain specification's network ID for P2P connections

      --eth-max-message-size <BYTES>
          Maximum allowed ETH message size in bytes. Default is 10 MiB

      --netrestrict <NETRESTRICT>
          Restrict network communication to the given IP networks (CIDR masks).

          Comma separated list of CIDR network specifications. Only peers with IP addresses within these ranges will be allowed to connect.

          Example: --netrestrict "192.168.0.0/16,10.0.0.0/8"

      --enforce-enr-fork-id
          Enforce EIP-868 ENR fork ID validation for discovered peers.

          When enabled, peers discovered without a confirmed fork ID are not added to the peer set until their fork ID is verified via EIP-868 ENR request. This filters out peers from other networks that pollute the discovery table.

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use.

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

  <ID>
          The block number or hash

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p bootnode
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p/bootnode



Bootnode command

```bash theme={null}
$ op-reth p2p bootnode --help
```

```txt theme={null}
Usage: op-reth p2p bootnode [OPTIONS]

Options:
      --addr <ADDR>
          Listen address for the bootnode (default: "0.0.0.0:30301")

          [default: 0.0.0.0:30301]

      --p2p-secret-key <PATH>
          Secret key to use for the bootnode.

          This will also deterministically set the peer ID. If a path is provided but no key exists at that path, a new random secret will be generated and stored there. If no path is specified, a new ephemeral random secret will be used.

      --nat <NAT>
          NAT resolution method (any|none|upnp|publicip|extip:\<IP\>).

          Can be repeated with one IPv4 and one IPv6 `extip:<IP>` to advertise a dual-stack discv5 ENR (discv4 binds a single socket and always advertises only the `--addr` family).

          [default: any]

      --v5
          Also run discv5, sharing the discv4 UDP port (`--addr`)

  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p enode
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p/enode



Print enode identifier

```bash theme={null}
$ op-reth p2p enode --help
```

```txt theme={null}
Usage: op-reth p2p enode [OPTIONS] <DISCOVERY_SECRET>

Arguments:
  <DISCOVERY_SECRET>
          Path to the secret key file for discovery

Options:
      --ip <IP>
          Optional IP address to include in the enode URL.

          If not provided, defaults to 0.0.0.0.

  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p header
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p/header



Download block header

```bash theme={null}
$ op-reth p2p header --help
```

```txt theme={null}
Usage: op-reth p2p header [OPTIONS] <ID>

Options:
      --retries <RETRIES>
          The number of retries per request

          [default: 5]

  -h, --help
          Print help (see a summary with '-h')

Networking:
  -d, --disable-discovery
          Disable the discovery service

      --disable-dns-discovery
          Disable the DNS discovery

      --disable-discv4-discovery
          Disable Discv4 discovery

      --disable-discv5-discovery
          Disable Discv5 discovery

      --disable-nat
          Disable Nat discovery

      --discovery.addr <DISCOVERY_ADDR>
          The UDP address to use for devp2p peer discovery version 4.

          If unset and `--net-if.experimental` is used, discv4 binds to the resolved interface address.

          [default: 0.0.0.0]

      --discovery.port <DISCOVERY_PORT>
          The UDP port to use for devp2p peer discovery version 4

          [default: 30303]

      --discovery.v5.addr <DISCOVERY_V5_ADDR>
          The UDP IPv4 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv4

      --discovery.v5.addr.ipv6 <DISCOVERY_V5_ADDR_IPV6>
          The UDP IPv6 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv6

      --discovery.v5.port <DISCOVERY_V5_PORT>
          The UDP IPv4 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv4, or `--discovery.v5.addr` is set

          [default: 9200]

      --discovery.v5.port.ipv6 <DISCOVERY_V5_PORT_IPV6>
          The UDP IPv6 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv6, or `--discovery.addr.ipv6` is set.

          If not provided, discovery V5 defaults to same port as discovery V4 (--discovery.port).

          [default: 9200]

      --discovery.v5.lookup-interval <DISCOVERY_V5_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out periodic lookup queries, for the whole run of the program

          [default: 20]

      --discovery.v5.bootstrap.lookup-interval <DISCOVERY_V5_BOOTSTRAP_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out boost lookup queries, for a fixed number of times, at bootstrap

          [default: 5]

      --discovery.v5.bootstrap.lookup-countdown <DISCOVERY_V5_BOOTSTRAP_LOOKUP_COUNTDOWN>
          The number of times to carry out boost lookup queries at bootstrap

          [default: 200]

      --trusted-peers <TRUSTED_PEERS>
          Comma separated enode URLs of trusted peers for P2P connections.

          --trusted-peers enode://abcd@192.168.0.1:30303

      --trusted-only
          Connect to or accept from trusted peers only

      --bootnodes <BOOTNODES>
          Comma separated enode URLs for P2P discovery bootstrap.

          Will fall back to a network-specific default if not specified.

      --dns-retries <DNS_RETRIES>
          Amount of DNS resolution requests retries to perform when peering

          [default: 0]

      --peers-file <FILE>
          The path to the known peers file. Connected peers are dumped to this file on nodes
          shutdown, and read on startup. Cannot be used with `--no-persist-peers`.

      --identity <IDENTITY>
          Custom node identity

          [default: op-reth/<VERSION>-<SHA>/<ARCH>]

      --p2p-secret-key <PATH>
          Secret key to use for this node.

          This will also deterministically set the peer ID. If not specified, it will be set in the data dir for the chain being used.

      --p2p-secret-key-hex <HEX>
          Hex encoded secret key to use for this node.

          This will also deterministically set the peer ID. Cannot be used together with `--p2p-secret-key`.

      --no-persist-peers
          Do not persist peers.

      --nat <NAT>
          NAT resolution method (any|none|upnp|publicip|extip:\<IP\>)

          [default: any]

      --addr <ADDR>
          Network listening address

          [default: 0.0.0.0]

      --port <PORT>
          Network listening port

          [default: 30303]

      --max-outbound-peers <MAX_OUTBOUND_PEERS>
          Maximum number of outbound peers. default: 100

      --max-inbound-peers <MAX_INBOUND_PEERS>
          Maximum number of inbound peers. default: 30

      --max-peers <COUNT>
          Maximum number of total peers (inbound + outbound).

          Splits peers using approximately 2:1 inbound:outbound ratio. Cannot be used together with `--max-outbound-peers` or `--max-inbound-peers`.

      --max-tx-reqs <COUNT>
          Max concurrent `GetPooledTransactions` requests.

          [default: 130]

      --max-tx-reqs-peer <COUNT>
          Max concurrent `GetPooledTransactions` requests per peer.

          [default: 1]

      --max-seen-tx-history <COUNT>
          Max number of seen transactions to remember per peer.

          Default is 320 transaction hashes.

          [default: 320]

      --max-pending-imports <COUNT>
          Max number of transactions to import concurrently.

          [default: 4096]

      --pooled-tx-response-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions
          to pack in one response.
          Spec'd at 2MiB.

          [default: 2097152]

      --pooled-tx-pack-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions to
          request in one request.

          Since `RLPx` protocol version 68, the byte size of a transaction is shared as metadata in a
          transaction announcement (see `RLPx` specs). This allows a node to request a specific size
          response.

          By default, nodes request only 128 KiB worth of transactions, but should a peer request
          more, up to 2 MiB, a node will answer with more than 128 KiB.

          Default is 128 KiB.

          [default: 131072]

      --max-tx-pending-fetch <COUNT>
          Max capacity of cache of hashes for transactions pending fetch.

          [default: 25600]

      --tx-channel-memory-limit <BYTES>
          Memory limit (in bytes) for the channel that buffers transaction events flowing
          from the network manager to the transactions manager.

          When the budget is exhausted, new events are dropped (see metric
          `total_dropped_tx_events_at_full_capacity`). Acts as a backstop against unbounded
          memory growth under sustained P2P transaction flooding.

          [default: 1073741824]

      --net-if.experimental <IF_NAME>
          Name of network interface used to communicate with peers.

          If flag is set, but no value is passed, the default interface for docker `eth0` is tried. If `--discovery.addr` is left at its default, discv4 will also bind to the resolved interface address.

      --tx-propagation-policy <TX_PROPAGATION_POLICY>
          Transaction Propagation Policy

          The policy determines which peers transactions are gossiped to.

          [default: All]

      --tx-ingress-policy <TX_INGRESS_POLICY>
          Transaction ingress policy

          Determines which peers' transactions are accepted over P2P.

          [default: All]

      --disable-tx-gossip
          Disable transaction pool gossip

          Disables gossiping of transactions in the mempool to peers. This can be omitted for personal nodes, though providers should always opt to enable this flag.

      --tx-propagation-mode <PROPAGATION_MODE>
          Sets the transaction propagation mode by determining how new pending transactions are propagated to other peers in full.

          Examples: sqrt, all, max:10

          [default: sqrt]

      --required-block-hashes <REQUIRED_BLOCK_HASHES>
          Comma separated list of required block hashes or block number=hash pairs. Peers that don't have these blocks will be filtered out. Format: hash or `block_number=hash` (e.g., 23115201=0x1234...)

      --network-id <NETWORK_ID>
          Optional network ID to override the chain specification's network ID for P2P connections

      --eth-max-message-size <BYTES>
          Maximum allowed ETH message size in bytes. Default is 10 MiB

      --netrestrict <NETRESTRICT>
          Restrict network communication to the given IP networks (CIDR masks).

          Comma separated list of CIDR network specifications. Only peers with IP addresses within these ranges will be allowed to connect.

          Example: --netrestrict "192.168.0.0/16,10.0.0.0/8"

      --enforce-enr-fork-id
          Enforce EIP-868 ENR fork ID validation for discovered peers.

          When enabled, peers discovered without a confirmed fork ID are not added to the peer set until their fork ID is verified via EIP-868 ENR request. This filters out peers from other networks that pollute the discovery table.

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use.

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

  <ID>
          The header number or hash

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p rlpx
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p/rlpx



RLPx commands

```bash theme={null}
$ op-reth p2p rlpx --help
```

```txt theme={null}
Usage: op-reth p2p rlpx [OPTIONS] <COMMAND>

Commands:
  ping  ping node
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth p2p rlpx ping
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/p2p/rlpx/ping



ping node

```bash theme={null}
$ op-reth p2p rlpx ping --help
```

```txt theme={null}
Usage: op-reth p2p rlpx ping [OPTIONS] <NODE>

Arguments:
  <NODE>
          The node to ping

Options:
  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs



Manage storage of historical proofs in expanded trie db in fault proof window

```bash theme={null}
$ op-reth proofs --help
```

```txt theme={null}
Usage: op-reth proofs [OPTIONS] <COMMAND>

Commands:
  init      Initialize the proofs storage with the current state of the chain
  backfill  Backfill proofs history to an older earliest block
  prune     Prune old proof history to reclaim space
  snapshot  Build or drop the trie-state snapshot
  unwind    Unwind the proofs storage to a specific block
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs backfill
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/backfill



Backfill proofs history to an older earliest block

```bash theme={null}
$ op-reth proofs backfill --help
```

```txt theme={null}
Usage: op-reth proofs backfill [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

      --proofs-history.window <PROOFS_HISTORY_WINDOW>
          The window to span blocks for proofs history. Value is the number of blocks. Default is 1 month of blocks based on 2 seconds block time (`30 * 24 * 60 * 60 / 2 = 1_296_000`)

          [default: 1296000]

      --proofs-history.backfill-batch-size <N>
          Number of blocks committed per MDBX write transaction (>= 1).

          Larger N amortizes commit/fsync; trade-off is higher peak RSS and up to N blocks of progress lost on crash. Very large N can also exceed MDBX's per-tx dirty-page ceiling on storage-heavy blocks — the batch fails cleanly (whole tx rolls back) and can be retried with a lower value. Default 25 measured ~2.6× throughput vs K=1 on op-mainnet — the sweet spot on the K sweep before dirty-page pressure starts slowing cursor reads.

          [default: 25]

      --proofs-history.use-snapshot [<BOOL>]
          Use the trie-state snapshot to accelerate per-block reads during backfill. If no snapshot exists, one is bootstrapped at the current `earliest` before the backfill loop begins. Requires v2 storage.

          Defaults to `true`. Pass `--proofs-history.use-snapshot false` to force the non-snapshot path (per-block reads via the reth DB).

          [default: true]
          [possible values: true, false]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs init
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/init



Initialize the proofs storage with the current state of the chain

```bash theme={null}
$ op-reth proofs init --help
```

```txt theme={null}
Usage: op-reth proofs init [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

      --proofs-history.skip-backfill
          Skip the post-init backward backfill. By default, after the snapshot of the current chain state is captured the proof window is extended back by `--proofs-history.window` blocks using the snapshot-accelerated path. Set this flag to leave the window at `[latest, latest]` and run `op-proofs backfill` later instead. No effect on V1 storage (V1 does not support backfill)

      --proofs-history.window <PROOFS_HISTORY_WINDOW>
          The window to span blocks for proofs history. Value is the number of blocks. Default is 1 month of blocks based on 2 seconds block time (`30 * 24 * 60 * 60 / 2 = 1_296_000`)

          [default: 1296000]

      --proofs-history.backfill-batch-size <N>
          Number of blocks committed per MDBX write transaction (>= 1).

          Larger N amortizes commit/fsync; trade-off is higher peak RSS and up to N blocks of progress lost on crash. Very large N can also exceed MDBX's per-tx dirty-page ceiling on storage-heavy blocks — the batch fails cleanly (whole tx rolls back) and can be retried with a lower value. Default 25 measured ~2.6× throughput vs K=1 on op-mainnet — the sweet spot on the K sweep before dirty-page pressure starts slowing cursor reads.

          [default: 25]

      --proofs-history.use-snapshot [<BOOL>]
          Use the trie-state snapshot to accelerate per-block reads during backfill. If no snapshot exists, one is bootstrapped at the current `earliest` before the backfill loop begins. Requires v2 storage.

          Defaults to `true`. Pass `--proofs-history.use-snapshot false` to force the non-snapshot path (per-block reads via the reth DB).

          [default: true]
          [possible values: true, false]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs prune
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/prune



Prune old proof history to reclaim space

```bash theme={null}
$ op-reth proofs prune --help
```

```txt theme={null}
Usage: op-reth proofs prune [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

      --proofs-history.window <PROOFS_HISTORY_WINDOW>
          The window to span blocks for proofs history. Value is the number of blocks. Default is 1 month of blocks based on 2 seconds block time (`30 * 24 * 60 * 60 / 2 = 1_296_000`)

          [default: 1296000]

      --proofs-history.prune-batch-size <PROOFS_HISTORY_PRUNE_BATCH_SIZE>
          The batch size for pruning operations

          [default: 1000]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs snapshot
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/snapshot



Build or drop the trie-state snapshot

```bash theme={null}
$ op-reth proofs snapshot --help
```

```txt theme={null}
Usage: op-reth proofs snapshot [OPTIONS] <COMMAND>

Commands:
  init  Build a snapshot at a target block and mark it Ready
  drop  Drop the snapshot tables and meta row
  help  Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs snapshot drop
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/snapshot/drop



Drop the snapshot tables and meta row

```bash theme={null}
$ op-reth proofs snapshot drop --help
```

```txt theme={null}
Usage: op-reth proofs snapshot drop [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs snapshot init
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/snapshot/init



Build a snapshot at a target block and mark it Ready

```bash theme={null}
$ op-reth proofs snapshot init --help
```

```txt theme={null}
Usage: op-reth proofs snapshot init [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

      --proofs-history.snapshot-target-block <TARGET_BLOCK>
          Target block for the snapshot anchor. Must fall inside the proofs window `[earliest, latest]`. Defaults to `earliest` — that's the anchor the snapshot-accelerated backfill flow picks up

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth proofs unwind
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/proofs/unwind



Unwind the proofs storage to a specific block

```bash theme={null}
$ op-reth proofs unwind --help
```

```txt theme={null}
Usage: op-reth proofs unwind [OPTIONS] --target <TARGET_BLOCK>

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>
          Path to the proofs-history storage DB. Defaults to `<reth-data-dir>/historical-proofs` (chain-namespaced via reth's `--datadir`)

      --proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>
          Storage schema version. Must match the version used when starting the node

          Possible values:
          - v1: V1 storage schema (original single-table-per-domain layout). Default
          - v2: V2 storage schema with changeset and history-bitmap tables, enabling history-aware reads at any block number within the proof window

          [default: v1]

      --target <TARGET_BLOCK>
          The target block number to unwind to.

          All history *after* this block will be removed.

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth prune
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/prune



Prune according to the configuration without any limits

```bash theme={null}
$ op-reth prune --help
```

```txt theme={null}
Usage: op-reth prune [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

Metrics:
      --metrics <PROMETHEUS>
          Enable Prometheus metrics.

          The metrics will be served at the given interface and port.

      --metrics.prometheus.push.url <PUSH_GATEWAY_URL>
          URL for pushing Prometheus metrics to a push gateway.

          If set, the node will periodically push metrics to the specified push gateway URL.

      --metrics.prometheus.push.interval <SECONDS>
          Interval in seconds for pushing metrics to push gateway.

          Default: 5 seconds

          [default: 5]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth re-execute
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/re-execute



Re-execute blocks in parallel to verify historical sync correctness

```bash theme={null}
$ op-reth re-execute --help
```

```txt theme={null}
Usage: op-reth re-execute [OPTIONS]

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --from <FROM>
          The height to start at

          [default: 1]

      --to <TO>
          The height to end at. Defaults to the latest block

      --num-tasks <NUM_TASKS>
          Number of tasks to run in parallel. Defaults to the number of available CPUs

      --blocks-per-chunk <BLOCKS_PER_CHUNK>
          Number of blocks each worker processes before grabbing the next chunk

          [default: 5000]

      --skip-invalid-blocks
          Continues with execution when an invalid block is encountered and collects these blocks

JIT:
      --jit
          Enable JIT compilation of EVM bytecode

      --jit.hot-threshold <HOT_THRESHOLD>
          Number of observed misses before a bytecode is promoted to JIT compilation

          [default: 8]

      --jit.worker-count <WORKER_COUNT>
          Number of JIT compilation worker threads

      --jit.channel-capacity <CHANNEL_CAPACITY>
          Capacity of the lookup-observed event channel. Events are silently dropped when the channel is full

          [default: 4096]

      --jit.max-pending-jobs <MAX_PENDING_JOBS>
          Maximum number of pending JIT compilation jobs

          [default: 2048]

      --jit.max-bytecode-len <MAX_BYTECODE_LEN>
          Maximum bytecode length eligible for JIT compilation. Contracts with bytecode larger than this are never promoted to JIT. 0 means no limit

          [default: 0]

      --jit.code-cache-bytes <CODE_CACHE_BYTES>
          Maximum total resident compiled code size in bytes. When exceeded, the backend evicts least-recently-used entries. 0 means no limit

          [default: 1073741824]

      --jit.idle-evict-duration <IDLE_EVICT_DURATION>
          Duration after which a compiled program with no lookup hits is evicted

          [default: 1h]

      --jit.debug
          Enable compiler debug dumps.

          IR, assembly, and bytecode are written to `<datadir>/jit/<spec_id>/<code_hash>/` for each compiled contract. Note that this is not ever cleaned up, and has a non negligible performance overhead.

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage



Manipulate individual stages

```bash theme={null}
$ op-reth stage --help
```

```txt theme={null}
Usage: op-reth stage [OPTIONS] <COMMAND>

Commands:
  run     Run a single stage
  drop    Drop a stage's tables from the database
  dump    Dumps a stage from a range into a new database
  unwind  Unwinds a certain block range, deleting it from the database
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage drop
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/drop



Drop a stage's tables from the database

```bash theme={null}
$ op-reth stage drop --help
```

```txt theme={null}
Usage: op-reth stage drop [OPTIONS] <STAGE>

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

  <STAGE>
          Possible values:
          - headers:         The headers stage within the pipeline
          - bodies:          The bodies stage within the pipeline
          - senders:         The senders stage within the pipeline
          - execution:       The execution stage within the pipeline
          - account-hashing: The account hashing stage within the pipeline
          - storage-hashing: The storage hashing stage within the pipeline
          - hashing:         The account and storage hashing stages within the pipeline
          - merkle:          The merkle stage within the pipeline
          - tx-lookup:       The transaction lookup stage within the pipeline
          - account-history: The account history stage within the pipeline
          - storage-history: The storage history stage within the pipeline

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage dump
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/dump



Dumps a stage from a range into a new database

```bash theme={null}
$ op-reth stage dump --help
```

```txt theme={null}
Usage: op-reth stage dump [OPTIONS] <COMMAND>

Commands:
  execution        Execution stage
  storage-hashing  `StorageHashing` stage
  account-hashing  `AccountHashing` stage
  merkle           Merkle stage
  help             Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage dump account-hashing
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/dump/account-hashing



`AccountHashing` stage

```bash theme={null}
$ op-reth stage dump account-hashing --help
```

```txt theme={null}
Usage: op-reth stage dump account-hashing [OPTIONS] --output-datadir <OUTPUT_PATH> --from <FROM> --to <TO>

Options:
      --output-datadir <OUTPUT_PATH>
          The path to the new datadir folder.

  -f, --from <FROM>
          From which block

  -t, --to <TO>
          To which block

  -d, --dry-run
          If passed, it will dry-run a stage execution from the newly created database right after dumping

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage dump execution
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/dump/execution



Execution stage

```bash theme={null}
$ op-reth stage dump execution --help
```

```txt theme={null}
Usage: op-reth stage dump execution [OPTIONS] --output-datadir <OUTPUT_PATH> --from <FROM> --to <TO>

Options:
      --output-datadir <OUTPUT_PATH>
          The path to the new datadir folder.

  -f, --from <FROM>
          From which block

  -t, --to <TO>
          To which block

  -d, --dry-run
          If passed, it will dry-run a stage execution from the newly created database right after dumping

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage dump merkle
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/dump/merkle



Merkle stage

```bash theme={null}
$ op-reth stage dump merkle --help
```

```txt theme={null}
Usage: op-reth stage dump merkle [OPTIONS] --output-datadir <OUTPUT_PATH> --from <FROM> --to <TO>

Options:
      --output-datadir <OUTPUT_PATH>
          The path to the new datadir folder.

  -f, --from <FROM>
          From which block

  -t, --to <TO>
          To which block

  -d, --dry-run
          If passed, it will dry-run a stage execution from the newly created database right after dumping

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage dump storage-hashing
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/dump/storage-hashing



`StorageHashing` stage

```bash theme={null}
$ op-reth stage dump storage-hashing --help
```

```txt theme={null}
Usage: op-reth stage dump storage-hashing [OPTIONS] --output-datadir <OUTPUT_PATH> --from <FROM> --to <TO>

Options:
      --output-datadir <OUTPUT_PATH>
          The path to the new datadir folder.

  -f, --from <FROM>
          From which block

  -t, --to <TO>
          To which block

  -d, --dry-run
          If passed, it will dry-run a stage execution from the newly created database right after dumping

  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage run
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/run



Run a single stage.

```bash theme={null}
$ op-reth stage run --help
```

```txt theme={null}
Usage: op-reth stage run [OPTIONS] --from <FROM> --to <TO> <STAGE>

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --metrics <SOCKET>
          Enable Prometheus metrics.

          The metrics will be served at the given interface and port.

      --from <FROM>
          The height to start at

  -t, --to <TO>
          The end of the stage

      --batch-size <BATCH_SIZE>
          Batch size for stage execution and unwind

  -s, --skip-unwind
          Normally, running the stage requires unwinding for stages that already have been run, in order to not rewrite to the same database slots.

          You can optionally skip the unwinding phase if you're syncing a block range that has not been synced before.

  -c, --commit
          Commits the changes in the database. WARNING: potentially destructive.

          Useful when you want to run diagnostics on the database.

          NOTE: This flag is currently required for the headers, bodies, and execution stages because they use static files and must commit to properly unwind and run.

      --checkpoints
          Save stage checkpoints

  <STAGE>
          The name of the stage to run

          Possible values:
          - headers:         The headers stage within the pipeline
          - bodies:          The bodies stage within the pipeline
          - senders:         The senders stage within the pipeline
          - execution:       The execution stage within the pipeline
          - account-hashing: The account hashing stage within the pipeline
          - storage-hashing: The storage hashing stage within the pipeline
          - hashing:         The account and storage hashing stages within the pipeline
          - merkle:          The merkle stage within the pipeline
          - tx-lookup:       The transaction lookup stage within the pipeline
          - account-history: The account history stage within the pipeline
          - storage-history: The storage history stage within the pipeline

Networking:
  -d, --disable-discovery
          Disable the discovery service

      --disable-dns-discovery
          Disable the DNS discovery

      --disable-discv4-discovery
          Disable Discv4 discovery

      --disable-discv5-discovery
          Disable Discv5 discovery

      --disable-nat
          Disable Nat discovery

      --discovery.addr <DISCOVERY_ADDR>
          The UDP address to use for devp2p peer discovery version 4.

          If unset and `--net-if.experimental` is used, discv4 binds to the resolved interface address.

          [default: 0.0.0.0]

      --discovery.port <DISCOVERY_PORT>
          The UDP port to use for devp2p peer discovery version 4

          [default: 30303]

      --discovery.v5.addr <DISCOVERY_V5_ADDR>
          The UDP IPv4 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv4

      --discovery.v5.addr.ipv6 <DISCOVERY_V5_ADDR_IPV6>
          The UDP IPv6 address to use for devp2p peer discovery version 5. Overwritten by `RLPx` address, if it's also IPv6

      --discovery.v5.port <DISCOVERY_V5_PORT>
          The UDP IPv4 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv4, or `--discovery.v5.addr` is set

          [default: 9200]

      --discovery.v5.port.ipv6 <DISCOVERY_V5_PORT_IPV6>
          The UDP IPv6 port to use for devp2p peer discovery version 5. Not used unless `--addr` is IPv6, or `--discovery.addr.ipv6` is set.

          If not provided, discovery V5 defaults to same port as discovery V4 (--discovery.port).

          [default: 9200]

      --discovery.v5.lookup-interval <DISCOVERY_V5_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out periodic lookup queries, for the whole run of the program

          [default: 20]

      --discovery.v5.bootstrap.lookup-interval <DISCOVERY_V5_BOOTSTRAP_LOOKUP_INTERVAL>
          The interval in seconds at which to carry out boost lookup queries, for a fixed number of times, at bootstrap

          [default: 5]

      --discovery.v5.bootstrap.lookup-countdown <DISCOVERY_V5_BOOTSTRAP_LOOKUP_COUNTDOWN>
          The number of times to carry out boost lookup queries at bootstrap

          [default: 200]

      --trusted-peers <TRUSTED_PEERS>
          Comma separated enode URLs of trusted peers for P2P connections.

          --trusted-peers enode://abcd@192.168.0.1:30303

      --trusted-only
          Connect to or accept from trusted peers only

      --bootnodes <BOOTNODES>
          Comma separated enode URLs for P2P discovery bootstrap.

          Will fall back to a network-specific default if not specified.

      --dns-retries <DNS_RETRIES>
          Amount of DNS resolution requests retries to perform when peering

          [default: 0]

      --peers-file <FILE>
          The path to the known peers file. Connected peers are dumped to this file on nodes
          shutdown, and read on startup. Cannot be used with `--no-persist-peers`.

      --identity <IDENTITY>
          Custom node identity

          [default: op-reth/<VERSION>-<SHA>/<ARCH>]

      --p2p-secret-key <PATH>
          Secret key to use for this node.

          This will also deterministically set the peer ID. If not specified, it will be set in the data dir for the chain being used.

      --p2p-secret-key-hex <HEX>
          Hex encoded secret key to use for this node.

          This will also deterministically set the peer ID. Cannot be used together with `--p2p-secret-key`.

      --no-persist-peers
          Do not persist peers.

      --nat <NAT>
          NAT resolution method (any|none|upnp|publicip|extip:\<IP\>)

          [default: any]

      --addr <ADDR>
          Network listening address

          [default: 0.0.0.0]

      --port <PORT>
          Network listening port

          [default: 30303]

      --max-outbound-peers <MAX_OUTBOUND_PEERS>
          Maximum number of outbound peers. default: 100

      --max-inbound-peers <MAX_INBOUND_PEERS>
          Maximum number of inbound peers. default: 30

      --max-peers <COUNT>
          Maximum number of total peers (inbound + outbound).

          Splits peers using approximately 2:1 inbound:outbound ratio. Cannot be used together with `--max-outbound-peers` or `--max-inbound-peers`.

      --max-tx-reqs <COUNT>
          Max concurrent `GetPooledTransactions` requests.

          [default: 130]

      --max-tx-reqs-peer <COUNT>
          Max concurrent `GetPooledTransactions` requests per peer.

          [default: 1]

      --max-seen-tx-history <COUNT>
          Max number of seen transactions to remember per peer.

          Default is 320 transaction hashes.

          [default: 320]

      --max-pending-imports <COUNT>
          Max number of transactions to import concurrently.

          [default: 4096]

      --pooled-tx-response-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions
          to pack in one response.
          Spec'd at 2MiB.

          [default: 2097152]

      --pooled-tx-pack-soft-limit <BYTES>
          Experimental, for usage in research. Sets the max accumulated byte size of transactions to
          request in one request.

          Since `RLPx` protocol version 68, the byte size of a transaction is shared as metadata in a
          transaction announcement (see `RLPx` specs). This allows a node to request a specific size
          response.

          By default, nodes request only 128 KiB worth of transactions, but should a peer request
          more, up to 2 MiB, a node will answer with more than 128 KiB.

          Default is 128 KiB.

          [default: 131072]

      --max-tx-pending-fetch <COUNT>
          Max capacity of cache of hashes for transactions pending fetch.

          [default: 25600]

      --tx-channel-memory-limit <BYTES>
          Memory limit (in bytes) for the channel that buffers transaction events flowing
          from the network manager to the transactions manager.

          When the budget is exhausted, new events are dropped (see metric
          `total_dropped_tx_events_at_full_capacity`). Acts as a backstop against unbounded
          memory growth under sustained P2P transaction flooding.

          [default: 1073741824]

      --net-if.experimental <IF_NAME>
          Name of network interface used to communicate with peers.

          If flag is set, but no value is passed, the default interface for docker `eth0` is tried. If `--discovery.addr` is left at its default, discv4 will also bind to the resolved interface address.

      --tx-propagation-policy <TX_PROPAGATION_POLICY>
          Transaction Propagation Policy

          The policy determines which peers transactions are gossiped to.

          [default: All]

      --tx-ingress-policy <TX_INGRESS_POLICY>
          Transaction ingress policy

          Determines which peers' transactions are accepted over P2P.

          [default: All]

      --disable-tx-gossip
          Disable transaction pool gossip

          Disables gossiping of transactions in the mempool to peers. This can be omitted for personal nodes, though providers should always opt to enable this flag.

      --tx-propagation-mode <PROPAGATION_MODE>
          Sets the transaction propagation mode by determining how new pending transactions are propagated to other peers in full.

          Examples: sqrt, all, max:10

          [default: sqrt]

      --required-block-hashes <REQUIRED_BLOCK_HASHES>
          Comma separated list of required block hashes or block number=hash pairs. Peers that don't have these blocks will be filtered out. Format: hash or `block_number=hash` (e.g., 23115201=0x1234...)

      --network-id <NETWORK_ID>
          Optional network ID to override the chain specification's network ID for P2P connections

      --eth-max-message-size <BYTES>
          Maximum allowed ETH message size in bytes. Default is 10 MiB

      --netrestrict <NETRESTRICT>
          Restrict network communication to the given IP networks (CIDR masks).

          Comma separated list of CIDR network specifications. Only peers with IP addresses within these ranges will be allowed to connect.

          Example: --netrestrict "192.168.0.0/16,10.0.0.0/8"

      --enforce-enr-fork-id
          Enforce EIP-868 ENR fork ID validation for discovered peers.

          When enabled, peers discovered without a confirmed fork ID are not added to the peer set until their fork ID is verified via EIP-868 ENR request. This filters out peers from other networks that pollute the discovery table.

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage unwind
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/unwind



Unwinds a certain block range, deleting it from the database

```bash theme={null}
$ op-reth stage unwind --help
```

```txt theme={null}
Usage: op-reth stage unwind [OPTIONS] <COMMAND>

Commands:
  to-block    Unwinds the database from the latest block, until the given block number or hash has been reached, that block is not included
  num-blocks  Unwinds the database from the latest block, until the given number of blocks have been reached
  help        Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --datadir <DATA_DIR>
          The path to the data dir for all reth files and subdirectories.

          Defaults to the OS-specific data directory:

          - Linux: `$XDG_DATA_HOME/reth/` or `$HOME/.local/share/reth/`
          - Windows: `{FOLDERID_RoamingAppData}/reth/`
          - macOS: `$HOME/Library/Application Support/reth/`

          [default: default]

      --datadir.static-files <PATH>
          The absolute path to store static files in.

      --datadir.rocksdb <PATH>
          The absolute path to store `RocksDB` database in.

      --datadir.pprof-dumps <PATH>
          The absolute path to store pprof dumps in.

      --config <FILE>
          The path to the configuration file to use

      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Database:
      --db.log-level <LOG_LEVEL>
          Database logging level. Levels higher than "notice" require a debug build

          Possible values:
          - fatal:   Enables logging for critical conditions, i.e. assertion failures
          - error:   Enables logging for error conditions
          - warn:    Enables logging for warning conditions
          - notice:  Enables logging for normal but significant condition
          - verbose: Enables logging for verbose informational
          - debug:   Enables logging for debug-level messages
          - trace:   Enables logging for trace debug-level messages
          - extra:   Enables logging for extra debug-level messages

      --db.exclusive <EXCLUSIVE>
          Open environment in exclusive/monopolistic mode. Makes it possible to open a database on an NFS volume

          [possible values: true, false]

      --db.max-size <MAX_SIZE>
          Maximum database size (e.g., 4TB, 8TB).

          This sets the "map size" of the database. If the database grows beyond this limit, the node will stop with an "environment map size limit reached" error.

          The default value is 8TB.

      --db.page-size <PAGE_SIZE>
          Database page size (e.g., 4KB, 8KB, 16KB).

          Specifies the page size used by the MDBX database.

          The page size determines the maximum database size. MDBX supports up to 2^31 pages, so with the default 4KB page size, the maximum database size is 8TB. To allow larger databases, increase this value to 8KB or higher.

          WARNING: This setting is only configurable at database creation; changing it later requires re-syncing.

      --db.growth-step <GROWTH_STEP>
          Database growth step (e.g., 4GB, 4KB)

      --db.read-transaction-timeout <READ_TRANSACTION_TIMEOUT>
          Read transaction timeout in seconds, 0 means no timeout

      --db.max-readers <MAX_READERS>
          Maximum number of readers allowed to access the database concurrently

      --db.sync-mode <SYNC_MODE>
          Controls how aggressively the database synchronizes data to disk

      --db.rocksdb-block-cache-size <ROCKSDB_BLOCK_CACHE_SIZE>
          `RocksDB` block cache size (e.g., 512MB, 4GB).

          Controls the size of the in-memory LRU cache for decompressed `RocksDB` blocks. A larger cache reduces repeated decompression of hot blocks, improving read performance for history lookups.

      --db.balstore-cache-size <BALSTORE_CACHE_SIZE>
          Number of recent blocks to keep in the in-memory BAL store cache

      --db.disable-metrics
          Disable built-in database metrics

Static Files:
      --static-files.blocks-per-file.headers <BLOCKS_PER_FILE_HEADERS>
          Number of blocks per file for the headers segment

      --static-files.blocks-per-file.transactions <BLOCKS_PER_FILE_TRANSACTIONS>
          Number of blocks per file for the transactions segment

      --static-files.blocks-per-file.receipts <BLOCKS_PER_FILE_RECEIPTS>
          Number of blocks per file for the receipts segment

      --static-files.blocks-per-file.transaction-senders <BLOCKS_PER_FILE_TRANSACTION_SENDERS>
          Number of blocks per file for the transaction senders segment

      --static-files.blocks-per-file.account-change-sets <BLOCKS_PER_FILE_ACCOUNT_CHANGE_SETS>
          Number of blocks per file for the account changesets segment

      --static-files.blocks-per-file.storage-change-sets <BLOCKS_PER_FILE_STORAGE_CHANGE_SETS>
          Number of blocks per file for the storage changesets segment

Storage:
      --storage.v2 [<V2>]
          Enable V2 (hot/cold) storage layout for new databases.

          When set, new databases will be initialized with the V2 storage layout that separates hot and cold data. Existing databases always use the settings persisted in their metadata regardless of this flag.

          [default: true]
          [possible values: true, false]

      --offline
          If this is enabled, then all stages except headers, bodies, and sender recovery will be unwound

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage unwind num-blocks
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/unwind/num-blocks



Unwinds the database from the latest block, until the given number of blocks have been reached

```bash theme={null}
$ op-reth stage unwind num-blocks --help
```

```txt theme={null}
Usage: op-reth stage unwind num-blocks [OPTIONS] <AMOUNT>

Arguments:
  <AMOUNT>


Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# op-reth stage unwind to-block
Source: https://docs.optimism.io/node-operators/op-reth/cli/op-reth/stage/unwind/to-block



Unwinds the database from the latest block, until the given block number or hash has been reached, that block is not included

```bash theme={null}
$ op-reth stage unwind to-block --help
```

```txt theme={null}
Usage: op-reth stage unwind to-block [OPTIONS] <TARGET>

Arguments:
  <TARGET>


Options:
  -h, --help
          Print help (see a summary with '-h')

Datadir:
      --chain <CHAIN_OR_PATH>
          The chain this node is running.
          Possible values are either a built-in chain or the path to a chain specification file.

          Built-in chains:
              optimism, op-mainnet, optimism_sepolia, optimism-sepolia, automata, bob, boba, celo, cyber, ethernity, fraxtal, funki, hashkeychain, ink, lisk, lyra, metal, mint, mode, op, orderly, polynomial, race, redstone, settlus-mainnet, shape, silent-data-mainnet, soneium, sseed, swan, tbn, unichain, worldchain, xterio-eth, zora, boba-sepolia, camp-sepolia, celo-sep-sepolia, cyber-sepolia, funki-sepolia, ink-sepolia, lisk-sepolia, metal-sepolia, mode-sepolia, op-sepolia, ozean-sepolia, pivotal-sepolia, race-sepolia, radius_testnet-sepolia, settlus-sepolia-sepolia, shape-sepolia, soneium-minato-sepolia, tbn-sepolia, unichain-sepolia, worldchain-sepolia, zora-sepolia, oplabs-devnet-0-sepolia-dev-0, sepolia-devnet-2-sepolia-devnet-2, dev

          [default: optimism]

Logging:
      --log.stdout.format <FORMAT>
          The format to use for logs written to stdout

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.stdout.filter <FILTER>
          The filter to use for logs written to stdout

          [default: ""]

      --log.file.format <FORMAT>
          The format to use for logs written to the log file

          Possible values:
          - json:     Represents JSON formatting for logs. This format outputs log records as JSON objects, making it suitable for structured logging
          - log-fmt:  Represents logfmt (key=value) formatting for logs. This format is concise and human-readable, typically used in command-line applications
          - terminal: Represents terminal-friendly formatting for logs

          [default: terminal]

      --log.file.filter <FILTER>
          The filter to use for logs written to the log file

          [default: debug]

      --log.file.directory <PATH>
          The path to put log files in

          [default: <CACHE_DIR>/logs]

      --log.file.name <NAME>
          The prefix name of the log files

          [default: reth.log]

      --log.file.max-size <SIZE>
          The maximum size (in MB) of one log file

          [default: 200]

      --log.file.max-files <COUNT>
          The maximum amount of log files that will be stored. If set to 0, background file logging is disabled.

          Default: 5 for `node` command, 0 for non-node utility subcommands.

      --log.journald
          Write logs to journald

      --log.journald.filter <FILTER>
          The filter to use for logs written to journald

          [default: error]

      --color <COLOR>
          Sets whether or not the formatter emits ANSI terminal escape codes for colors and other text formatting

          Possible values:
          - always: Colors on
          - auto:   Auto-detect
          - never:  Colors off

          [default: always]

      --logs-otlp[=<URL>]
          Enable `Opentelemetry` logs export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/logs` - gRPC: `http://localhost:4317`

          Example: --logs-otlp=http://collector:4318/v1/logs

          [env: OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=]

      --logs-otlp.filter <FILTER>
          Set a filter directive for the OTLP logs exporter. This controls the verbosity of logs sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --logs-otlp.filter=info,reth=debug

          Defaults to INFO if not specified.

          [default: info]

Display:
  -v, --verbosity...
          Set the minimum log level.

          -v      Errors
          -vv     Warnings
          -vvv    Info
          -vvvv   Debug
          -vvvvv  Traces (warning: very verbose!)

  -q, --quiet
          Silence all log output

Tracing:
      --tracing-otlp[=<URL>]
          Enable `Opentelemetry` tracing export to an OTLP endpoint.

          If no value provided, defaults based on protocol: - HTTP: `http://localhost:4318/v1/traces` - gRPC: `http://localhost:4317`

          Example: --tracing-otlp=http://collector:4318/v1/traces

          [env: OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=]

      --tracing-otlp-protocol <PROTOCOL>
          OTLP transport protocol to use for exporting traces and logs.

          - `http`: expects endpoint path to end with `/v1/traces` or `/v1/logs` - `grpc`: expects endpoint without a path

          Defaults to HTTP if not specified.

          Possible values:
          - http: HTTP/Protobuf transport, port 4318, requires `/v1/traces` path
          - grpc: gRPC transport, port 4317

          [env: OTEL_EXPORTER_OTLP_PROTOCOL=]
          [default: http]

      --tracing-otlp.filter <FILTER>
          Set a filter directive for the OTLP tracer. This controls the verbosity of spans and events sent to the OTLP endpoint. It follows the same syntax as the `RUST_LOG` environment variable.

          Example: --tracing-otlp.filter=info,reth=debug,hyper_util=off

          Defaults to TRACE if not specified.

          [default: debug]

      --tracing-otlp.sample-ratio <RATIO>
          Trace sampling ratio to control the percentage of traces to export.

          Valid range: 0.0 to 1.0 - 1.0, default: Sample all traces - 0.01: Sample 1% of traces - 0.0: Disable sampling

          Example: --tracing-otlp.sample-ratio=0.0.

          [env: OTEL_TRACES_SAMPLER_ARG=]
```


# Understanding the op-reth CLI
Source: https://docs.optimism.io/node-operators/op-reth/cli/overview

Understand how the op-reth command-line interface is organized, how chain selection works through the Superchain Registry, and where configuration values come from.

This page explains how the `op-reth` command-line interface is organized, so
you can find the right command and understand where its configuration comes
from. To install and start a node, follow
[Execution client configuration](/node-operators/guides/configuration/execution-clients).
For the full flag catalogue of every command, see the
[generated CLI reference](/node-operators/op-reth/cli/op-reth).

## One binary, many commands

`op-reth` ships as a single binary. The command you run day to day is
`op-reth node`, which starts the execution client itself. The other
subcommands are operational tools: most work against the same data directory —
initializing it, importing history into it, inspecting it, or repairing it —
so you rarely run them while the node is running. A couple (`config` and
`dump-genesis`) simply print information to stdout.

| Command                                                                        | What it does                                                            |
| ------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| [`node`](/node-operators/op-reth/cli/op-reth/node)                             | Start the node                                                          |
| [`init`](/node-operators/op-reth/cli/op-reth/init)                             | Initialize the database from a genesis file                             |
| [`init-state`](/node-operators/op-reth/cli/op-reth/init-state)                 | Initialize the database from a state dump file                          |
| [`import-op`](/node-operators/op-reth/cli/op-reth/import-op)                   | Sync RLP-encoded OP blocks below Bedrock from a file, without executing |
| [`import-receipts-op`](/node-operators/op-reth/cli/op-reth/import-receipts-op) | Import RLP-encoded receipts from a file                                 |
| [`dump-genesis`](/node-operators/op-reth/cli/op-reth/dump-genesis)             | Dump the genesis block JSON configuration to stdout                     |
| [`db`](/node-operators/op-reth/cli/op-reth/db)                                 | Database debugging utilities                                            |
| [`stage`](/node-operators/op-reth/cli/op-reth/stage)                           | Manipulate individual sync stages                                       |
| [`p2p`](/node-operators/op-reth/cli/op-reth/p2p)                               | P2P debugging utilities                                                 |
| [`config`](/node-operators/op-reth/cli/op-reth/config)                         | Write the configuration to stdout                                       |
| [`prune`](/node-operators/op-reth/cli/op-reth/prune)                           | Prune according to the configuration without any limits                 |
| [`re-execute`](/node-operators/op-reth/cli/op-reth/re-execute)                 | Re-execute blocks in parallel to verify historical sync correctness     |
| [`proofs`](/node-operators/op-reth/cli/op-reth/proofs)                         | Manage storage of historical proofs within the fault proof window       |

The [CLI reference](/node-operators/op-reth/cli/op-reth) mirrors this structure: each
page reproduces the output of `op-reth <command> --help`, and nested
subcommands (such as `op-reth db stats`) get their own nested pages.

### Running the node

[`node`](/node-operators/op-reth/cli/op-reth/node) is the long-running command that
syncs and serves the chain. It carries by far the largest flag surface,
organized into functional groups — Metrics, Datadir, Networking, RPC, TxPool,
Builder, Debug, Dev testnet, Pruning, Engine, and Rollup, among others — with
related flags sharing a dotted prefix (for example `--txpool.*`, `--prune.*`,
`--rollup.*`, or `--http.*` in the RPC group).

The `Rollup` group is OP Stack-specific: flags such as `--rollup.sequencer`
(the sequencer endpoint that transactions are forwarded to) and
`--rollup.disable-tx-pool-gossip` configure behavior that only exists on OP
Stack chains. These are covered with examples in
[Execution client configuration](/node-operators/guides/configuration/execution-clients).

### Initializing and importing

[`init`](/node-operators/op-reth/cli/op-reth/init) and
[`init-state`](/node-operators/op-reth/cli/op-reth/init-state) create a fresh database
from a genesis file or a state dump file respectively, instead of syncing from
the network.

[`import-op`](/node-operators/op-reth/cli/op-reth/import-op) and
[`import-receipts-op`](/node-operators/op-reth/cli/op-reth/import-receipts-op) exist for
one OP Stack-specific job: loading OP Mainnet history from before the Bedrock
migration, which cannot be re-executed and is instead imported from files.
[Sync OP Mainnet](/node-operators/op-reth/run/faq/sync-op-mainnet) explains when you
need them — most operators use the minimal bootstrap path with `init-state`
and skip the pre-Bedrock import entirely.

### Inspecting and maintaining

The remaining commands are diagnostic and maintenance tools:

* [`db`](/node-operators/op-reth/cli/op-reth/db) inspects and repairs the database:
  table statistics, checksums, diffs between databases, and storage
  settings.
* [`stage`](/node-operators/op-reth/cli/op-reth/stage) runs, drops, dumps, or unwinds
  individual stages of reth's staged-sync pipeline (such as execution,
  account hashing, and merkle) — useful for debugging or re-running one part
  of sync without starting over.
* [`p2p`](/node-operators/op-reth/cli/op-reth/p2p) debugs the networking layer:
  downloading a single header or body from peers, RLPx utilities, and
  running a bootnode.
* [`config`](/node-operators/op-reth/cli/op-reth/config) and
  [`dump-genesis`](/node-operators/op-reth/cli/op-reth/dump-genesis) print the
  effective configuration and the chain's genesis JSON to stdout.
* [`prune`](/node-operators/op-reth/cli/op-reth/prune) and
  [`re-execute`](/node-operators/op-reth/cli/op-reth/re-execute) are heavyweight
  maintenance passes: pruning historical data according to your
  configuration, and re-executing blocks in parallel to verify that
  historical sync produced correct results.

## Chain selection and the Superchain Registry

Every command that touches chain data accepts `--chain <CHAIN_OR_PATH>`, which
takes either a built-in chain name or the path to a chain specification file.
The default is `optimism` (OP Mainnet).

The built-in names come from the
[Superchain Registry](https://github.com/ethereum-optimism/superchain-registry):
op-reth bakes the registry's chain configurations into the binary at build
time, so chains like `base`, `unichain`, `ink`, `mode`, `zora`, and their
Sepolia counterparts (for example `unichain-sepolia`) work by name with no
extra configuration files. The full list of built-in chains is in the
[`node` reference](/node-operators/op-reth/cli/op-reth/node) under `--chain`. For a
chain that is not in the registry, pass the path to its chain specification
file instead.

## Where configuration comes from

op-reth is configured primarily through CLI flags. Three conventions in the
help text (and the [generated reference](/node-operators/op-reth/cli/op-reth)) tell you
how a flag behaves:

* **Defaults** — every flag with a default value lists it as
  `[default: ...]`. For example, `--datadir` defaults to an OS-specific data
  directory (`$HOME/.local/share/reth/` or `$XDG_DATA_HOME/reth/` on Linux).
* **Environment variables** — flags that can also be set through an
  environment variable list it as `[env: ...]`; the OpenTelemetry export
  flags (`--logs-otlp`, `--tracing-otlp`) are examples.
* **Shared groups** — every subcommand accepts the same Logging, Display,
  and Tracing options, so `-vvv` or `--log.file.directory` work the same on
  `op-reth db stats` as on `op-reth node`.

A configuration file supplements the flags: `op-reth node --config <FILE>`
points the node at one, and `op-reth config` writes the resulting
configuration to stdout (`op-reth config --default` shows the defaults), which
is the quickest way to see what is configurable through the file.

## Next steps

* Follow [Execution client configuration](/node-operators/guides/configuration/execution-clients)
  to install op-reth and pair it with a consensus client.
* Browse the [CLI reference](/node-operators/op-reth/cli/op-reth) for the complete
  flag catalogue of every command.
* See [Sync OP Mainnet](/node-operators/op-reth/run/faq/sync-op-mainnet) if you are
  bootstrapping an OP Mainnet archive node.


# op-reth for node operators
Source: https://docs.optimism.io/node-operators/op-reth/index

op-reth is the OP Stack execution client built on reth. Start here to run it alongside a rollup node and to find its CLI reference.

`op-reth` is the [OP Stack](https://docs.optimism.io/) execution client built on [reth](https://github.com/paradigmxyz/reth). It provides a high-performance execution layer for Optimism and all OP Stack chains.

## Features

* **Full OP Stack support** — Deposit transactions, L2-specific fee handling, and all OP Stack protocol changes.
* **Superchain Registry** — Built-in support for all chains in the [superchain registry](https://github.com/ethereum-optimism/superchain-registry). Use `--chain unichain`, `--chain base`, etc.
* **High performance** — Built on reth's modular architecture with parallelized execution and efficient storage.

## Getting started

* [Execution client configuration](/node-operators/guides/configuration/execution-clients): install op-reth, pair it with a consensus client, and set the OP Stack specific flags.
* [Running a Node With Docker](/node-operators/tutorials/node-from-docker): bring up op-reth and op-node from the official images.
* [Sync OP Mainnet](/node-operators/op-reth/run/faq/sync-op-mainnet) — Import Bedrock state and sync OP Mainnet from scratch.
* [Understanding the op-reth CLI](/node-operators/op-reth/cli/overview) — How the commands, chain selection, and configuration fit together.
* [CLI Reference](/node-operators/op-reth/cli/op-reth) — Full command-line reference for op-reth.


# Sync OP Mainnet
Source: https://docs.optimism.io/node-operators/op-reth/run/faq/sync-op-mainnet

Syncing op-reth with OP Mainnet and Bedrock state.

To sync OP mainnet, Bedrock state needs to be imported as a starting point. There are currently two ways:

* Minimal bootstrap **(recommended)**: only state snapshot at Bedrock block is imported without any OVM historical data.
* Full bootstrap **(not recommended)**: state, blocks and receipts are imported.

## Minimal bootstrap (recommended)

**The state snapshot at Bedrock block is required.** It can be exported from [op-geth](https://github.com/testinprod-io/op-erigon/blob/pcw109550/bedrock-db-migration/bedrock-migration.md#export-state) (**.jsonl**) or downloaded directly from [here](https://mega.nz/file/GdZ1xbAT#a9cBv3AqzsTGXYgX7nZc_3fl--tcBmOAIwIA5ND6kwc).

### 1. Download and decompress

After you downloaded the state file, ensure the state file is decompressed into **.jsonl** format:

```sh theme={null}
$ unzstd /path/to/world_trie_state.jsonl.zstd
```

### 2. Import the state

Import the state snapshot:

```sh theme={null}
$ op-reth init-state --without-ovm --chain optimism --datadir op-mainnet world_trie_state.jsonl
```

### 3. Sync from Bedrock to tip

Running the node with `--debug.tip <block-hash>` syncs the node without help from CL until a fixed tip. The
block hash can be taken from the latest block on [https://optimistic.etherscan.io](https://optimistic.etherscan.io).

Eg, sync the node to a recent finalized block (e.g. 125200000) to catch up close to the tip, before pairing with op-node.

```sh theme={null}
$ op-reth node --chain optimism --datadir op-mainnet --debug.tip 0x098f87b75c8b861c775984f9d5dbe7b70cbbbc30fc15adb03a5044de0144f2d0 # block #125200000
```

## Full bootstrap (not recommended)

**Not recommended for now**: [storage consistency issue](https://github.com/paradigmxyz/reth/pull/11099) tldr: sudden crash may break the node.

### Import state

To sync OP mainnet, the Bedrock datadir needs to be imported to use as starting point.
Blocks lower than the OP mainnet Bedrock fork, are built on the OVM and cannot be executed on the EVM.
For this reason, the chain segment from genesis until Bedrock, must be manually imported to circumvent
execution in reth's sync pipeline.

Importing OP mainnet Bedrock datadir requires exported data:

* Blocks \[and receipts] below Bedrock
* State snapshot at first Bedrock block

### Manual Export Steps

The `op-geth` Bedrock datadir can be downloaded from [https://datadirs.optimism.io](https://datadirs.optimism.io).

To export the OVM chain from `op-geth`, clone the `testinprod-io/op-geth` repo and checkout
[testinprod-io/op-geth#1](https://github.com/testinprod-io/op-geth/pull/1). Commands to export blocks, receipts and state dump can be
found in `op-geth/migrate.sh`.

### Manual Import Steps

#### 1. Import Blocks

Imports a `.rlp` file of blocks.

Import of >100 million OVM blocks, from genesis to Bedrock, completes in 45 minutes.

```bash theme={null}
$ op-reth import-op --chain optimism <exported-blocks>
```

#### 2. Import Receipts

This step is optional. To run a full node, skip this step. If however receipts are to be imported, the
corresponding transactions must already be imported (see [step 1](#1-import-blocks)).

Imports a `.rlp` file of receipts, that has been exported with command specified in
[testinprod-io/op-geth#1](https://github.com/testinprod-io/op-geth/pull/1) (command for exporting receipts uses custom RLP-encoding).

Import of >100 million OVM receipts, from genesis to Bedrock, completes in 30 minutes.

```bash theme={null}
$ op-reth import-receipts-op --chain optimism <exported-receipts>
```

#### 3. Import State

Imports a `.jsonl` state dump. The block at which the state dump is made, must be the latest block in
reth's database. This should be block 105 235 063, the first Bedrock block (see [step 1](#1-import-blocks)).

Import of >4 million OP mainnet accounts at Bedrock, completes in 10 minutes.

```bash theme={null}
$ op-reth init-state --chain optimism <state-dump>
```

### Start with op-node

Use `op-node` to track the tip. Start `op-node` with `--syncmode=execution-layer` and `--l2.enginekind=reth`. If `op-node`'s RPC
connection to L1 is over localhost, `--l1.trustrpc` can be set to improve performance.


# Node Operator Overview
Source: https://docs.optimism.io/node-operators/overview

Learn about running nodes on OP Stack networks.

## Overview

This section of the documentation is dedicated to node operators who want to learn about configuring and running nodes on OP Stack networks.
Because the OP Stack is an open-source, modular, and extensible stack, there are many different clients, configurations, and requirements depending on your goals and the specific network you're targeting.
The information provided in this section covers standard configurations and features on the OP Stack.

## Why Run a Node?

Running your own node gives you the benefit of trustless verification, enhanced privacy, and gives you local access to the blockchain.
However, it also requires time and resources to set up and maintain.
So you should consider your goals and use cases before deciding to run a node because there are many third-party RPC providers available.

## System requirements

Before you start, check that your machine can handle the network and node type you're targeting.
Requirements scale with both:

* **RAM:** 16GB is the suggested minimum for an OP Mainnet node.
* **CPU:** A reasonably modern CPU.
* **Disk:** An SSD, sized to the network and node type. A full OP Mainnet node needs hundreds of gigabytes and grows steadily; an archive node needs multiple terabytes and grows much faster, so use an NVMe SSD for archive nodes.

Test networks are far lighter than OP Mainnet: an OP Sepolia full node syncs into tens of gigabytes rather than hundreds.
If you're setting up for the first time, start on OP Sepolia to validate your setup before committing OP Mainnet-scale disk.

For the current OP Mainnet storage figures and their growth rates, see the [hardware requirements](/node-operators/tutorials/run-node-from-source#hardware-requirements) in the from-source tutorial.

## Node Architecture

Regardless of which OP Stack network you're running a node for, all nodes share the same fundamental two-client architecture: a consensus client (rollup node, either [op-node](/op-stack/components/op-node) or [kona-node](/op-stack/components/kona-node)) paired with an execution client ([op-reth](/op-stack/components/op-reth)), communicating via the Engine API with JWT authentication.
Nodes that follow every chain in an [interop](/op-stack/interop/explainer) dependency set run [op-supernode](/op-stack/interop/supernode) as the consensus layer instead.
See the [architecture reference](/node-operators/reference/architecture) for how the components fit together and the current client support matrix.

## Node Types

Different node types serve different purposes:

* **Full node**: keeps a complete copy of the blockchain, validates all transactions and blocks, and participates on the P2P network.
* **Archive node**: additionally retains all historical state for every block.
  On OP Mainnet, archive nodes need to restore from a [database snapshot](/op-mainnet/network-information/snapshots) before syncing.
* **Sequencer node**: can be a full or archive node, but it can create new L2 blocks.

## Network upgrades

Network upgrades on OP Stack networks are generally [activated by timestamps](/op-stack/protocol/network-upgrades#activations).
Failing to upgrade your node before the activation timestamp causes a chain divergence that requires a resync, so follow the [node upgrade process](/op-stack/protocol/network-upgrades#upgrade-process) to stay on the canonical chain.

## Stay up to date

Upgrade announcements, deprecations, and other changes that affect node operators are published on the [Network Notices](/notices) page.

## Next steps

* [**Run a node with Docker**](/node-operators/tutorials/node-from-docker): recommended path; uses the official op-reth + op-node images.
* [**Build and run a node from source**](/node-operators/tutorials/run-node-from-source): covers op-reth and Nethermind.
* [**Run op-reth with historical proofs**](/node-operators/tutorials/reth-historical-proofs): configure op-reth's proofs-history store for permissionless withdrawal proving.
* [**Consensus client configuration**](/node-operators/guides/configuration/consensus-clients): working base configuration and recommended flags for the rollup node.
* [**Execution client configuration**](/node-operators/guides/configuration/execution-clients): working base configuration and recommended flags for the execution client.
* [**Supernode configuration**](/node-operators/guides/configuration/supernode): recommended settings and a starter configuration for running op-supernode in an interop dependency set.
* [**Node metrics and monitoring**](/node-operators/guides/monitoring/metrics): keep tabs on your node once it's running.
* [**Node troubleshooting**](/node-operators/guides/troubleshooting): help with common problems.
* [**Architecture reference**](/node-operators/reference/architecture): deeper detail on the two-client architecture.


# Node architecture
Source: https://docs.optimism.io/node-operators/reference/architecture/index

Understand how the components of an OP Stack node fit together.

This page explains how an OP Stack node is put together: what its components are, what each one is responsible for, and how they relate to the equivalent parts of an Ethereum node. It is background reading to build a mental model before you run a node; for the steps to actually stand one up, see the [Next steps](#next-steps) below.

Every node on an OP Stack network is composed of two core software services, the Rollup Node and the Execution Client.
OP Mainnet also optionally supports a third component, Legacy Geth, that can serve stateful queries for blocks and transactions created before the [Bedrock Upgrade](https://web.archive.org/web/20230608050602/https://blog.oplabs.co/introducing-optimism-bedrock/).

## Node flow diagram

The following diagram shows how the Rollup Node, Execution Client, and Legacy Geth components work together to form a complete node running on OP Stack networks.
This diagram uses the `op-node` implementation of the Rollup Node and shows the general architecture that applies to all execution client implementations.

<img alt="OP Mainnet node architecture diagram." />

## Rollup node

The Rollup Node is responsible for deriving L2 block payloads from L1 data and passing those payloads to the Execution Client. The Rollup Node can also optionally participate in a peer-to-peer network to receive blocks directly from the Sequencer before those blocks are submitted to L1. The Rollup Node is largely analogous to a [consensus client](https://ethereum.org/en/developers/docs/nodes-and-clients/#what-are-nodes-and-clients) in Ethereum.

### Rollup node implementations

* **[op-node](/op-stack/components/op-node)** is the reference implementation of the Rollup Node, written in Go and maintained by Optimism. It is the default choice for any node role and is not deprecated.
* **[kona-node](/op-stack/components/kona-node)** is the Rust implementation of the Rollup Node, built as part of the Kona project. It is in active development and should be considered experimental, so give it a role where that is acceptable.

For nodes that follow every chain in an [interop](/op-stack/interop/explainer) dependency set, deploy the consensus layer as [op-supernode](/op-stack/interop/supernode), which hosts an op-node instance for each chain in one process and adds cross-chain message verification. See the [supernode configuration guide](/node-operators/guides/configuration/supernode) for recommended settings and the [op-supernode configuration reference](/node-operators/reference/op-supernode-config) for the flag catalogue.

## Execution client

The Execution Client is responsible for executing the block payloads it receives from the Rollup Node over JSON-RPC via the standard [Ethereum Engine API](https://github.com/ethereum/execution-apis/blob/main/src/engine/common.md#engine-api----common-definitions).
The Execution Client exposes the standard JSON-RPC API that Ethereum developers are familiar with, and can be used to query blockchain data and submit transactions to the network.
The Execution Client is largely analogous to an [execution client](https://ethereum.org/en/developers/docs/nodes-and-clients/#what-are-nodes-and-clients) in Ethereum.

### Execution client implementations

* **[op-reth](/op-stack/components/op-reth)** is the Optimism-maintained execution client, written in Rust and built on reth. It is the primary supported execution client for OP Stack nodes. See the [execution client configuration guide](/node-operators/guides/configuration/execution-clients) for a working configuration.
* **[Nethermind](https://github.com/NethermindEth/nethermind)** is a third-party execution client written in C# that also supports OP Stack chains. The docs focus on Optimism-maintained software; for Nethermind specifics, see the [Nethermind documentation](https://docs.nethermind.io/get-started/running-node/l2-networks).

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

op-program has also reached end of support, replaced by kona-client for fault proofs; the same [notice](/notices/archive/op-geth-deprecation) covers both migrations.

## Legacy Geth

OP Mainnet blocks and transactions from before the 2023 [Bedrock Upgrade](https://web.archive.org/web/20230608050602/https://blog.oplabs.co/introducing-optimism-bedrock/) can be read from any current execution client, but re-executing them (RPC calls such as `eth_call` against pre-Bedrock blocks) requires an optional third component, Legacy Geth (`l2geth`), the client that ran OP Mainnet before the upgrade.
It is typically only needed for complete OP Mainnet archive nodes; see the [Legacy Geth configuration guide](/node-operators/guides/configuration/legacy-geth) for setup and request routing, and [accessing pre-regenesis history](/op-mainnet/pre-bedrock-history/regenesis-history) for the even older history that predates the current chain data entirely.

## Next steps

* To get your node up and running, start with the [run a node from docker](/node-operators/tutorials/node-from-docker) or [build and run a node from source](/node-operators/tutorials/run-node-from-source) tutorial. The source tutorial covers `op-reth` (primary) and `Nethermind` execution clients.
* If you've already got your node up and running, check out the [Node Metrics and Monitoring Guide](/node-operators/guides/monitoring/metrics) to learn how to keep tabs on your node and make sure it keeps running smoothly.
* If you run into any problems, please visit the [Node Troubleshooting Guide](/node-operators/guides/troubleshooting) for help.


# Consensus-layer sync
Source: https://docs.optimism.io/node-operators/reference/consensus-layer-sync

Learn about the consensus-layer sync mode.

This page documents the consensus-layer sync mode, which is the default sync method for op-node but not the recommended approach for most node operators.

## Overview

Consensus-layer sync is a sync approach where `op-node` reads transaction data from L1 and derives blocks, then inserts them into the execution client. Unlike execution-layer sync (snap sync), this method does not rely on P2P networking to download state or block data from other L2 nodes.

While consensus-layer sync is still the default mode, **execution-layer sync (snap sync) is recommended** for faster synchronization and better performance.

## When to use consensus-layer sync

This sync mode might be preferred in the following scenarios:

* **Independent verification**: Decentralized developer groups who need to independently verify the entire chain by deriving all data from L1
* **No P2P connectivity**: Environments where P2P networking is restricted or unavailable
* **L1-only trust model**: Applications that prefer to trust only L1 data without relying on L2 peer nodes
* **Debugging and research**: Analyzing how blocks are derived from L1 data

<Warning>
  Consensus-layer sync is significantly slower than execution-layer sync (snap sync). For most node operators, snap sync is the recommended approach for faster synchronization.
</Warning>

## Configuration

### Configuration for op-node

Set the following flag on `op-node`:

```shell theme={null}
--syncmode=consensus-layer
```

<Info>
  The `--syncmode=consensus-layer` is the default setting for `op-node`. You don't need to specify it explicitly unless you want to be explicit about the sync mode or are overriding a different configuration.
</Info>

### Configuration for op-geth

Set the following flag on `op-geth`:

```shell theme={null}
--syncmode=full
```

<Info>
  The `--syncmode=full` flag is not the default setting and must be explicitly configured. This ensures blocks are inserted by `op-node` rather than synced via P2P.
</Info>

### Configuration for Nethermind

Set the following flags on `Nethermind`:

```shell theme={null}
--config op-mainnet
--Sync.SnapSync=false
--Sync.FastSync=false
```

<Info>
  Replace `op-mainnet` with the appropriate configuration for your network (e.g., `op-sepolia` for OP Sepolia).
</Info>

## How consensus-layer sync works

The consensus-layer sync process:

1. **L1 monitoring**: `op-node` continuously monitors the L1 chain for transaction batches
2. **Block derivation**: `op-node` derives L2 blocks from the L1 transaction data
3. **Block insertion**: Derived blocks are inserted into the execution client one by one
4. **State building**: The execution client builds state by executing each block sequentially

This approach ensures that every block is derived from L1 and independently verified, but it's much slower than downloading state snapshots from peers.

## Performance considerations

* **Sync time**: Significantly slower than snap sync or archive sync with execution-layer mode
* **Network requirements**: Requires reliable L1 RPC access but minimal L2 P2P connectivity
* **Resource usage**: Lower P2P bandwidth usage but more L1 RPC calls
* **OP Mainnet**: For OP Mainnet, you'll still need the [bedrock datadir](/node-operators/guides/management/snapshots) for state before the Bedrock upgrade

## Comparison with other sync modes

| Feature          | Consensus-Layer (Legacy) | Execution-Layer (Snap Sync) | Archive with Execution-Layer |
| ---------------- | ------------------------ | --------------------------- | ---------------------------- |
| Data source      | L1 only                  | L2 P2P + L1                 | L2 P2P + L1                  |
| Sync speed       | Slowest                  | Fastest                     | Medium                       |
| State pruning    | Yes (by default)         | Yes                         | No                           |
| Historical state | Not available            | Not available               | Full history                 |
| P2P required     | No                       | Yes                         | Yes                          |
| Verification     | Full L1 derivation       | Cryptographic verification  | Full execution               |

## Next steps

* See the [Archive Node guide](/node-operators/guides/management/archive-node) for running an archive node
* See the [Consensus Client Configuration](/node-operators/guides/configuration/consensus-clients) and [Execution Client Configuration](/node-operators/guides/configuration/execution-clients) guides for additional explanation or customization
* If you experience difficulty at any stage of this process, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions)


# Legacy Geth configuration options
Source: https://docs.optimism.io/node-operators/reference/legacy-geth-config

Reference for Legacy Geth (l2geth) environment variables and the RPC methods routed to it.

This page catalogues the environment variables Legacy Geth (`l2geth`) accepts and the RPC methods your execution client routes to it.
For what Legacy Geth is and how to set it up, see the [Legacy Geth guide](/node-operators/guides/configuration/legacy-geth).

Legacy Geth applies only to networks that upgraded through Bedrock, such as OP Mainnet, where it serves execution requests and chain data for pre-Bedrock blocks.

## Environment variables

Legacy Geth accepts the following environment variables:

| Variable                   | Description                    | Default                               |
| -------------------------- | ------------------------------ | ------------------------------------- |
| `USING_OVM`                | **Required**. Enables OVM mode | N/A (must be set to `true`)           |
| `ETH1_SYNC_SERVICE_ENABLE` | Enables L1 sync service        | `true` (set to `false` for read-only) |
| `RPC_API`                  | Enabled RPC APIs               | `eth,net,web3`                        |
| `RPC_ADDR`                 | RPC listening address          | `localhost`                           |
| `RPC_CORS_DOMAIN`          | CORS domains                   | `localhost`                           |
| `RPC_ENABLE`               | Enable RPC server              | `false`                               |
| `RPC_PORT`                 | RPC port                       | `8545`                                |
| `RPC_VHOSTS`               | Virtual hosts                  | `localhost`                           |

<Warning>
  `USING_OVM=true` must always be set.
  Without it, `l2geth` panics at startup or returns invalid execution traces.
</Warning>

## Execution-client routing flag

Both op-reth and op-geth use the same `--rollup.historicalrpc` flag to route pre-Bedrock requests to Legacy Geth.
The flag takes the URL of the Legacy Geth RPC endpoint, for example `--rollup.historicalrpc=http://localhost:8545`.

## RPC methods routed to Legacy Geth

This section describes op-reth.
When `--rollup.historicalrpc` is set, op-reth forwards requests that target pre-Bedrock blocks to Legacy Geth and serves everything else directly.
This covers both methods that require transaction execution (which op-reth cannot perform for pre-Bedrock blocks) and methods that read pre-Bedrock block or transaction data.
Methods not listed below (for example `eth_getLogs`) are never routed to Legacy Geth.

<Info>
  op-geth behaved differently: it served pre-Bedrock block and transaction data locally from its migrated database and routed only execution methods to Legacy Geth.
  op-geth has reached end-of-support and this behavior is no longer documented here; see the [op-geth deprecation notice](/notices/archive/op-geth-deprecation).
</Info>

### State and execution methods

Routed to Legacy Geth when the method's block parameter refers to a pre-Bedrock block:

* `eth_call`
* `eth_estimateGas`
* `eth_createAccessList`
* `eth_getBalance`
* `eth_getCode`
* `eth_getStorageAt`
* `eth_getTransactionCount`
* `eth_getProof`
* `debug_traceCall`

### Block data methods

Routed to Legacy Geth when the requested block is pre-Bedrock, or when the requested block hash is unknown to op-reth:

* `eth_getBlockByNumber` / `eth_getBlockByHash`
* `eth_getBlockReceipts`
* `eth_getHeaderByNumber` / `eth_getHeaderByHash`
* `eth_getBlockTransactionCountByNumber` / `eth_getBlockTransactionCountByHash`
* `eth_getUncleCountByBlockNumber` / `eth_getUncleCountByBlockHash`
* `eth_getUncleByBlockNumberAndIndex` / `eth_getUncleByBlockHashAndIndex`
* `eth_getTransactionByBlockNumberAndIndex` / `eth_getTransactionByBlockHashAndIndex`
* `eth_getRawTransactionByBlockNumberAndIndex` / `eth_getRawTransactionByBlockHashAndIndex`
* `debug_traceBlockByNumber` / `debug_traceBlockByHash`

### Transaction data methods

Routed to Legacy Geth when the transaction belongs to a pre-Bedrock block, or when the transaction is unknown to op-reth:

* `eth_getTransactionByHash`
* `eth_getTransactionReceipt`
* `eth_getRawTransactionByHash`
* `debug_traceTransaction`

### `eth_getBlockReceipts` emulation

Legacy Geth (`l2geth`) predates `eth_getBlockReceipts` and does not implement it.
op-reth forwards the request first; if Legacy Geth responds that the method does not exist, op-reth fetches the block's transaction hashes from Legacy Geth and assembles the response from one `eth_getTransactionReceipt` call per transaction.
Receipts are returned in transaction order and passed through verbatim, with their legacy fields intact — exactly what a forwarded `eth_getTransactionReceipt` returns for the same transactions.
A block unknown to Legacy Geth returns `null`, and a block without transactions returns `[]`.


# op-node configuration options
Source: https://docs.optimism.io/node-operators/reference/op-node-config

Complete reference for all op-node command-line flags and environment variables.

This page catalogues every configuration option for the op-node, the consensus-layer
(rollup node) client of an OP Stack chain.

<ConfigReferencePreamble />

For guidance on running a node — hardware, sync strategies, and monitoring —
see the [node operator guides](/node-operators/tutorials/run-node-from-source).

## Flags

Generated from [`op-node/v1.19.3`](https://github.com/ethereum-optimism/optimism/releases/tag/op-node%2Fv1.19.3)
flag definitions. 109 flags: 3 required, 106 optional.

### Required flags

| Flag              | Description                                                                                                         | Environment variable     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| `--l1`            | Address of L1 User JSON-RPC endpoint to use (eth namespace required)                                                | `OP_NODE_L1_ETH_RPC`     |
| `--l2`            | Address of L2 Engine JSON-RPC endpoints to use (engine and eth namespace required)                                  | `OP_NODE_L2_ENGINE_RPC`  |
| `--l2.jwt-secret` | Path to JWT secret key. Keys are 32 bytes, hex encoded in a file. A new key will be generated if the file is empty. | `OP_NODE_L2_ENGINE_AUTH` |

### Optional flags

| Flag                                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Default                   | Environment variable                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------- |
| `--altda.da-server`                   | HTTP address of a DA Server                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | —                         | `OP_NODE_ALTDA_DA_SERVER`                   |
| `--altda.da-service`                  | Use DA service type where commitments are generated by Alt-DA server                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `false`                   | `OP_NODE_ALTDA_DA_SERVICE`                  |
| `--altda.enabled`                     | Enable Alt-DA mode Alt-DA Mode is a Beta feature of the MIT licensed OP Stack. While it has received initial review from core contributors, it is still undergoing testing, and may have bugs or other issues.                                                                                                                                                                                                                                                                                                                     | `false`                   | `OP_NODE_ALTDA_ENABLED`                     |
| `--altda.get-timeout`                 | Timeout for get requests. 0 means no timeout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `0s`                      | `OP_NODE_ALTDA_GET_TIMEOUT`                 |
| `--altda.max-concurrent-da-requests`  | Maximum number of concurrent requests to the DA server                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `1`                       | `OP_NODE_ALTDA_MAX_CONCURRENT_DA_REQUESTS`  |
| `--altda.put-timeout`                 | Timeout for put requests. 0 means no timeout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `0s`                      | `OP_NODE_ALTDA_PUT_TIMEOUT`                 |
| `--altda.verify-on-read`              | Verify input data matches the commitments from the DA storage service                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `true`                    | `OP_NODE_ALTDA_VERIFY_ON_READ`              |
| `--conductor.enabled`                 | Enable the conductor service                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `false`                   | `OP_NODE_CONDUCTOR_ENABLED`                 |
| `--conductor.rpc`                     | Conductor service rpc endpoint                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"http://127.0.0.1:8547"` | `OP_NODE_CONDUCTOR_RPC`                     |
| `--conductor.rpc-timeout`             | Conductor service rpc timeout                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `1s`                      | `OP_NODE_CONDUCTOR_RPC_TIMEOUT`             |
| `--experimental.sequencer-api`        | Enables experimental test sequencer RPC functionality                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `false`                   | `OP_NODE_EXPERIMENTAL_SEQUENCER_API`        |
| `--fetch-withdrawal-root-from-state`  | Read withdrawal\_storage\_root (aka message passer storage root) from state trie (via execution layer) instead of the block header. Restores pre-Isthmus behavior, requires an archive EL client.                                                                                                                                                                                                                                                                                                                                  | `false`                   | `OP_NODE_FETCH_WITHDRAWAL_ROOT_FROM_STATE`  |
| `--finality.delay`                    | Number of L1 blocks to traverse before trying to finalize L2 blocks again. Uses default (64) if 0.                                                                                                                                                                                                                                                                                                                                                                                                                                 | `0`                       | `OP_NODE_FINALITY_DELAY`                    |
| `--finality.lookback`                 | Number of L1 blocks to look back for finality verification. Uses default calculation if 0 (considers alt-DA challenge/resolve windows if applicable).                                                                                                                                                                                                                                                                                                                                                                              | `0`                       | `OP_NODE_FINALITY_LOOKBACK`                 |
| `--interop.dependency-set`            | Dependency-set configuration, point at JSON file.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | —                         | `OP_NODE_INTEROP_DEPENDENCY_SET`            |
| `--l1.beacon`                         | Address of L1 Beacon-node HTTP endpoint to use.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | —                         | `OP_NODE_L1_BEACON`                         |
| `--l1.beacon-fallbacks`               | Addresses of L1 Beacon-API compatible HTTP fallback endpoints. Used to fetch blob sidecars not available at the l1.beacon (e.g. expired blobs).                                                                                                                                                                                                                                                                                                                                                                                    | —                         | `OP_NODE_L1_BEACON_FALLBACKS`               |
| `--l1.beacon-header`                  | Optional HTTP header to add to all requests to the L1 Beacon endpoint. Format: 'X-Key: Value'                                                                                                                                                                                                                                                                                                                                                                                                                                      | —                         | `OP_NODE_L1_BEACON_HEADER`                  |
| `--l1.beacon.fetch-all-sidecars`      | If true, all sidecars are fetched and filtered locally. Workaround for buggy Beacon nodes.                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                   | `OP_NODE_L1_BEACON_FETCH_ALL_SIDECARS`      |
| `--l1.beacon.ignore`                  | When false, halts op-node startup if the healthcheck to the Beacon-node endpoint fails.                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                   | `OP_NODE_L1_BEACON_IGNORE`                  |
| `--l1.beacon.slot-duration-override`  | Duration in seconds of an L1 slot. When set (non-zero), bypasses the beacon /eth/v1/config/spec fetch and uses this value as SECONDS\_PER\_SLOT. Useful for devnets where the beacon spec endpoint is unavailable (e.g. anvil).                                                                                                                                                                                                                                                                                                    | `0`                       | `OP_NODE_L1_BEACON_SLOT_DURATION_OVERRIDE`  |
| `--l1.cache-size`                     | Cache size for blocks, receipts and transactions. If this flag is set to 0, 3/2 of the sequencing window size is used (usually 2400). The default value of 900 (\~3h of L1 blocks) is good for (high-throughput) networks that see frequent safe head increments. On (low-throughput) networks with infrequent safe head increments, it is recommended to set this value to 0, or a value that well covers the typical span between safe head increments. Note that higher values will cause significantly increased memory usage. | `900`                     | `OP_NODE_L1_CACHE_SIZE`                     |
| `--l1.epoch-poll-interval`            | Poll interval for retrieving new L1 epoch updates such as safe and finalized block changes. Disabled if 0 or negative.                                                                                                                                                                                                                                                                                                                                                                                                             | `6m24s`                   | `OP_NODE_L1_EPOCH_POLL_INTERVAL`            |
| `--l1.http-poll-interval`             | Polling interval for latest-block subscription when using an HTTP RPC provider. Ignored for other types of RPC endpoints.                                                                                                                                                                                                                                                                                                                                                                                                          | `12s`                     | `OP_NODE_L1_HTTP_POLL_INTERVAL`             |
| `--l1.max-concurrency`                | Maximum number of concurrent RPC requests to make to the L1 RPC provider.                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `10`                      | `OP_NODE_L1_MAX_CONCURRENCY`                |
| `--l1.rpc-max-batch-size`             | Maximum number of RPC requests to bundle, e.g. during L1 blocks receipt fetching. The L1 RPC rate limit counts this as N items, but allows it to burst at once.                                                                                                                                                                                                                                                                                                                                                                    | `20`                      | `OP_NODE_L1_RPC_MAX_BATCH_SIZE`             |
| `--l1.rpc-rate-limit`                 | Optional self-imposed global rate-limit on L1 RPC requests, specified in requests / second. Disabled if set to 0.                                                                                                                                                                                                                                                                                                                                                                                                                  | `0`                       | `OP_NODE_L1_RPC_RATE_LIMIT`                 |
| `--l1.rpckind`                        | The kind of RPC provider, used to inform optimal transactions receipts fetching, and thus reduce costs. Valid options: alchemy, quicknode, infura, parity, nethermind, debug\_geth, erigon, basic, any, standard                                                                                                                                                                                                                                                                                                                   | `standard`                | `OP_NODE_L1_RPC_KIND`                       |
| `--l1.runtime-config-reload-interval` | Poll interval for reloading the runtime config, useful when config events are not being picked up. Disabled if 0 or negative.                                                                                                                                                                                                                                                                                                                                                                                                      | `10m0s`                   | `OP_NODE_L1_RUNTIME_CONFIG_RELOAD_INTERVAL` |
| `--l1.trustrpc`                       | Trust the L1 RPC, sync faster at risk of malicious/buggy RPC providing bad or inconsistent L1 data                                                                                                                                                                                                                                                                                                                                                                                                                                 | `false`                   | `OP_NODE_L1_TRUST_RPC`                      |
| `--l2.engine-rpc-timeout`             | L2 engine client rpc timeout                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `10s`                     | `OP_NODE_L2_ENGINE_RPC_TIMEOUT`             |
| `--l2.enginekind`                     | The kind of engine client, used to control the behavior of optimism in respect to different types of engine clients. Valid options: geth, reth, erigon                                                                                                                                                                                                                                                                                                                                                                             | `reth`                    | `OP_NODE_L2_ENGINE_KIND`                    |
| `--l2.follow.source`                  | Address of L2 CL RPC HTTP endpoint to follow source                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | —                         | `OP_NODE_L2_FOLLOW_SOURCE`                  |
| `--log.color`                         | Color the log output if in terminal mode                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `false`                   | `OP_NODE_LOG_COLOR`                         |
| `--log.format`                        | Format the log output. Supported formats: text, terminal, logfmt, logfmtms, json, jsonms                                                                                                                                                                                                                                                                                                                                                                                                                                           | `text`                    | `OP_NODE_LOG_FORMAT`                        |
| `--log.level`                         | The lowest log level that will be output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `INFO`                    | `OP_NODE_LOG_LEVEL`                         |
| `--log.pid`                           | Show pid in the log                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `false`                   | `OP_NODE_LOG_PID`                           |
| `--metrics.addr`                      | Metrics listening address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `"0.0.0.0"`               | `OP_NODE_METRICS_ADDR`                      |
| `--metrics.enabled`                   | Enable the metrics server                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `false`                   | `OP_NODE_METRICS_ENABLED`                   |
| `--metrics.port`                      | Metrics listening port                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `7300`                    | `OP_NODE_METRICS_PORT`                      |
| `--network`                           | Predefined network selection. Available networks: every chain bundled from the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) at the release; run `op-node --help` for the exact list                                                                                                                                                                                                                                                                                                             | —                         | `OP_NODE_NETWORK`                           |
| `--override.canyon`                   | Manually specify the canyon fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `0`                       | `OP_NODE_OVERRIDE_CANYON`                   |
| `--override.delta`                    | Manually specify the delta fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `0`                       | `OP_NODE_OVERRIDE_DELTA`                    |
| `--override.ecotone`                  | Manually specify the ecotone fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `0`                       | `OP_NODE_OVERRIDE_ECOTONE`                  |
| `--override.fjord`                    | Manually specify the fjord fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `0`                       | `OP_NODE_OVERRIDE_FJORD`                    |
| `--override.granite`                  | Manually specify the granite fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `0`                       | `OP_NODE_OVERRIDE_GRANITE`                  |
| `--override.holocene`                 | Manually specify the holocene fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `0`                       | `OP_NODE_OVERRIDE_HOLOCENE`                 |
| `--override.isthmus`                  | Manually specify the isthmus fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `0`                       | `OP_NODE_OVERRIDE_ISTHMUS`                  |
| `--override.jovian`                   | Manually specify the jovian fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `0`                       | `OP_NODE_OVERRIDE_JOVIAN`                   |
| `--override.karst`                    | Manually specify the karst fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `0`                       | `OP_NODE_OVERRIDE_KARST`                    |
| `--override.keep-karst-upgrade-gas`   | Manually set keep\_karst\_upgrade\_gas, overriding the bundled setting. When true, the Karst activation block's one-time upgrade gas is kept on every later block (for chains that activated Karst with the leak baked into their history).                                                                                                                                                                                                                                                                                        | `false`                   | `OP_NODE_OVERRIDE_KEEP_KARST_UPGRADE_GAS`   |
| `--override.lagoon`                   | Manually specify the lagoon fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `0`                       | `OP_NODE_OVERRIDE_LAGOON`                   |
| `--override.pectrablobschedule`       | Manually specify the pectrablobschedule fork timestamp, overriding the bundled setting                                                                                                                                                                                                                                                                                                                                                                                                                                             | `0`                       | `OP_NODE_OVERRIDE_PECTRABLOBSCHEDULE`       |
| `--p2p.advertise.ip`                  | The IP address to advertise in Discv5, put into the ENR of the node. This may also be a hostname / domain name to resolve to an IP.                                                                                                                                                                                                                                                                                                                                                                                                | —                         | `OP_NODE_P2P_ADVERTISE_IP`                  |
| `--p2p.advertise.tcp`                 | The TCP port to advertise in Discv5, put into the ENR of the node. Set to p2p.listen.tcp value if 0.                                                                                                                                                                                                                                                                                                                                                                                                                               | `0`                       | `OP_NODE_P2P_ADVERTISE_TCP`                 |
| `--p2p.advertise.udp`                 | The UDP port to advertise in Discv5 as fallback if not determined by Discv5, put into the ENR of the node. Set to p2p.listen.udp value if 0.                                                                                                                                                                                                                                                                                                                                                                                       | `0`                       | `OP_NODE_P2P_ADVERTISE_UDP`                 |
| `--p2p.ban.duration`                  | The duration that peers are banned for.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `1h0m0s`                  | `OP_NODE_P2P_PEER_BANNING_DURATION`         |
| `--p2p.ban.peers`                     | Enables peer banning.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `true`                    | `OP_NODE_P2P_PEER_BANNING`                  |
| `--p2p.ban.threshold`                 | The minimum score below which peers are disconnected and banned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `-100`                    | `OP_NODE_P2P_PEER_BANNING_THRESHOLD`        |
| `--p2p.bootnodes`                     | Comma-separated base64-format ENR list. Bootnodes to start discovering other node records from.                                                                                                                                                                                                                                                                                                                                                                                                                                    | —                         | `OP_NODE_P2P_BOOTNODES`                     |
| `--p2p.disable`                       | Completely disable the P2P stack                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`                   | `OP_NODE_P2P_DISABLE`                       |
| `--p2p.discovery.path`                | Discovered ENRs are persisted in a database to recover from a restart without having to bootstrap the discovery process again. Set to 'memory' to never persist the peerstore.                                                                                                                                                                                                                                                                                                                                                     | `"opnode_discovery_db"`   | `OP_NODE_P2P_DISCOVERY_PATH`                |
| `--p2p.gossip.timestamp.threshold`    | Threshold for rejecting gossip messages with payload timestamps older than this duration. Default is 60 seconds.                                                                                                                                                                                                                                                                                                                                                                                                                   | `1m0s`                    | `OP_NODE_P2P_GOSSIP_TIMESTAMP_THRESHOLD`    |
| `--p2p.listen.ip`                     | IP to bind LibP2P and Discv5 to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `"0.0.0.0"`               | `OP_NODE_P2P_LISTEN_IP`                     |
| `--p2p.listen.tcp`                    | TCP port to bind LibP2P to. Any available system port if set to 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `9222`                    | `OP_NODE_P2P_LISTEN_TCP_PORT`               |
| `--p2p.listen.udp`                    | UDP port to bind Discv5 to. Same as TCP port if left 0.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `0`                       | `OP_NODE_P2P_LISTEN_UDP_PORT`               |
| `--p2p.nat`                           | Enable NAT traversal with PMP/UPNP devices to learn external IP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `false`                   | `OP_NODE_P2P_NAT`                           |
| `--p2p.netrestrict`                   | Comma-separated list of CIDR masks. P2P will only try to connect on these networks                                                                                                                                                                                                                                                                                                                                                                                                                                                 | —                         | `OP_NODE_P2P_NETRESTRICT`                   |
| `--p2p.no-discovery`                  | Disable Discv5 (node discovery)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `false`                   | `OP_NODE_P2P_NO_DISCOVERY`                  |
| `--p2p.peers.grace`                   | Grace period to keep a newly connected peer around, if it is not misbehaving.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `30s`                     | `OP_NODE_P2P_PEERS_GRACE`                   |
| `--p2p.peers.hi`                      | High-tide peer count. The node starts pruning peer connections slowly after reaching this number.                                                                                                                                                                                                                                                                                                                                                                                                                                  | `30`                      | `OP_NODE_P2P_PEERS_HI`                      |
| `--p2p.peers.lo`                      | Low-tide peer count. The node actively searches for new peer connections if below this amount.                                                                                                                                                                                                                                                                                                                                                                                                                                     | `20`                      | `OP_NODE_P2P_PEERS_LO`                      |
| `--p2p.peerstore.path`                | Peerstore database location. Persisted peerstores help recover peers after restarts. Set to 'memory' to never persist the peerstore. Peerstore records will be pruned / expire as necessary. Warning: a copy of the priv network key of the local peer will be persisted here.                                                                                                                                                                                                                                                     | `"opnode_peerstore_db"`   | `OP_NODE_P2P_PEERSTORE_PATH`                |
| `--p2p.priv.path`                     | Read the hex-encoded 32-byte private key for the peer ID from this txt file. Created if not already exists.Important to persist to keep the same network identity after restarting, maintaining the previous advertised identity.                                                                                                                                                                                                                                                                                                  | `"opnode_p2p_priv.txt"`   | `OP_NODE_P2P_PRIV_PATH`                     |
| `--p2p.scoring`                       | Sets the peer scoring strategy for the P2P stack. Can be one of: none or light.                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `"light"`                 | `OP_NODE_P2P_PEER_SCORING`                  |
| `--p2p.sequencer.key`                 | Hex-encoded private key for signing off on p2p application messages as sequencer.                                                                                                                                                                                                                                                                                                                                                                                                                                                  | —                         | `OP_NODE_P2P_SEQUENCER_KEY`                 |
| `--p2p.static`                        | Comma-separated multiaddr-format peer list. Static connections to make and maintain, these peers will be regarded as trusted. Addresses of the local peer are ignored. Duplicate/Alternative addresses for the same peer all apply, but only a single connection per peer is maintained.                                                                                                                                                                                                                                           | —                         | `OP_NODE_P2P_STATIC`                        |
| `--p2p.sync.req-resp`                 | Enables the P2P req-resp sync server, which serves payloads-by-number to peers that request them. The client side has been removed; the server will be deprecated in a future release in favor of EL P2P sync.                                                                                                                                                                                                                                                                                                                     | `true`                    | `OP_NODE_P2P_SYNC_REQ_RESP`                 |
| `--pprof.addr`                        | pprof listening address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"0.0.0.0"`               | `OP_NODE_PPROF_ADDR`                        |
| `--pprof.enabled`                     | Enable the pprof server                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                   | `OP_NODE_PPROF_ENABLED`                     |
| `--pprof.path`                        | pprof file path. If it is a directory, the path is \{dir}/\{profileType}.prof                                                                                                                                                                                                                                                                                                                                                                                                                                                      | —                         | `OP_NODE_PPROF_PATH`                        |
| `--pprof.port`                        | pprof listening port                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `6060`                    | `OP_NODE_PPROF_PORT`                        |
| `--pprof.type`                        | pprof profile type. One of cpu, heap, goroutine, threadcreate, block, mutex, allocs                                                                                                                                                                                                                                                                                                                                                                                                                                                | —                         | `OP_NODE_PPROF_TYPE`                        |
| `--rollup.config`                     | Rollup chain parameters                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | —                         | `OP_NODE_ROLLUP_CONFIG`                     |
| `--rollup.l1-chain-config`            | Path to .json file with the chain configuration for the L1, either in the direct format or genesis.json format (i.e. embedded under the .config property). Not necessary / will be ignored if using Ethereum mainnet or Sepolia as an L1.                                                                                                                                                                                                                                                                                          | —                         | `OP_NODE_ROLLUP_L1_CHAIN_CONFIG`            |
| `--rpc.addr`                          | rpc listening address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"0.0.0.0"`               | `OP_NODE_RPC_ADDR`                          |
| `--rpc.admin-state`                   | File path used to persist state changes made via the admin API so they persist across restarts. Disabled if not set.                                                                                                                                                                                                                                                                                                                                                                                                               | —                         | `OP_NODE_RPC_ADMIN_STATE`                   |
| `--rpc.enable-admin`                  | Enable the admin API                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `false`                   | `OP_NODE_RPC_ENABLE_ADMIN`                  |
| `--rpc.port`                          | rpc listening port                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `9545`                    | `OP_NODE_RPC_PORT`                          |
| `--safedb.path`                       | File path used to persist safe head update data. Disabled if not set.                                                                                                                                                                                                                                                                                                                                                                                                                                                              | —                         | `OP_NODE_SAFEDB_PATH`                       |
| `--sequencer.enabled`                 | Enable sequencing of new L2 blocks. A separate batch submitter has to be deployed to publish the data for verifiers.                                                                                                                                                                                                                                                                                                                                                                                                               | `false`                   | `OP_NODE_SEQUENCER_ENABLED`                 |
| `--sequencer.l1-confs`                | Number of L1 blocks to keep distance from the L1 head as a sequencer for picking an L1 origin.                                                                                                                                                                                                                                                                                                                                                                                                                                     | `4`                       | `OP_NODE_SEQUENCER_L1_CONFS`                |
| `--sequencer.max-safe-lag`            | Maximum number of L2 blocks for restricting the distance between L2 safe and unsafe. Disabled if 0.                                                                                                                                                                                                                                                                                                                                                                                                                                | `0`                       | `OP_NODE_SEQUENCER_MAX_SAFE_LAG`            |
| `--sequencer.recover`                 | Forces the sequencer to strictly prepare the next L1 origin and create empty L2 blocks                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                   | `OP_NODE_SEQUENCER_RECOVER`                 |
| `--sequencer.sealing-duration`        | This is the amount of the time the sequencer allocates to sealing the block (i.e. it will fetch the payload from the execution engine this much prior to the block's timestamp). If this is \<= 0 it is automatically adjusted to 50ms.                                                                                                                                                                                                                                                                                            | `50ms`                    | `OP_NODE_SEQUENCER_SEALING_DURATION`        |
| `--sequencer.stopped`                 | Initialize the sequencer in a stopped state. The sequencer can be started using the admin\_startSequencer RPC                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                   | `OP_NODE_SEQUENCER_STOPPED`                 |
| `--signer.address`                    | Address the signer is signing requests for                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | —                         | `OP_NODE_SIGNER_ADDRESS`                    |
| `--signer.endpoint`                   | Signer endpoint the client will connect to                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | —                         | `OP_NODE_SIGNER_ENDPOINT`                   |
| `--signer.header`                     | Headers to pass to the remote signer. Format `key=value`. Value can contain any character allowed in a HTTP header. When using env vars, split with commas. When using flags one key value pair per flag.                                                                                                                                                                                                                                                                                                                          | —                         | `OP_NODE_SIGNER_HEADER`                     |
| `--signer.tls.ca`                     | tls ca cert path                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `"tls/ca.crt"`            | `OP_NODE_SIGNER_TLS_CA`                     |
| `--signer.tls.cert`                   | tls cert path                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `"tls/tls.crt"`           | `OP_NODE_SIGNER_TLS_CERT`                   |
| `--signer.tls.enabled`                | Enable or disable TLS client authentication for the signer                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `true`                    | `OP_NODE_SIGNER_TLS_ENABLED`                |
| `--signer.tls.key`                    | tls key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"tls/tls.key"`           | `OP_NODE_SIGNER_TLS_KEY`                    |
| `--syncmode`                          | Blockchain sync mode (options: consensus-layer, execution-layer)                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `consensus-layer`         | `OP_NODE_SYNCMODE`                          |
| `--syncmode.offset-el-safe`           | After execution-layer sync completes, set safe and finalized heads to this duration behind the synced tip (converted to L2 blocks via rollup block time using ceiling division). Default 12h, matching the OP Mainnet sequencing window.                                                                                                                                                                                                                                                                                           | `12h0m0s`                 | `OP_NODE_SYNCMODE_OFFSET_EL_SAFE`           |
| `--verifier.l1-confs`                 | Number of L1 blocks to keep distance from the L1 head before deriving L2 data from. Reorgs are supported, but may be slow to perform.                                                                                                                                                                                                                                                                                                                                                                                              | `0`                       | `OP_NODE_VERIFIER_L1_CONFS`                 |

## Notes on selected flags

### network and rollup.config

In addition to the required flags above, the op-node must be told which chain
it serves: set exactly one of `--network` (a chain bundled from the
superchain-registry, e.g. `op-mainnet`) or `--rollup.config` (a rollup
configuration file, for custom chains). Setting both, or neither, is a startup
error.

### l1.trustrpc

<Info>
  If you're running an Erigon Ethereum execution client for your L1 provider
  you will need to include `--l1.trustrpc`. At the time of writing, Erigon
  doesn't support the `eth_getProof` method that op-node prefers to use to
  load L1 data for some processing. The trustrpc flag makes it use something
  else that Erigon supports, but the op-node can't verify for correctness.
</Info>

### syncmode.offset-el-safe

Only effective with `--syncmode=execution-layer`. After execution-layer sync
completes, the safe and finalized heads are set to this duration behind the
synced tip (converted to L2 blocks using the rollup block time). The default
`12h` matches the OP Mainnet sequencing window.

Setting this to `0` leaves safe and finalized at the synced tip. This is
**not recommended and is dangerous**: the offset ensures the node does not
label the EL-sync tip as safe/finalized until L1 has had time to confirm it.
With `0`, an EL-sync tip that later turns out to be on a reorged
(non-canonical) branch can be marked safe/finalized, and safe/finalized are
not supposed to reorg. Fix a body-pruning mismatch by enlarging the EL's
retained body window instead — see the warning below.

<Warning>
  op-node reads the L1-info deposit transaction from the block body at the
  head placed this far behind the tip, so the execution client must retain
  block bodies at least this far back. Body pruning (op-reth's `--minimal`
  mode or `--prune.bodies.distance`) is unsupported; if you enable it anyway,
  keep the retained body window comfortably larger than this offset (in
  blocks), or EL sync fails with `l2 block is missing L1 info deposit tx`.
  See [Pruning op-reth](/node-operators/guides/management/archive-node#pruning-op-reth).
</Warning>

### sequencer.l1-confs

<Warning>
  The maximum value for `sequencer.l1-confs` cannot exceed the sequencer
  drift, currently set to 30 minutes (1800 seconds or 150 blocks). Setting a
  value higher than this limit will prevent the sequencer from producing
  blocks within the sequence window.
</Warning>

### verifier.l1-confs

<Info>
  While `verifier.l1-confs` has no strict limit, it's recommended to keep this
  value within 12-13 minutes (typically 10-20 blocks) for optimal performance.
  Exceeding this range may impact the verifier's data processing efficiency.
</Info>

### altda.\*

The `altda.*` flags configure Alt-DA mode, a Beta feature of the OP Stack.
While it has received initial review from core contributors, it is still
undergoing testing, and may have bugs or other issues. See the
[Alt-DA mode guide](/chain-operators/guides/features/alt-da-mode-guide) for
setup instructions.

### interop.\*

The `interop.*` flags configure OP Stack interop networks. Interop is a highly
experimental feature; the flags apply only to interop-enabled networks. Do not
enable the interop RPC (`--interop.rpc.addr`) if you do not run a supervisor
service.

### version

<Info>
  Nodes built from source do not output the correct version numbers that are
  reported on the GitHub release page.
</Info>

## Node log levels

Node log levels determine the verbosity of log messages, allowing operators to filter messages based on importance and detail. The log levels for the `op-node` (used in Optimism)
are as follows:

1. Silent (0): No log messages are displayed. This level is rarely used as it provides
   no feedback on the node's status.

2. Error (1): Only error messages are displayed. Use this level to focus on critical
   issues that need immediate attention.

3. Warn (2): Displays error messages and warnings. This level helps to identify
   potential problems that might not be immediately critical but require attention.

4. Info (3): Displays error messages, warnings, and normal activity logs. This is the
   default level and provides a balanced view of the node's operations without being too
   verbose.

5. Debug (4): All info-level messages plus additional debugging information. Use this
   level when troubleshooting issues or developing the node software.

6. Detail (5): The most verbose level, including detailed debugging information and
   low-level system operations. This level generates a large amount of log data and is
   typically used only for in-depth troubleshooting.

To set the log level, use the `--log.level` flag when running the `op-node` command. For
example, to set the log level to debug:

```bash theme={null}
op-node --log.level=debug
```

By adjusting the log level, operators can control the amount and type of information that
gets logged, helping to manage log data volume and focus on relevant details during
different operational scenarios.


# op-node JSON-RPC API
Source: https://docs.optimism.io/node-operators/reference/op-node-json-rpc

Complete reference for op-node RPC methods including rollup-specific functionality.

`op-node` implements rollup-specific functionality as the Consensus Layer, similar to an L1 beacon node. It provides RPC methods for querying rollup state, managing peers, and controlling sequencer operations.

<Info>
  Use [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice) instead of `rollup_gasPrices` for the L2 gas price.
  For the L1 gas price, you can call the [`GasPriceOracle`'s `l1BaseFee` function](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F#readProxyContract#F11).
  If you want to estimate the cost of a transaction, you can [use the SDK](/app-developers/tutorials/transactions/sdk-estimate-costs).
</Info>

## Making RPC Requests

The following examples show you how to make requests with [`curl`](https://curl.se/) and [`cast`](https://book.getfoundry.sh/cast/).

<Info>
  Protip: piping these commands into [`jq`](https://jqlang.github.io/jq/) will give you nicely formatted JSON responses.

  `$ cast rpc optimism_syncStatus --rpc-url http://localhost:9545 | jq`
</Info>

## optimism Namespace

Optimism-specific rollup methods for querying chain state and configuration.

### optimism\_outputAtBlock

Get the output root at a specific block. This method is documented in [the specifications](https://specs.optimism.io/protocol/rollup-node.html?utm_source=op-docs\&utm_medium=docs#output-method-api).

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data  \
      '{"jsonrpc":"2.0","method":"optimism_outputAtBlock","params":["<hex_block_number>"],"id":1}' \
      http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc optimism_outputAtBlock <hex_block_number> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
   "jsonrpc":"2.0",
   "id":1,
   "result":[
      "0x0000000000000000000000000000000000000000000000000000000000000000",
      "0xabe711e34c1387c8c56d0def8ce77e454d6a0bfd26cef2396626202238442421"
   ]
}
```

### optimism\_syncStatus

Get the synchronization status of the rollup node. This method provides detailed information about L1 and L2 block processing states.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc optimism_syncStatus --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "current_l1": {
    "hash": "0xff3b3253058411b727ac662f4c9ae1698918179e02ecebd304beb1a1ae8fc4fd",
    "number": 4427350,
    "parentHash": "0xb26586390c3f04678706dde13abfb5c6e6bb545e59c22774e651db224b16cd48",
    "timestamp": 1696478784
  },
  "current_l1_finalized": {
    "hash": "0x7157f91b8ae21ef869c604e5b268e392de5aa69a9f44466b9b0f838d56426541",
    "number": 4706784,
    "parentHash": "0x1ac2612a500b9facd650950b8755d97cf2470818da2d88552dea7cd563e86a17",
    "timestamp": 1700160084
  },
  "head_l1": {
    "hash": "0x6110a8e6ed4c4aaab20477a3eac81bf99e505bf6370cd4d2e3c6d34aa5f4059a",
    "number": 4706863,
    "parentHash": "0xee8a9cba5d93481f11145c24890fd8f536384f3c3c043f40006650538fbdcb56",
    "timestamp": 1700161272
  },
  "safe_l1": {
    "hash": "0x8407c9968ce278ab435eeaced18ba8f2f94670ad9d3bdd170560932cf46e2804",
    "number": 4706811,
    "parentHash": "0x6593cccab3e772776418ff691f6e4e75597af18505373522480fdd97219c06ef",
    "timestamp": 1700160480
  },
  "finalized_l1": {
    "hash": "0x7157f91b8ae21ef869c604e5b268e392de5aa69a9f44466b9b0f838d56426541",
    "number": 4706784,
    "parentHash": "0x1ac2612a500b9facd650950b8755d97cf2470818da2d88552dea7cd563e86a17",
    "timestamp": 1700160084
  },
  "unsafe_l2": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  },
  "safe_l2": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  },
  "finalized_l2": {
    "hash": "0x285b03afb46faad747be1ca7ab6ef50ef0ff1fe04e4eeabafc54f129d180fad2",
    "number": 2337942,
    "parentHash": "0x7e7f36cba1fd1ccdcdaa81577a1732776a01c0108ab5f98986cf997724eb48ac",
    "timestamp": 1696478424,
    "l1origin": {
      "hash": "0x983309dadf7e0ab8447f3050f2a85b179e9acde1cd884f883fb331908c356412",
      "number": 4427314
    },
    "sequenceNumber": 7
  },
  "pending_safe_l2": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  },
  "queued_unsafe_l2": {
    "hash": "0x3af253f5b993f58fffdd5e594b3f53f5b7b254cdc18f4bdb13ea7331149942db",
    "number": 4054795,
    "parentHash": "0x284b7dc92bac97be8ec3b2cf548e75208eb288704de381f2557938ecdf86539d",
    "timestamp": 1699912130,
    "l1origin": {
      "hash": "0x1490a63c372090a0331e05e63ec6a7a6e84835f91776306531f28b4217394d76",
      "number": 4688196
    },
    "sequenceNumber": 2
  },
  "engine_sync_target": {
    "hash": "0x9a3b2edab72150de252d45cabe2f1ac57d48ddd52bb891831ffed00e89408fe4",
    "number": 2338094,
    "parentHash": "0x935b94ec0bac0e63c67a870b1a97d79e3fa84dda86d31996516cb2f940753f53",
    "timestamp": 1696478728,
    "l1origin": {
      "hash": "0x38731e0a6eeb40091f0c4a00650e911c57d054aaeb5b158f55cd5705fa6a3ebf",
      "number": 4427339
    },
    "sequenceNumber": 3
  }
}
```

### optimism\_rollupConfig

Get the rollup configuration parameters.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"optimism_rollupConfig","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc optimism_rollupConfig --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "genesis": {
    "l1": {
      "hash": "0x48f520cf4ddaf34c8336e6e490632ea3cf1e5e93b0b2bc6e917557e31845371b",
      "number": 4071408
    },
    "l2": {
      "hash": "0x102de6ffb001480cc9b8b548fd05c34cd4f46ae4aa91759393db90ea0409887d",
      "number": 0
    },
    "l2_time": 1691802540,
    "system_config": {
      "batcherAddr": "0x8f23bb38f531600e5d8fddaaec41f13fab46e98c",
      "overhead": "0x00000000000000000000000000000000000000000000000000000000000000bc",
      "scalar": "0x00000000000000000000000000000000000000000000000000000000000a6fe0",
      "gasLimit": 30000000
    }
  },
  "block_time": 2,
  "max_sequencer_drift": 600,
  "seq_window_size": 3600,
  "channel_timeout": 300,
  "l1_chain_id": 11155111,
  "l2_chain_id": 11155420,
  "regolith_time": 0,
  "canyon_time": 1699981200,
  "batch_inbox_address": "0xff00000000000000000000000000000011155420",
  "deposit_contract_address": "0x16fc5058f25648194471939df75cf27a2fdc48bc",
  "l1_system_config_address": "0x034edd2a225f7f429a63e0f1d2084b9e0a93b538"
}
```

### optimism\_version

Get the software version of the op-node.

<Info>
  At the moment, building from source will not give you the correct version, but our docker images will.
</Info>

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"optimism_version","params":[],"id":1}' \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc optimism_version --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
   "jsonrpc":"2.0",
   "id":1,
   "result":"v0.0.0-"
}
```

## opp2p Namespace

The `opp2p` namespace handles peer-to-peer networking interactions, allowing you to manage peer connections, discovery, and network policies.

### opp2p\_self

Returns your node's peer information including peer ID, addresses, and network configuration.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_self","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_self --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "peerID": "16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE",
    "nodeID": "75a52a90fe5f972171fefce2399ca5a73191c654e7c7ddfdd71edf4fca6697f0",
    "userAgent": "",
    "protocolVersion": "",
    "ENR": "enr:-J-4QFOtI_hDBa_kilrQcg4iTJt9VMAuDLCbgAAKMa--WfxoPml1xDYxypUG7IsWga83FOlvr78LG3oH8CfzRzUmsDyGAYvKqIZ2gmlkgnY0gmlwhGxAaceHb3BzdGFja4Xc76gFAIlzZWNwMjU2azGhAnAON-FvpiWY2iG_LXJDYosknGyikaajPDd1cQARsVnBg3RjcIIkBoN1ZHCC0Vs",
    "addresses": [
      "/ip4/127.0.0.1/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE",
      "/ip4/192.168.1.71/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE",
      "/ip4/108.64.105.199/tcp/9222/p2p/16Uiu2HAm2y6DXp6THWHCyquczNUh8gVAm4spo6hjP3Ns1dGRiAdE"
    ],
    "protocols": null,
    "connectedness": 0,
    "direction": 0,
    "protected": false,
    "chainID": 0,
    "latency": 0,
    "gossipBlocks": true,
    "scores": {
      "gossip": {
        "total": 0,
        "blocks": {
          "timeInMesh": 0,
          "firstMessageDeliveries": 0,
          "meshMessageDeliveries": 0,
          "invalidMessageDeliveries": 0
        },
        "IPColocationFactor": 0,
        "behavioralPenalty": 0
      },
      "reqResp": {
        "validResponses": 0,
        "errorResponses": 0,
        "rejectedPayloads": 0
      }
    }
  }
}
```

### opp2p\_peers

Returns a list of your node's peers with detailed connection information.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_peers","params":[true],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_peers true --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "totalConnected": 20,
    "peers": {
      "16Uiu2HAkvNYscHu4V1uj6fVWkwrAMCRsqXDSq4mUbhpGq4LttYsC": {
        "peerID": "16Uiu2HAkvNYscHu4V1uj6fVWkwrAMCRsqXDSq4mUbhpGq4LttYsC",
        "nodeID": "d693c5b58424016c0c38ec5539c272c754cb6b8007b322e0ecf16a4ee13f96fb",
        "userAgent": "optimism",
        "protocolVersion": "",
        "ENR": "",
        "addresses": [
          "/ip4/20.249.62.215/tcp/9222/p2p/16Uiu2HAkvNYscHu4V1uj6fVWkwrAMCRsqXDSq4mUbhpGq4LttYsC"
        ],
        "protocols": [
          "/ipfs/ping/1.0.0",
          "/meshsub/1.0.0",
          "/meshsub/1.1.0",
          "/opstack/req/payload_by_number/11155420/0",
          "/floodsub/1.0.0",
          "/ipfs/id/1.0.0",
          "/ipfs/id/push/1.0.0"
        ],
        "connectedness": 1,
        "direction": 1,
        "protected": false,
        "chainID": 0,
        "latency": 0,
        "gossipBlocks": true,
        "scores": {
          "gossip": {
            "total": -5.04,
            "blocks": {
              "timeInMesh": 0,
              "firstMessageDeliveries": 0,
              "meshMessageDeliveries": 0,
              "invalidMessageDeliveries": 0
            },
            "IPColocationFactor": 0,
            "behavioralPenalty": 0
          },
          "reqResp": {
            "validResponses": 0,
            "errorResponses": 0,
            "rejectedPayloads": 0
          }
        }
      }
    },
    "bannedPeers": [],
    "bannedIPS": [],
    "bannedSubnets": []
  }
}
```

### opp2p\_peerStats

Returns aggregate statistics about your peer connections.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_peerStats","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_peerStats --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "connected": 20,
    "table": 94,
    "blocksTopic": 20,
    "blocksTopicV2": 18,
    "banned": 0,
    "known": 71
  }
}
```

### opp2p\_discoveryTable

Returns your peer discovery table containing node records (ENRs) of discovered peers.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_discoveryTable","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_discoveryTable --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
  "enr:-J24QGC_SzoGG4EqyvO_082paQOwhvECeWGT-kaenrHdE2_iLTLeGmH-IOVpqEjC0L-yWmkI-c7598VaCjHQRNWn1CyGAYsqDgrFgmlkgnY0gmlwhNgp3WeHb3BzdGFja4OFQgCJc2VjcDI1NmsxoQPiq20PNZYzyvpEifcGVrOXHfM94JeWSgDL07I2hSl0d4N0Y3CCJAaDdWRwgiQG",
  "enr:-J24QKvt2ThBM8-FPeHfAmpoaVLdfVD2cw1cRpNuwmvH_bQtQ1dqrrZw9FqiMbXbFRQf9IvjrlKSFLodbsRALIFATICGAYuQClJigmlkgnY0gmlwhKI3ZuaHb3BzdGFja4O6BACJc2VjcDI1NmsxoQLQRz2CH95qQd6vmF5saV-WOoTZobNfSt-FUdVa7R35nYN0Y3CCIyuDdWRwgiMr"
  ]
}
```

### opp2p\_blockPeer

Blocks a peer by peer ID, preventing future connections.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_blockPeer","params":["<peerID>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_blockPeer <peerID> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_unblockPeer

Unblocks a previously blocked peer.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_unblockPeer","params":["<peerID>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_unblockPeer <peerID> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_listBlockedPeers

Returns a list of blocked peer IDs.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_listBlockedPeers","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_listBlockedPeers --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "16Uiu2HAmV3PueiaHj7Rg2bs3mrRUo2RVhjXRMpH67k9iZquDGQ8v"
  ]
}
```

### opp2p\_blockAddr

Blocks connections from a specific IP address.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_blockAddr","params":["<ip-address>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_blockAddr <ip-address> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_unblockAddr

Unblocks a previously blocked IP address.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_unblockAddr","params":["<ip-address>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_unblockAddr <ip-address> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_listBlockedAddrs

Returns a list of blocked IP addresses.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_listBlockedAddrs","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_listBlockedAddrs --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    "2607:f8b0:4002:c0c::65"
  ]
}
```

### opp2p\_blockSubnet

Blocks connections from a specific subnet (CIDR notation).

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_blockSubnet","params":["<subnet>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_blockSubnet <subnet> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_unblockSubnet

Unblocks a previously blocked subnet.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_unblockSubnet","params":["<subnet>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_unblockSubnet <subnet> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_listBlockedSubnets

Returns a list of blocked subnets.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_listBlockedSubnets","params":[],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_listBlockedSubnets --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": []
}
```

### opp2p\_protectPeer

Protects a peer from being pruned from the connection pool.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_protectPeer","params":["<peerID>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_protectPeer <peerID> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_unprotectPeer

Removes protection from a peer, allowing it to be pruned if necessary.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_unprotectPeer","params":["<peerID>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_unprotectPeer <peerID> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_connectPeer

Initiates a connection to a peer using its multiaddress.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_connectPeer","params":["<peer multiaddr>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_connectPeer <peer multiaddr> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### opp2p\_disconnectPeer

Disconnects from a specific peer.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"opp2p_disconnectPeer","params":["<peerID>"],"id":1}'  \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc opp2p_disconnectPeer <peerID> --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

## admin Namespace

Administrative methods for controlling sequencer operations and the derivation pipeline.

### admin\_resetDerivationPipeline

Resets the derivation pipeline, forcing it to re-derive L2 blocks from L1 data.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"admin_resetDerivationPipeline","params":[],"id":1}' \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc admin_resetDerivationPipeline --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### admin\_startSequencer

Starts the sequencer if it was previously stopped. This allows the node to begin producing new blocks.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"admin_startSequencer","params":[],"id":1}' \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc admin_startSequencer --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### admin\_stopSequencer

Stops the sequencer, preventing it from producing new blocks. The node will continue to sync from other sequencers.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"admin_stopSequencer","params":[],"id":1}' \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc admin_stopSequencer --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": null
}
```

### admin\_sequencerActive

Returns whether the sequencer is currently active and producing blocks.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
        '{"jsonrpc":"2.0","method":"admin_sequencerActive","params":[],"id":1}' \
        http://localhost:9545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast rpc admin_sequencerActive --rpc-url http://localhost:9545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": true
}
```


# op-reth configuration options
Source: https://docs.optimism.io/node-operators/reference/op-reth-config

Where to find the op-reth CLI reference, and how op-reth pairs with op-node.

op-reth's flag reference lives in one place: the
[op-reth CLI reference](/node-operators/op-reth/cli/overview), imported into these docs
from the op-reth source tree and versioned with it. Start there for the
command taxonomy and configuration model, or jump straight to the
[`op-reth node` flag listing](/node-operators/op-reth/cli/op-reth/node) for the full
`--help` output of the command node operators run.

This page previously carried a hand-maintained copy of the op-reth flag
catalog, pinned to an old release; it has been retired in favor of the single
imported surface above so the flag facts cannot drift between two pages.

<Info>
  **op-reth is the recommended execution client for new OP Stack deployments.** op-node's `--l2.enginekind` flag defaults to `reth`, so no extra engine-kind configuration is needed when pairing the two; set it explicitly only when running a different execution client (`geth` or `erigon`). See the [op-node configuration options](/node-operators/reference/op-node-config) page for the engine-side flags.
</Info>

## Related references

* [op-reth JSON-RPC reference](/node-operators/reference/op-reth-json-rpc)
* [op-reth historical proofs configuration](/node-operators/reference/op-reth-historical-proof-config)
* [Building an archive node / pruning op-reth](/node-operators/guides/management/archive-node)
* Upstream cross-reference: [Reth CLI documentation](https://reth.rs/cli/reth.html)


# op-reth historical proof configuration
Source: https://docs.optimism.io/node-operators/reference/op-reth-historical-proof-config

Configuration options for the op-reth historical proof store (v2).

This page documents the configuration options for the **historical proof store (v2)** in [op-reth](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-reth).

When enabled, op-reth maintains a separate storage database for versioned trie data used to serve `eth_getProof` for historical blocks. This is critical for historical state access (for example, fault proof workloads) without requiring full archive-style behavior from the execution database.

<Warning>
  op-reth **v2.2.3 or later** is required to enable historical proofs v2. Earlier versions do not support the `--proofs-history.storage-version=v2` flag.
</Warning>

<Info>
  Use the **historical proofs storage format v2** by setting `--proofs-history.storage-version=v2`.
</Info>

For a complete setup guide, see the tutorial on [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs).

<Info>
  This fork inherits all standard op-reth configuration options. See the [op-reth configuration reference](/node-operators/reference/op-reth-config).
</Info>

## Historical proof store (v2)

Options for configuring the v2 historical proof store.

### proofs-history

If true, enable the historical proof store and keep it updated as new blocks are processed.

<Tabs>
  <Tab title="Syntax">`--proofs-history`</Tab>
</Tabs>

### proofs-history.storage-version

Storage format version for the historical proofs database.

For the v2 system, set this to `v2`.

<Tabs>
  <Tab title="Syntax">`--proofs-history.storage-version <PROOFS_HISTORY_STORAGE_VERSION>`</Tab>
  <Tab title="Recommended">`v2`</Tab>
</Tabs>

### proofs-history.storage-path

The path to the storage DB for proofs history.

<Tabs>
  <Tab title="Syntax">`--proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH>`</Tab>
</Tabs>

### proofs-history.window

The window to span blocks for proofs history. Value is the number of blocks.
Default is 1 month of blocks based on 2 seconds block time (`30 * 24 * 60 * 60 / 2 = 1,296,000`).

<Tabs>
  <Tab title="Syntax">`--proofs-history.window <PROOFS_HISTORY_WINDOW>`</Tab>
  <Tab title="Default">`1296000`</Tab>
</Tabs>

### proofs-history.verification-interval

Verification interval: perform full block execution every N blocks for data integrity.

* `0`: Disabled (Default). Always use fast path with pre-computed data.
* `1`: Always verify. Always execute blocks.
* `N`: Verify every Nth block (e.g., 100 = every 100 blocks).

Periodic verification helps catch data corruption while maintaining good performance.

<Tabs>
  <Tab title="Syntax">`--proofs-history.verification-interval <PROOFS_HISTORY_VERIFICATION_INTERVAL>`</Tab>
  <Tab title="Default">`0`</Tab>
</Tabs>

## Lifecycle and management commands

In v2, operators usually follow this lifecycle:

1. Run `op-reth proofs init` once to initialize the proofs DB at the current tip.
2. Start `op-reth` with `--proofs-history --proofs-history.storage-version=v2` so the node uses historical proofs storage format v2.
3. Let the store fill proofs data **forward** from the initialization point.
4. Let automatic pruning enforce the configured retention window.
5. Use manual `prune` or `unwind` only for recovery/maintenance scenarios.

The `op-reth proofs` command provides these maintenance operations.

### init

Initialize the proofs storage with the current state of the chain.

```bash theme={null}
op-reth proofs init --chain <CHAIN> --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --proofs-history.storage-version=v2
```

<Info>
  The first time `proofs init` runs, it can take minutes to hours. Subsequent invocations should usually take seconds.

  `proofs init` does **not** backfill historical proofs. It records the current chain tip as the starting point of the proofs database. After initialization, run the node with `--proofs-history` so the store fills forward as new blocks are committed.

  To serve proofs across the full retention window (for example, 30 days with default settings), the node must accumulate that much forward history after init. In practice, operators should initialize from a snapshot that is already old enough to satisfy the required historical window as syncing advances.
</Info>

### prune

Prune old proof history to reclaim space.

```bash theme={null}
op-reth proofs prune --chain <CHAIN> --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --proofs-history.window <PROOFS_HISTORY_WINDOW>
```

<Info>
  Pruning runs automatically while the node is up, driven by the engine task as new blocks are committed; no separate interval flag is required.

  Manual prune is mainly a recovery action, for example if op-reth detects a large mismatch between configured retention and on-disk data and refuses startup. See the [tutorial](/node-operators/tutorials/reth-historical-proofs#manual-prune) for details.
</Info>

### unwind

Unwind the proofs storage to a specific block

```bash theme={null}
op-reth proofs unwind --datadir <DATA_DIR> --proofs-history.storage-path <PROOFS_HISTORY_STORAGE_PATH> --target <TARGET_BLOCK>
```

## RPC Endpoints

### debug\_proofsSyncStatus

Returns the current sync status of the proofs store.

```
debug_proofsSyncStatus → { "earliest": <block>, "latest": <block> }
```

`earliest` and `latest` define the currently available historical-proof interval in the v2 store.

Once `latest` tracks chain tip, `eth_getProof` calls for blocks within `[earliest, latest]` are served from the versioned proofs store.

## v1 to v2 operator notes

* The historical-proof path is now centered on a dedicated versioned proofs store lifecycle (`init` -> forward fill -> prune), rather than treating it as a standalone extension workflow.
* `proofs init` establishes a starting point only; it does not reconstruct old proofs data.
* Coverage is operationally measured via `debug_proofsSyncStatus` (`earliest`/`latest`).
* For stable long-window proof serving, validate startup snapshots and retention settings together.

## Metrics

When the `metrics` feature is enabled, the proofs-history system exposes Prometheus metrics to monitor health and performance.

### Block processing (`optimism_trie.block.*`)

| Metric                               | Type      | Description                                 |
| ------------------------------------ | --------- | ------------------------------------------- |
| `total_duration_seconds`             | Histogram | End-to-end time to process a block          |
| `execution_duration_seconds`         | Histogram | Time spent in EVM execution                 |
| `state_root_duration_seconds`        | Histogram | Time spent calculating state root           |
| `write_duration_seconds`             | Histogram | Time spent writing trie updates to storage  |
| `account_trie_updates_written_total` | Counter   | Number of account trie branch nodes written |
| `storage_trie_updates_written_total` | Counter   | Number of storage trie branch nodes written |
| `hashed_accounts_written_total`      | Counter   | Number of hashed account entries written    |
| `hashed_storages_written_total`      | Counter   | Number of hashed storage entries written    |
| `earliest_number`                    | Gauge     | Earliest block number in the proofs store   |
| `latest_number`                      | Gauge     | Latest block number in the proofs store     |

### Pruner (`optimism_trie.pruner.*`)

| Metric                         | Type      | Description                                      |
| ------------------------------ | --------- | ------------------------------------------------ |
| `total_duration_seconds`       | Histogram | Duration of each prune run                       |
| `pruned_blocks`                | Gauge     | Number of blocks pruned in the last run          |
| `account_trie_updates_written` | Gauge     | Account trie entries deleted in the last prune   |
| `storage_trie_updates_written` | Gauge     | Storage trie entries deleted in the last prune   |
| `hashed_accounts_written`      | Gauge     | Hashed account entries deleted in the last prune |
| `hashed_storages_written`      | Gauge     | Hashed storage entries deleted in the last prune |

### RPC (`optimism_rpc.eth_api_ext.*`)

| Metric                           | Type      | Description                                   |
| -------------------------------- | --------- | --------------------------------------------- |
| `get_proof_latency`              | Histogram | Latency of successful `eth_getProof` requests |
| `get_proof_requests`             | Counter   | Total `eth_getProof` requests received        |
| `get_proof_successful_responses` | Counter   | Total successful `eth_getProof` responses     |
| `get_proof_failures`             | Counter   | Total failed `eth_getProof` requests          |

### Storage operations (`optimism_trie.storage.operation.*`)

Per-operation `duration_seconds` histograms are recorded for: `store_account_branch`, `store_storage_branch`, `store_hashed_account`, `store_hashed_storage`, `trie_cursor_seek_exact`, `trie_cursor_seek`, `trie_cursor_next`, `trie_cursor_current`, `hashed_cursor_seek`, `hashed_cursor_next`.


# op-reth JSON-RPC API
Source: https://docs.optimism.io/node-operators/reference/op-reth-json-rpc

Complete reference for op-reth execution client RPC methods with OP Stack enhancements.

`op-reth` is the Rust execution client for the OP Stack, based on [Reth](https://github.com/paradigmxyz/reth). It implements the same Engine API and Ethereum JSON-RPC surface as `op-geth`, so it is a drop-in alternative on OP Stack chains.

This page documents the JSON-RPC methods that were tested against an OP Stack devnet running `op-reth v2.2.3` (build `reth/v2.2.0-88505c7`) with the V2 (Jovian) fee model active.

## Overview

`op-reth` implements the standard Ethereum JSON-RPC API with the same OP Stack additions as `op-geth`. Familiar Ethereum tools (cast, web3.js, ethers, viem, …) work without modification.

<Info>
  The execution engine's RPC interface is functionally identical to [the upstream Reth RPC interface](https://reth.rs/run/run-a-node.html#rpc-namespaces). The OP-specific behavior matches `op-geth`: transaction receipts include additional L1 data-availability fee fields, and deposit transactions (type `0x7e`) carry OP-specific fields.
</Info>

## Key Differences from Ethereum

While `op-reth` maintains compatibility with Ethereum's JSON-RPC API, there are important differences shared with the wider OP Stack:

### Transaction Receipts

User transaction receipts include additional L1 data fee information. With the **V2 (Jovian) fee model** the fields are:

* **`l1GasUsed`** — Amount of L1 gas attributed to L1 data availability.
* **`l1GasPrice`** — L1 base fee at the time of execution.
* **`l1Fee`** — Total L1 data fee charged in wei.
* **`l1BaseFeeScalar`** — Scalar applied to the L1 base fee component.
* **`l1BlobBaseFee`** — L1 blob base fee at the time of execution.
* **`l1BlobBaseFeeScalar`** — Scalar applied to the L1 blob base fee component.
* **`daFootprintGasScalar`** — Scalar applied to the data-availability footprint.

<Warning>
  The legacy single-scalar field **`l1FeeScalar`** (used by Bedrock-era chains and still shown in older `op-geth` docs) is **not** present on V2 chains. Clients that hardcode `l1FeeScalar` need to read the new scalar fields above. The `l1GasUsed`, `l1GasPrice`, and `l1Fee` fields are unchanged.
</Warning>

### Deposit transactions

OP Stack deposit transactions (`type: 0x7e`) include extra fields in both transaction and receipt responses:

* On the transaction: `sourceHash`, `mint`, `depositReceiptVersion`.
* On the receipt: `depositNonce`, `depositReceiptVersion`.

### Gas Price Calculation

For L2 gas prices, use the standard [`eth_gasPrice`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_gasprice) method.

For L1 gas prices and end-to-end fee estimation, use the [`GasPriceOracle`](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F) predeploy or [the Optimism SDK](/app-developers/tutorials/transactions/sdk-estimate-costs).

## Standard JSON-RPC Methods

All examples below were verified live against `op-reth v2.2.3`.

### eth\_blockNumber

Returns the number of the most recent block.

<Tabs>
  <Tab title="curl">
    ```sh theme={null}
    curl -X POST -H "Content-Type: application/json" --data \
      '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
      http://localhost:8545
    ```
  </Tab>

  <Tab title="cast">
    ```sh theme={null}
    cast block-number --rpc-url http://localhost:8545
    ```
  </Tab>
</Tabs>

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x1202c"
}
```

### eth\_chainId

Returns the currently configured chain ID, used for signing replay-protected transactions.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0x190a85e3" }
```

### eth\_syncing

Returns sync status.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_syncing","params":[],"id":1}' \
  http://localhost:8545
```

<Info>
  Unlike `op-geth`, `op-reth` always returns a **structured object** that lists each pipeline stage (`Headers`, `Bodies`, `Execution`, `MerkleExecute`, …) and their per-stage progress, even when the node is fully synced. Clients that treat any non-`false` response as "still syncing" need to compare `currentBlock` and `highestBlock` instead.
</Info>

Sample output (synced node):

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "startingBlock": "0x1202c",
    "currentBlock": "0x1202c",
    "highestBlock": "0x1202c",
    "stages": [
      { "name": "Headers", "block": "0x1202c" },
      { "name": "Bodies", "block": "0x1202c" },
      { "name": "Execution", "block": "0x1202c" },
      { "name": "MerkleExecute", "block": "0x1202c" },
      { "name": "Finish", "block": "0x1202c" }
    ]
  }
}
```

### eth\_getBalance

Returns the balance of the account at the given address.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getBalance","params":["0x4200000000000000000000000000000000000015","latest"],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0x0" }
```

### eth\_getTransactionByHash

Returns information about a transaction by transaction hash. Deposit transactions include `sourceHash`, `mint`, and `depositReceiptVersion`.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getTransactionByHash","params":["0x38a7db9aa2d7ec70d55ac7de90384279bdcad38ecdf68e3fcc4c6b649761daf9"],"id":1}' \
  http://localhost:8545
```

Sample success output (deposit transaction):

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "0x7e",
    "sourceHash": "0xdbad163233eb082b43df51b26625dcfbd997bcd2f0810a58a651c633516c4941",
    "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
    "to": "0x4200000000000000000000000000000000000015",
    "mint": "0x0",
    "value": "0x0",
    "gas": "0xf4240",
    "input": "0x3db6be2b…",
    "hash": "0x38a7db9aa2d7ec70d55ac7de90384279bdcad38ecdf68e3fcc4c6b649761daf9",
    "blockHash": "0x5bbabb299894fa2f763a0b6bbccc966b80e791aa49663b80fc9789e0f04183ea",
    "blockNumber": "0x1202c",
    "transactionIndex": "0x0",
    "blockTimestamp": "0x69fda224",
    "depositReceiptVersion": "0x1",
    "gasPrice": "0x0",
    "nonce": "0x1202b",
    "r": "0x0", "s": "0x0", "v": "0x0", "yParity": "0x0"
  }
}
```

### eth\_getTransactionReceipt

Returns the receipt of a transaction by hash. Includes OP Stack–specific L1 fee fields. The example below is a deposit-tx receipt (note the `depositNonce` / `depositReceiptVersion` fields and `l1Fee = 0`); a regular user-tx receipt will carry a non-zero `l1Fee` computed from the V2 scalars.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getTransactionReceipt","params":["0x38a7db9aa2d7ec70d55ac7de90384279bdcad38ecdf68e3fcc4c6b649761daf9"],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "type": "0x7e",
    "status": "0x1",
    "cumulativeGasUsed": "0xb44e",
    "logs": [],
    "logsBloom": "0x000…",
    "transactionHash": "0x38a7db9aa2d7ec70d55ac7de90384279bdcad38ecdf68e3fcc4c6b649761daf9",
    "transactionIndex": "0x0",
    "blockHash": "0x5bbabb299894fa2f763a0b6bbccc966b80e791aa49663b80fc9789e0f04183ea",
    "blockNumber": "0x1202c",
    "gasUsed": "0xb44e",
    "effectiveGasPrice": "0x0",
    "blobGasUsed": "0xabe0",
    "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
    "to": "0x4200000000000000000000000000000000000015",
    "contractAddress": null,
    "depositNonce": "0x1202b",
    "depositReceiptVersion": "0x1",
    "l1GasPrice": "0x35",
    "l1GasUsed": "0x6e7",
    "l1Fee": "0x0",
    "l1BaseFeeScalar": "0x558",
    "l1BlobBaseFee": "0x3",
    "l1BlobBaseFeeScalar": "0xc3c9d",
    "daFootprintGasScalar": "0x190"
  }
}
```

<Info>
  Notice the OP-specific fields at the end of the receipt: `l1GasUsed`, `l1GasPrice`, `l1Fee`, plus the V2 scalars `l1BaseFeeScalar`, `l1BlobBaseFee`, `l1BlobBaseFeeScalar`, and `daFootprintGasScalar`. The Bedrock-era `l1FeeScalar` field is **not** present on V2 chains.
</Info>

### eth\_call

Executes a new message call immediately without creating a transaction on the blockchain. Example calls `GasPriceOracle.l1BaseFee()`.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_call","params":[{"to":"0x420000000000000000000000000000000000000F","data":"0x519b4bd3"},"latest"],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0000000000000000000000000000000000000000000000000000000000000030"
}
```

### eth\_estimateGas

Generates and returns an estimate of gas needed for a transaction to complete.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_estimateGas","params":[{"from":"0x0000000000000000000000000000000000000001","to":"0x0000000000000000000000000000000000000002","value":"0x0"}],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0x52e9" }
```

<Warning>
  `eth_estimateGas` only estimates L2 execution gas. To calculate the total transaction cost including L1 data fees, use the [Optimism SDK](/app-developers/tutorials/transactions/sdk-estimate-costs) or query the [`GasPriceOracle` predeployed contract](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F).
</Warning>

### eth\_sendRawTransaction

Submits a signed transaction to the network. The example payload is intentionally invalid to demonstrate the error shape.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_sendRawTransaction","params":["0xd46e8dd67c5d32be8d46e8dd67c5d32be8058bb8eb970870f072445675058bb8eb970870f072445675"],"id":1}' \
  http://localhost:8545
```

Sample error output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32602, "message": "failed to decode signed transaction" }
}
```

A well-formed signed transaction returns the transaction hash as `result`.

### eth\_getBlockByNumber

Returns information about a block by block number. Op-reth populates the standard post-Ecotone/Cancun fields: `withdrawalsRoot`, `blobGasUsed`, `excessBlobGas`, `parentBeaconBlockRoot`, and `requestsHash`.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["0x1b4",false],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "hash": "0x791e5f88a078641354af3c85dbd009b5658e36e1509a2262c11f8a7fc51c2883",
    "parentHash": "0xa4d2ce03caea13be2262673a58860ac2e717a00d6cf02fee63d7ce61327c32b9",
    "miner": "0x4200000000000000000000000000000000000011",
    "number": "0x1b4",
    "gasLimit": "0x3938700",
    "gasUsed": "0xb44e",
    "timestamp": "0x69fb6534",
    "baseFeePerGas": "0xa787b25",
    "withdrawalsRoot": "0x8ed4baae3a927be3dea54996b4d5899f8c01e7594bf50b17dc1e741388ce3d12",
    "blobGasUsed": "0x0",
    "excessBlobGas": "0x0",
    "parentBeaconBlockRoot": "0x22096025070f565b96c8aaf633cb809ca242170c6188818cdebca9ead88756d5",
    "requestsHash": "0xe3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "transactions": [ "0xd9531a51bda284c199328f058383e8376b65c311b0671056344ad3af4700787a" ],
    "withdrawals": []
  }
}
```

### eth\_getLogs

Returns an array of all logs matching a given filter object.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getLogs","params":[{"fromBlock":"0x1","toBlock":"0x2","address":"0x8320fe7702b96808f7bbc0d4a888ed1468216cfd"}],"id":1}' \
  http://localhost:8545
```

Sample success output (empty filter result):

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": [] }
```

## Gas Price Methods

### eth\_gasPrice

Returns the current gas price in wei for L2 execution.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_gasPrice","params":[],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0xf433b" }
```

<Info>
  This only returns the L2 gas price. For comprehensive transaction cost estimation including L1 data fees, use the [`GasPriceOracle` predeployed contract](https://explorer.optimism.io/address/0x420000000000000000000000000000000000000F) or [the Optimism SDK](/app-developers/tutorials/transactions/sdk-estimate-costs).
</Info>

### eth\_maxPriorityFeePerGas

Returns the current maximum priority fee per gas (EIP-1559).

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_maxPriorityFeePerGas","params":[],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0xf4240" }
```

### eth\_feeHistory

Returns historical base fee, gas-usage ratio, blob base fee, and priority-fee percentile data for fee estimation.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_feeHistory","params":["0x4","latest",[25,50,75]],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "oldestBlock": "0x12396",
    "baseFeePerGas": ["0xfb","0xfb","0xfb","0xfb","0xfb"],
    "gasUsedRatio": [0.0007691,0.0007691,0.0007691,0.0007691],
    "baseFeePerBlobGas": ["0x1","0x1","0x1","0x1","0x1"],
    "blobGasUsedRatio": [0.0,0.0,0.0,0.0],
    "reward": [["0x0","0x0","0x0"],["0x0","0x0","0x0"],["0x0","0x0","0x0"],["0x0","0x0","0x0"]]
  }
}
```

## Account and State Methods

### eth\_getCode

Returns code at a given address.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getCode","params":["0x420000000000000000000000000000000000000F","latest"],"id":1}' \
  http://localhost:8545
```

Sample success output (truncated):

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x60806040526004361061005e5760003560e01c80635c60da1b…"
}
```

### eth\_getStorageAt

Returns the value from a storage position at a given address.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getStorageAt","params":["0x420000000000000000000000000000000000000F","0x0","latest"],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x0000000000000000000000000000000000000000000000000000000001010101"
}
```

### eth\_getTransactionCount

Returns the number of transactions sent from an address (the nonce).

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"eth_getTransactionCount","params":["0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001","latest"],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0x12146" }
```

## Txpool Methods

When the `txpool` namespace is enabled (`--http.api eth,net,web3,debug,txpool`), `op-reth` exposes the standard txpool inspection methods.

### txpool\_status

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"txpool_status","params":[],"id":1}' \
  http://localhost:8545
```

Sample success output:

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "pending": "0x0", "queued": "0x0" }
}
```

## Debug Methods

`op-reth` supports the `debug_*` namespace for transaction inspection. Enable with `--http.api …,debug`.

<Warning>
  Debug methods can be resource-intensive. Most public RPC providers disable them. You'll need to run your own node with the `debug` namespace enabled to access them.
</Warning>

### debug\_traceTransaction

Returns the trace of a transaction, showing all internal calls and state changes. The `callTracer` is recommended for most use cases.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"debug_traceTransaction","params":["0x38a7db9aa2d7ec70d55ac7de90384279bdcad38ecdf68e3fcc4c6b649761daf9",{"tracer":"callTracer"}],"id":1}' \
  http://localhost:8545
```

Sample success output (deposit tx that proxies into the L1Block predeploy implementation):

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001",
    "gas": "0xf4240",
    "gasUsed": "0xb44e",
    "to": "0x4200000000000000000000000000000000000015",
    "input": "0x3db6be2b…",
    "calls": [
      {
        "from": "0x4200000000000000000000000000000000000015",
        "gas": "0xe9b56",
        "gasUsed": "0x489b",
        "to": "0xc0d3c0d3c0d3c0d3c0d3c0d3c0d3c0d3c0d30015",
        "input": "0x3db6be2b…",
        "value": "0x0",
        "type": "DELEGATECALL"
      }
    ],
    "value": "0x0",
    "type": "CALL"
  }
}
```

### debug\_traceCall

Traces a call without executing it on-chain.

```sh theme={null}
curl -X POST -H "Content-Type: application/json" --data \
  '{"jsonrpc":"2.0","method":"debug_traceCall","params":[{"to":"0x420000000000000000000000000000000000000F","data":"0x519b4bd3"},"latest",{"tracer":"callTracer"}],"id":1}' \
  http://localhost:8545
```

Sample success output (call to `GasPriceOracle.l1BaseFee()`):

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "from": "0x0000000000000000000000000000000000000000",
    "gas": "0x2faf080",
    "gasUsed": "0x8e85",
    "to": "0x420000000000000000000000000000000000000f",
    "input": "0x519b4bd3",
    "output": "0x0000000000000000000000000000000000000000000000000000000000000030",
    "calls": [
      {
        "from": "0x420000000000000000000000000000000000000f",
        "to": "0xc0d3c0d3c0d3c0d3c0d3c0d3c0d3c0d3c0d3000f",
        "input": "0x519b4bd3",
        "output": "0x0000000000000000000000000000000000000000000000000000000000000030",
        "type": "DELEGATECALL",
        "calls": [
          {
            "from": "0x420000000000000000000000000000000000000f",
            "to": "0x4200000000000000000000000000000000000015",
            "input": "0x5cf24969",
            "output": "0x0000000000000000000000000000000000000000000000000000000000000030",
            "type": "STATICCALL"
          }
        ]
      }
    ],
    "value": "0x0",
    "type": "CALL"
  }
}
```

## WebSocket Support

`op-reth` supports WebSocket connections for real-time event subscriptions using the `eth_subscribe` method. Default port is `8546`.

### eth\_subscribe

Creates a subscription for specific events. Verified subscription topics include `newHeads`, `logs`, `newPendingTransactions`, and `syncing`.

```js theme={null}
// Connect to WebSocket
const ws = new WebSocket('ws://localhost:8546');

// Subscribe to new block headers
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": ["newHeads"],
  "id": 1
}));

// Subscribe to logs
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x8320fe7702b96808f7bbc0d4a888ed1468216cfd",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ],
  "id": 2
}));
```

Subscription acknowledgement:

```json theme={null}
{ "jsonrpc": "2.0", "id": 1, "result": "0x8045a58dd94ddef0a9b0ac15ab397550" }
```

Event notification (newHeads):

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "eth_subscription",
  "params": {
    "subscription": "0x8045a58dd94ddef0a9b0ac15ab397550",
    "result": {
      "hash": "0xabcc886e14fdb89b4df093032bf984e98a1704d8037a21260689d19e7bf72154",
      "number": "0x124b2",
      "timestamp": "0x69fdab30",
      "baseFeePerGas": "0xfb",
      "…": "…"
    }
  }
}
```

### eth\_unsubscribe

Cancels an active subscription.

```js theme={null}
ws.send(JSON.stringify({
  "jsonrpc": "2.0",
  "method": "eth_unsubscribe",
  "params": ["0x8045a58dd94ddef0a9b0ac15ab397550"],
  "id": 1
}));
```

## Methods that behave differently from op-geth

These calls are worth flagging for tooling that auto-detects client capability:

| Method                       | op-geth                                                    | op-reth                                                                                                                                                              |
| ---------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpc_modules`                | Returns the namespace → version map.                       | **Not implemented** — returns `-32601 Method not found`. Use `web3_clientVersion` to identify the client.                                                            |
| `eth_syncing`                | Returns `false` when synced.                               | Always returns a structured object with per-stage progress; compare `currentBlock` and `highestBlock` to determine "synced".                                         |
| `trace_*` (Parity) namespace | Not exposed; `op-geth` uses `debug_*`.                     | Available in `op-reth`, but only when `trace` is added to `--http.api`. Not enabled by default in our compose file.                                                  |
| Receipt L1 fee scalars       | Single legacy `l1FeeScalar` field on pre-Ecotone receipts. | V2 (Jovian) fields: `l1BaseFeeScalar`, `l1BlobBaseFee`, `l1BlobBaseFeeScalar`, `daFootprintGasScalar`; `l1FeeScalar` removed. (Same on `op-geth` once V2 is active.) |

## Additional Resources

For a complete list of all supported JSON-RPC methods, refer to:

* [Reth JSON-RPC / Namespaces Documentation](https://reth.rs/run/run-a-node.html#rpc-namespaces)
* [Geth JSON-RPC Documentation](https://geth.ethereum.org/docs/interacting-with-geth/rpc)
* [Ethereum JSON-RPC Specification](https://ethereum.org/en/developers/docs/apis/json-rpc/)
* [OP Stack Transaction Cost Estimation](/app-developers/tutorials/transactions/sdk-estimate-costs)

## Running a Node with RPC Access

To run your own `op-reth` node with full RPC access:

```sh theme={null}
op-reth node \
  --chain /config/genesis.json \
  --datadir /data \
  --http \
  --http.addr 0.0.0.0 \
  --http.port 8545 \
  --http.api eth,net,web3,debug,txpool,trace \
  --ws \
  --ws.addr 0.0.0.0 \
  --ws.port 8546 \
  --ws.api eth,net,web3 \
  --authrpc.addr 0.0.0.0 \
  --authrpc.port 9551 \
  --authrpc.jwtsecret /config/jwt.hex \
  --rollup.sequencer-http https://<sequencer-rpc> \
  --rollup.disable-tx-pool-gossip
```

<Warning>
  Be cautious when exposing RPC endpoints publicly. Use authentication, rate limiting, and firewall rules to prevent abuse. The `debug` and `trace` namespaces should only be enabled for trusted clients.
</Warning>

### Test environment

The samples above were generated by running each curl/websocat command against an `op-reth v2.2.3` (`reth/v2.2.0-88505c7`) node in our `u19-beta-v223` devnet (chain ID `0x190a85e3` / `420120035`), HTTP port `8555`, WS port `8556`. All listed methods returned successful (or expected-error) responses.


# op-supernode configuration options
Source: https://docs.optimism.io/node-operators/reference/op-supernode-config

Complete reference for all op-supernode command-line flags and environment variables.

<Info>
  op-supernode is in active development.
  This page tracks the [op-supernode/v0.2.2-rc.8](https://github.com/ethereum-optimism/optimism/releases/tag/op-supernode%2Fv0.2.2-rc.8) release candidate and the flag list may evolve before the stable release.
</Info>

This page catalogues all configuration options for op-supernode, organized by functionality.
The following options are from the `--help` in [op-supernode/v0.2.2-rc.8](https://github.com/ethereum-optimism/optimism/releases/tag/op-supernode%2Fv0.2.2-rc.8).

For recommended settings, deployment topologies, and a starter configuration, see the [supernode configuration guide](/node-operators/guides/configuration/supernode).
For what op-supernode is and why it exists, see the [supernode explainer](/op-stack/interop/supernode).

<Info>
  Environment-variable names don't always derive mechanically from the CLI flag name.
  Some env-var suffixes keep op-node's source-level spelling even when the CLI flag was renamed (for example, `--vn.<chainID>.l2` is set by `OP_SUPERNODE_VN_<chainID>_L2_ENGINE_RPC`, not `OP_SUPERNODE_VN_<chainID>_L2`).
  The per-flag entries below show the correct env-var name alongside the CLI form.
  When in doubt, run `op-supernode --chains=<chainIDs> --help` for the authoritative name of any flag.
</Info>

## Dependency set and storage

### chains

The list of chain IDs that this supernode hosts.
Required.
Accepts a comma-separated list or a repeatable flag.
Each chain ID must have a matching set of per-chain `--vn.<chainID>.*` flags that configure the chain's network identity and execution-client connection.

<Tabs>
  <Tab title="Syntax">`--chains=<value>`</Tab>
  <Tab title="Example">`--chains=11155420,1301`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_CHAINS=`</Tab>
</Tabs>

### data-dir

Data directory for op-supernode.
Each chain's SafeDB and P2P state is stored in a `chain-<chainID>` subdirectory under this path so the chains cannot collide.
The default value is `./datadir`.

<Tabs>
  <Tab title="Syntax">`--data-dir=<value>`</Tab>
  <Tab title="Example">`--data-dir=/var/lib/op-supernode`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_DATA_DIR=`</Tab>
</Tabs>

## Shared L1 access

The supernode shares one L1 client and one beacon client across every chain in the dependency set.
These are the supernode's own in-process clients (caching layers in front of remote endpoints), not the remote L1 node and beacon node themselves — the supernode connects to existing endpoints rather than running its own.
Configure these flags at the top level only — the per-chain namespace also includes `--vn.<chainID>.l1` and `--vn.<chainID>.l1.beacon` (because the supernode mechanically clones every op-node flag into the namespace), but the supernode discards them at startup.

### l1

Address of the L1 user JSON-RPC endpoint.
Required.
The `eth` namespace must be enabled on the endpoint.

<Tabs>
  <Tab title="Syntax">`--l1=<value>`</Tab>
  <Tab title="Example">`--l1=https://ethereum-rpc-endpoint.example.com`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_L1_ETH_RPC=`</Tab>
</Tabs>

### l1.beacon

Address of the L1 beacon-node HTTP endpoint.
Required for any chain that depends on blob-derived L1 data, which covers every post-Ecotone OP Stack chain.

<Tabs>
  <Tab title="Syntax">`--l1.beacon=<value>`</Tab>
  <Tab title="Example">`--l1.beacon=https://ethereum-beacon-endpoint.example.com`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_L1_BEACON=`</Tab>
</Tabs>

### l1.beacon-fallbacks

Addresses of L1 beacon-API-compatible HTTP fallback endpoints.
Used to fetch blob sidecars not available at the primary `--l1.beacon` endpoint, including blobs that have aged past a regular beacon node's prune window.
The `--l1.beacon-archiver` alias points at the same flag.
Accepts a comma-separated list or a repeatable flag.

<Tabs>
  <Tab title="Syntax">`--l1.beacon-fallbacks=<value>`</Tab>
  <Tab title="Example">`--l1.beacon-fallbacks=https://archiver-1.example.com,https://archiver-2.example.com`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_L1_BEACON_FALLBACKS=`</Tab>
</Tabs>

### l1.http-poll-interval

Polling interval for the shared L1 HTTP RPC subscription.
The default value is `12s`.
This flag controls the supernode's own L1 client.
Per-chain `--vn.<chainID>.l1.http-poll-interval` settings are ignored because the shared client owns the resource.

<Tabs>
  <Tab title="Syntax">`--l1.http-poll-interval=<value>`</Tab>
  <Tab title="Example">`--l1.http-poll-interval=12s`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_L1_HTTP_POLL_INTERVAL=`</Tab>
</Tabs>

## Per-chain virtual-node configuration

Every chain in `--chains` runs as a virtual node inside the supernode.
The supernode reproduces the full op-node flag set under two prefixes so you can configure each chain.

* **`--vn.<chainID>.<flag>`** sets `<flag>` for one specific chain.
* **`--vn.all.<flag>`** sets `<flag>` for every chain in the dependency set.

The environment-variable form follows the same prefix rule: `OP_SUPERNODE_VN_<CHAINID>_<SUFFIX>` for one chain and `OP_SUPERNODE_VN_ALL_<SUFFIX>` for every chain.
The `<SUFFIX>` is the op-node flag's source-level environment-variable name (see the note at the top of this page for why it doesn't always match the CLI flag).

<Info>
  A few flags are owned by the supernode rather than by individual virtual nodes.
  Setting them under `--vn.<chainID>.*` or `--vn.all.*` has no effect.

  * `--l1` and `--l1.beacon`: the shared L1 plumbing replaces any per-chain L1 setting at startup.
  * `--l1.http-poll-interval`: the shared L1 client owns the polling cadence; the supernode logs a warning if a per-chain value is set.
  * `--log.*`: the supernode and every virtual node share one logger; top-level `--log.*` configures it. Per-chain `--vn.*.log.*` flags appear in the namespace but are silently ignored. (`--metrics.*` is different: top-level configures the supernode's own metrics service, but per-chain `--vn.*.metrics.*` configures each virtual node's own metrics, which are fanned into the same endpoint with per-chain Prometheus labels.)
  * P2P listen ports: see the [P2P](#p2p) section.
</Info>

The flags most operators need to set per chain are listed below.
For the full set of op-node flags available under the `--vn.*` namespace, see the [op-node configuration reference](/node-operators/reference/op-node-config) and the [consensus client configuration page](/node-operators/guides/configuration/consensus-clients).

### vn.\<chainID>.network

Names the chain's known network configuration so the supernode can load the matching rollup config from op-node's built-in registry.
Use this for any chain registered with op-node (`op-mainnet`, `op-sepolia`, `unichain-sepolia`, etc.).

<Tabs>
  <Tab title="Syntax">`--vn.<chainID>.network=<value>`</Tab>
  <Tab title="Example">`--vn.11155420.network=op-sepolia`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_VN_<CHAINID>_NETWORK=`</Tab>
</Tabs>

### vn.\<chainID>.rollup.config

Path to a rollup configuration JSON file for chains that are not in op-node's built-in network registry.
Use this instead of `--vn.<chainID>.network` for custom devnets or any chain you have a rollup config file for.

<Tabs>
  <Tab title="Syntax">`--vn.<chainID>.rollup.config=<value>`</Tab>
  <Tab title="Example">`--vn.420120037.rollup.config=/etc/op/rollup-config.json`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_VN_<CHAINID>_ROLLUP_CONFIG=`</Tab>
</Tabs>

### vn.\<chainID>.l2

Address of the engine-API endpoint for the chain's execution client.
Each chain needs its own execution client; one execution client cannot back two chains.

<Tabs>
  <Tab title="Syntax">`--vn.<chainID>.l2=<value>`</Tab>
  <Tab title="Example">`--vn.11155420.l2=http://op-sepolia-geth:8551`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_VN_<CHAINID>_L2_ENGINE_RPC=`</Tab>
</Tabs>

### vn.all.l2.jwt-secret

Path to the JWT secret used to authenticate every virtual node's engine connection to its execution client.
Set this at the `vn.all.*` level when every execution client in the dependency set shares one secret.
Use the per-chain `--vn.<chainID>.l2.jwt-secret` form only when a chain's execution client requires its own secret.

<Tabs>
  <Tab title="Syntax">`--vn.all.l2.jwt-secret=<value>`</Tab>
  <Tab title="Example">`--vn.all.l2.jwt-secret=/etc/op/jwt-secret.txt`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_VN_ALL_L2_ENGINE_AUTH=`</Tab>
</Tabs>

### vn.\<chainID>.l2.enginekind

Selects the engine-client variant so the supernode can apply engine-API behavior tailored to each.
Set to `reth` when the chain's execution client is op-reth; leave at the default for op-geth.
Supported values are `geth` and `reth`.
The default value is `geth`.

<Tabs>
  <Tab title="Syntax">`--vn.<chainID>.l2.enginekind=<value>`</Tab>
  <Tab title="Example">`--vn.11155420.l2.enginekind=reth`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_VN_<CHAINID>_L2_ENGINE_KIND=`</Tab>
</Tabs>

## P2P

P2P is enabled at the supernode level for every chain, or disabled for every chain.
Per-chain enable/disable is not supported.

### disable-p2p

Disables P2P for every chain.
The default value is `false`.
Use this in topologies where unsafe-head P2P gossip is handled by other nodes in the fleet (for example, a Light CL fleet) and the supernode only needs to derive from L1.

<Tabs>
  <Tab title="Syntax">`--disable-p2p=<value>`</Tab>
  <Tab title="Example">`--disable-p2p=true`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_DISABLE_P2P=`</Tab>
</Tabs>

### Per-chain listen ports

When P2P is enabled, each virtual node's P2P listen port defaults to `0` (dynamic) to prevent port collisions across chains.
Setting `--vn.all.p2p.listen.tcp` or `--vn.all.p2p.listen.udp` to a non-zero value is rejected because the same port cannot be reused across virtual nodes.

To pin static ports per chain, set both the TCP (RLPx) and UDP (discovery v5) ports with the per-chain form:

```bash theme={null}
--vn.11155420.p2p.listen.tcp=9222 \
--vn.11155420.p2p.listen.udp=9222 \
--vn.1301.p2p.listen.tcp=9223 \
--vn.1301.p2p.listen.udp=9223
```

## Interop verification

The interop activity is the part of op-supernode that decides when a chain's blocks have satisfied their cross-chain dependencies.
For background on how the activity decides between *wait*, *advance*, *invalidate*, and *rewind*, see the [supernode explainer](/op-stack/interop/supernode#cross-chain-message-safety).

### interop.activation-timestamp

Overrides the interop activation timestamp derived from the loaded rollup configs.
The default value is `0` (use the value from the rollup config).
Set this only when activating interop on a custom devnet whose rollup config does not yet carry the activation timestamp.

<Tabs>
  <Tab title="Syntax">`--interop.activation-timestamp=<value>`</Tab>
  <Tab title="Example">`--interop.activation-timestamp=1735689600`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_INTEROP_ACTIVATION_TIMESTAMP=`</Tab>
</Tabs>

### interop.log-backfill-depth

Extends initiating-message log ingestion backward from the L2 tip by this duration, clamped to the interop activation timestamp.
Validation still starts only beyond the local safe head; the backfill pre-ingests logs so they are available when validation needs them.
Requires the interop activation timestamp to be known, either from the rollup config or via `--interop.activation-timestamp`.
The default value is `0s` (no backfill).

<Tabs>
  <Tab title="Syntax">`--interop.log-backfill-depth=<value>`</Tab>
  <Tab title="Example">`--interop.log-backfill-depth=168h`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_INTEROP_LOG_BACKFILL_DEPTH=`</Tab>
</Tabs>

## JSON-RPC server

The supernode exposes a single JSON-RPC server that multiplexes activity methods and every chain's op-node RPC under one HTTP endpoint.
Per-chain RPC namespaces are mounted under a `/<chainID>/` path prefix on the same server.
For example, `POST /11155420/` reaches the OP Sepolia op-node RPC surface.
Activity RPC methods (`superroot_atTimestamp`, `supernode_syncStatus`, `heartbeat_check`) are exposed at the root.
For example, `POST /` with method `superroot_atTimestamp` reaches the SuperRoot activity.

### rpc.addr

Address the JSON-RPC server binds to.
The default value is `0.0.0.0`.

<Tabs>
  <Tab title="Syntax">`--rpc.addr=<value>`</Tab>
  <Tab title="Example">`--rpc.addr=0.0.0.0`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_RPC_ADDR=`</Tab>
</Tabs>

### rpc.port

Port the JSON-RPC server listens on.
The default value is `8545`.

<Tabs>
  <Tab title="Syntax">`--rpc.port=<value>`</Tab>
  <Tab title="Example">`--rpc.port=8545`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_RPC_PORT=`</Tab>
</Tabs>

### rpc.enable-admin

Enables admin-namespace RPC methods.
The default value is `false`.
Enable this only on endpoints that are not exposed to untrusted networks.

<Tabs>
  <Tab title="Syntax">`--rpc.enable-admin=<value>`</Tab>
  <Tab title="Example">`--rpc.enable-admin=true`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_RPC_ENABLE_ADMIN=`</Tab>
</Tabs>

## Logging

Logging is configured at the top level.
The supernode and every virtual node share one logger; per-chain `--vn.*.log.*` flags appear in the namespace but are silently ignored.

### log.level

Minimum log severity to emit.
Valid values are `trace`, `debug`, `info`, `warn`, `error`, `crit`.
The default value is `info`.

<Tabs>
  <Tab title="Syntax">`--log.level=<value>`</Tab>
  <Tab title="Example">`--log.level=info`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_LOG_LEVEL=`</Tab>
</Tabs>

### log.format

Log output format.
Valid values are `text`, `terminal`, `logfmt`, `logfmtms`, `json`, `jsonms` (the `*ms` variants append millisecond timestamps).
The default value is `text`.
Set `logfmt` or `json` when ingesting logs into a structured-log pipeline; the default `text` is for hand-reading.

<Tabs>
  <Tab title="Syntax">`--log.format=<value>`</Tab>
  <Tab title="Example">`--log.format=json`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_LOG_FORMAT=`</Tab>
</Tabs>

### log.color

Forces ANSI color codes in `text` log output regardless of whether the stream is a terminal.
The default value is `false`.

<Tabs>
  <Tab title="Syntax">`--log.color=<value>`</Tab>
  <Tab title="Example">`--log.color=true`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_LOG_COLOR=`</Tab>
</Tabs>

## Metrics and profiling

Metrics and profiling endpoints are configured at the top level.
The metrics server fans in counters from every chain container and exposes them on one endpoint with per-chain Prometheus labels.

### metrics.enabled

Enables the Prometheus metrics server.
The default value is `false`.

<Tabs>
  <Tab title="Syntax">`--metrics.enabled=<value>`</Tab>
  <Tab title="Example">`--metrics.enabled=true`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_METRICS_ENABLED=`</Tab>
</Tabs>

### metrics.addr

Address the metrics server binds to.
The default value is `0.0.0.0`.

<Tabs>
  <Tab title="Syntax">`--metrics.addr=<value>`</Tab>
  <Tab title="Example">`--metrics.addr=0.0.0.0`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_METRICS_ADDR=`</Tab>
</Tabs>

### metrics.port

Port the metrics server listens on.
The default value is `7300`.

<Tabs>
  <Tab title="Syntax">`--metrics.port=<value>`</Tab>
  <Tab title="Example">`--metrics.port=7300`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_METRICS_PORT=`</Tab>
</Tabs>

### pprof.enabled

Enables the pprof profiling endpoint.
The default value is `false`.

<Tabs>
  <Tab title="Syntax">`--pprof.enabled=<value>`</Tab>
  <Tab title="Example">`--pprof.enabled=true`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_PPROF_ENABLED=`</Tab>
</Tabs>

### pprof.addr

Address the pprof server binds to.
The default value is `0.0.0.0`.

<Tabs>
  <Tab title="Syntax">`--pprof.addr=<value>`</Tab>
  <Tab title="Example">`--pprof.addr=0.0.0.0`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_PPROF_ADDR=`</Tab>
</Tabs>

### pprof.port

Port the pprof server listens on.
The default value is `6060`.

<Tabs>
  <Tab title="Syntax">`--pprof.port=<value>`</Tab>
  <Tab title="Example">`--pprof.port=6060`</Tab>
  <Tab title="Environment Variable">`OP_SUPERNODE_PPROF_PORT=`</Tab>
</Tabs>

## Where to go next

* Follow the [supernode configuration guide](/node-operators/guides/configuration/supernode) for recommended settings and a starter configuration.
* Read the [supernode explainer](/op-stack/interop/supernode) for what op-supernode is and why it exists.
* Read the [op-node configuration reference](/node-operators/reference/op-node-config) for the full set of flags available under the `--vn.*` namespace.
* See the [op-supernode source](https://github.com/ethereum-optimism/optimism/tree/develop/op-supernode) in the monorepo for implementation detail.


# Running a Node With Docker
Source: https://docs.optimism.io/node-operators/tutorials/node-from-docker

Run an OP Stack node (op-reth + op-node) using the official Docker images and docker-compose.

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

<Info>
  **Learn the OP Stack — stop 13 of 13.**
  You've learned the stack from concepts to cross-layer flows. In this
  capstone you run an OP Stack node on a live network with the official
  Docker images. When it syncs, you've finished the track: head back to
  [Learn the OP Stack](/op-stack/learn/index) for where to go next.
</Info>

This tutorial runs an OP Stack node using the **official op-reth and op-node Docker images** in a single `docker-compose.yml`. No source build required.

<Info>
  To run the Rust consensus client instead of op-node, see the
  [kona-node Docker guide](/node-operators/kona-node/run/docker), which ships
  its own docker-compose recipe for a kona-node + op-reth stack.
</Info>

<Warning>
  **OP Mainnet requires a one-time pre-Bedrock state import.** OP Sepolia does not. If you point this tutorial at OP Mainnet on a fresh datadir, op-reth will fail at startup with `Op-mainnet has been launched without importing the pre-Bedrock state`. Before running OP Mainnet, follow the [op-reth sync-op-mainnet guide](https://reth.rs/run/sync-op-mainnet.html) to either restore from a [pre-synced snapshot](https://datadirs.optimism.io/) or run the minimal-bootstrap import. OP Sepolia bootstraps via snap sync with no extra steps — start there if you're just testing the setup.
</Warning>

## Dependencies

* [Docker](https://docs.docker.com/engine/install/)
* [Docker Compose](https://docs.docker.com/compose/install/) (v2)
* **An L1 execution RPC endpoint** (Ethereum mainnet for OP Mainnet, or Ethereum Sepolia for OP Sepolia).
* **An L1 Beacon API endpoint** for the same L1 chain. Needed by op-node to fetch blob data post-Ecotone.

## Quick start

<Steps>
  <Step title="Create a working directory">
    ```bash theme={null}
    mkdir op-stack-node && cd op-stack-node
    ```
  </Step>

  <Step title="Generate the JWT secret">
    Both containers share a JWT secret over a bind mount:

    ```bash theme={null}
    openssl rand -hex 32 > jwt.txt
    ```
  </Step>

  <Step title="Create the .env file">
    Configure your network and L1 endpoints. Pick **one** network block (Sepolia or Mainnet) and fill in your L1 RPC + Beacon URLs:

    ```bash theme={null}
    cat > .env <<'EOF'
    # --- Network: OP Sepolia (default) ---
    OP_RETH_CHAIN=optimism_sepolia
    OP_NODE_NETWORK=op-sepolia
    OP_RETH_SEQUENCER=https://sepolia-sequencer.optimism.io

    # --- Network: OP Mainnet (uncomment to use instead) ---
    # OP_RETH_CHAIN=optimism
    # OP_NODE_NETWORK=op-mainnet
    # OP_RETH_SEQUENCER=https://mainnet-sequencer.optimism.io

    # --- L1 endpoints (required) ---
    L1_RPC_URL=https://your-l1-rpc-endpoint
    L1_RPC_KIND=basic
    L1_BEACON_URL=https://your-l1-beacon-endpoint
    EOF
    ```

    `L1_RPC_KIND` valid values: `alchemy`, `quicknode`, `infura`, `parity`, `nethermind`, `debug_geth`, `erigon`, `basic`, `any`. Use `basic` if unsure.

    <Info>
      `OP_RETH_CHAIN` and `OP_NODE_NETWORK` accept any [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) chain (e.g. `unichain` / `unichain-mainnet`, `soneium` / `soneium-mainnet`). For each chain, point `L1_RPC_URL` / `L1_BEACON_URL` at the corresponding L1 (Ethereum Mainnet or Sepolia) and update `OP_RETH_SEQUENCER` to that chain's sequencer endpoint.
    </Info>
  </Step>

  <Step title="Create docker-compose.yml">
    ```yaml theme={null}
    services:
      op-reth:
        image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-reth:v2.2.5
        container_name: op-reth
        ports:
          - "8545:8545"          # JSON-RPC HTTP
          - "8546:8546"          # JSON-RPC WebSocket
          - "9001:9001"          # Prometheus metrics
          - "30303:30303"        # P2P TCP
          - "30303:30303/udp"    # P2P UDP
        volumes:
          - ./reth-data:/data
          - ./jwt.txt:/jwt.txt:ro
        command:
          - node
          - --chain=${OP_RETH_CHAIN}
          - --datadir=/data
          - --http
          - --http.addr=0.0.0.0
          - --http.port=8545
          - --ws
          - --ws.addr=0.0.0.0
          - --ws.port=8546
          - --authrpc.addr=0.0.0.0
          - --authrpc.port=8551
          - --authrpc.jwtsecret=/jwt.txt
          - --rollup.sequencer=${OP_RETH_SEQUENCER}
          - --metrics=0.0.0.0:9001
        restart: unless-stopped

      op-node:
        image: us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.18.2
        container_name: op-node
        depends_on:
          - op-reth
        ports:
          - "9545:7000"          # JSON-RPC HTTP (host 9545 → container 7000; macOS uses 7000 for AirPlay)
          - "7300:7300"          # Prometheus metrics
          - "9222:9222"          # P2P TCP
          - "9222:9222/udp"      # P2P UDP
        volumes:
          - ./jwt.txt:/jwt.txt:ro
        command:
          - op-node
          - --l1=${L1_RPC_URL}
          - --l1.rpckind=${L1_RPC_KIND}
          - --l1.beacon=${L1_BEACON_URL}
          - --l2=ws://op-reth:8551
          - --l2.jwt-secret=/jwt.txt
          - --network=${OP_NODE_NETWORK}
          - --syncmode=execution-layer
          - --l2.enginekind=reth
          - --rpc.addr=0.0.0.0
          - --rpc.port=7000
          - --metrics.enabled
          - --metrics.addr=0.0.0.0
          - --metrics.port=7300
        restart: unless-stopped
    ```

    The op-reth datadir is bind-mounted from `./reth-data` on the host so you can inspect / restore from a snapshot directly (see [Bootstrap from a snapshot](#bootstrap-from-a-snapshot) below).

    Image tags shown are the latest as of writing. For the current tags, see the [op-reth releases](https://github.com/ethereum-optimism/optimism/releases?q=op-reth) and [op-node releases](https://github.com/ethereum-optimism/optimism/releases?q=op-node).
  </Step>

  <Step title="Start the node">
    ```bash theme={null}
    docker compose up -d
    ```

    Follow logs with:

    ```bash theme={null}
    docker compose logs -f
    ```
  </Step>
</Steps>

## Verification

Check the node is alive and advancing:

```bash theme={null}
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
  http://localhost:8545
```

Expected: `{"jsonrpc":"2.0","id":1,"result":"0x..."}` with the current block in hex. Run again after a minute — the number should increase as sync progresses.

For op-node sync status (unsafe, safe, and finalized heads in one call):

```bash theme={null}
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"optimism_syncStatus","params":[],"id":1}' \
  http://localhost:9545 | jq .
```

<Info>
  During the initial EL-driven sync (`--syncmode=execution-layer`), `unsafe_l2` tracks the tip via libp2p gossip while `safe_l2` and `finalized_l2` stay at 0. This is expected — op-node defers L1 derivation until op-reth finishes its staged sync. Once the EL catches up, derivation begins and the safe/finalized heads start advancing.
</Info>

You can also tail op-node logs directly:

```bash theme={null}
docker compose logs op-node | grep -E "Sync progress|Finished EL sync"
```

## Bootstrap from a snapshot

Syncing from scratch is fine for OP Sepolia (\~30–50 GB, hours) but slow for OP Mainnet (\~700 GB, days). For Mainnet — or anytime you'd rather skip the initial sync — bootstrap op-reth from a pre-synced snapshot.

<Info>
  For OP Mainnet, a snapshot also handles the pre-Bedrock state requirement (see the warning at the top of this page) in one step.
</Info>

<Steps>
  <Step title="Stop the containers">
    ```bash theme={null}
    docker compose down
    rm -rf reth-data       # only if you previously synced and want to start clean
    ```
  </Step>

  <Step title="Download a snapshot">
    Browse [datadirs.optimism.io](https://datadirs.optimism.io/) for the snapshot matching your network and pick a recent file. Then download and verify the SHA256:

    ```bash theme={null}
    curl -fLO https://datadirs.optimism.io/<snapshot-file>.tar.zst

    # Verify checksum against the value on the index page
    sha256sum <snapshot-file>.tar.zst   # Linux
    shasum -a 256 <snapshot-file>.tar.zst   # macOS
    ```
  </Step>

  <Step title="Extract into the datadir">
    The bind-mounted directory is `./reth-data` (relative to your `docker-compose.yml`):

    ```bash theme={null}
    mkdir -p reth-data
    tar -I zstd -xvf <snapshot-file>.tar.zst -C reth-data --strip-components=1
    ```

    `--strip-components=1` removes the top-level wrapping directory inside the tarball. Run `tar -tf <snapshot-file>.tar.zst | head -3` first to confirm — if files are already at the archive root, omit `--strip-components`.
  </Step>

  <Step title="Start the node">
    ```bash theme={null}
    docker compose up -d
    docker compose logs -f op-reth
    ```

    op-reth will recognize the existing datadir on startup and pick up from the snapshot's tip — `latest_block` should be the snapshot's height, not 0. It will then catch up from that tip to current (minutes for Sepolia, hours for Mainnet, depending on snapshot age).
  </Step>
</Steps>

## Next steps

* [Node Metrics and Monitoring Guide](/node-operators/guides/monitoring/metrics) — wire up Prometheus/Grafana against the metrics port.
* [Node Troubleshooting Guide](/node-operators/guides/troubleshooting) — if you run into problems.
* [Building and running an OP Stack node from source](/node-operators/tutorials/run-node-from-source) — if you need a custom build or want to inspect the source.


# Running op-reth with Historical Proofs
Source: https://docs.optimism.io/node-operators/tutorials/reth-historical-proofs

Configure op-reth's proofs-history (v2) store to serve efficient historical eth_getProof responses for permissionless withdrawal proving.

This tutorial layers the **proofs-history** historical proof store (storage format **v2**) on top of a working op-reth node. Follow [Building and running an OP Stack node from source](/node-operators/tutorials/run-node-from-source) first to build op-reth and op-node, then return here to enable proofs-history.

<Info>
  **Do you need this tutorial?** Withdrawal proving on op-reth uses `eth_getProof` against historical L2 state, so both permissioned and permissionless chains need historical state exposed — but the required lookback differs sharply:

  * **Permissioned chains** only need a few hours of lookback (covering your dispute-game publishing cadence with margin). The lighter `--rpc.eth-proof-window <num_blocks>` flag is sufficient on its own — no separate proofs database is needed, and **this tutorial does not apply**. See the [op-reth configuration reference](/node-operators/op-reth/cli/op-reth/node) for that flag.
  * **Permissionless chains** need \~28 days of lookback. `--rpc.eth-proof-window` becomes too slow and memory-hungry at that range, so follow this tutorial to set up `--proofs-history` (v2).
</Info>

<Info>
  Use historical proofs storage format v2 by setting `--proofs-history.storage-version=v2` when running `op-reth node`.
</Info>

## How it works

reth's default `eth_getProof` reverts in-memory state diffs backward from the tip, which becomes prohibitive at multi-day lookbacks. The **proofs-history** subsystem maintains a separate MDBX database that tracks intermediate Merkle Patricia Trie nodes versioned by block, enabling O(1) lookups of proofs at any block within a configurable retention window. A background pruner removes data outside the window.

The subsystem processes blocks asynchronously via reth's ExEx (Execution Extension) hook, so it adds zero overhead to sync speed and negligible tip latency. See the [historical proof configuration reference](/node-operators/reference/op-reth-historical-proof-config) for storage tables, RPC overrides, and tunable parameters.

## Prerequisites

* A built `op-reth` binary at v2.2.3 or later (required for `--proofs-history.storage-version=v2`). See [Build op-node and the execution client](/node-operators/tutorials/run-node-from-source#build-op-node-and-the-execution-client).
* An op-reth datadir, either initialized from genesis or restored from a [snapshot](https://datadirs.optimism.io/) (covered below).
* Sufficient disk: estimate `chain_size + 20% buffer` for the proofs database (e.g., \~1 TB for 4 weeks on Base at 2s block time).
* NVMe SSD recommended.

## Initialization

Running `op-reth` with historical proofs requires a two-step initialization:

### 1. Initialize op-reth

Initialize the core database with the genesis file for your chain (e.g., `optimism`).

```bash theme={null}
./target/release/op-reth init \
  --datadir="/path/to/datadir" \
  --chain="optimism"
```

#### Option: Start from a Snapshot

If you prefer to start from a pre-synchronized database snapshot instead of syncing from genesis:

1. Download and extract an `op-reth` snapshot from [datadirs.optimism.io](https://datadirs.optimism.io/) into your `datadir`.
2. Skip the `op-reth init` command above.
3. Proceed to **Initialize Proofs Storage** below. The `proofs init` command initializes the proofs database at the snapshot's chain tip — it does not retroactively populate proofs for blocks already in the snapshot.

### 2. Initialize Proofs Storage

Initialize the separate storage used by the historical proof store. This is **required** before starting the node with `--proofs-history`, even when reusing an existing op-reth datadir or restoring from a snapshot.

```bash theme={null}
./target/release/op-reth proofs init \
  --datadir="/path/to/datadir" \
  --chain="optimism" \
  --proofs-history.storage-path="/path/to/proofs-db" \
  --proofs-history.storage-version=v2
```

<Info>
  The first time `proofs init` runs, it takes minutes to hours. Subsequent invocations should only take seconds. It does **not** backfill historical proofs — it marks the current chain tip as the starting point of the proofs database. Once the node is running with `--proofs-history`, the proofs database fills forward as new blocks are committed. To serve proofs across the full retention window (e.g., 30 days for permissionless fault proofs at default settings), the node must run continuously for at least that long after initialization. For that reason it is recommended to start from a snapshot whose tip is old enough to cover the required time window.
</Info>

## Running op-reth with proofs-history

Add the `--proofs-history.*` flags below to your standard op-reth start command from [Start the execution client](/node-operators/tutorials/run-node-from-source#start-the-execution-client). The proofs-history additions are:

```bash theme={null}
./target/release/op-reth node \
  # ... your standard flags from Tutorial A ...
  --proofs-history \
  --proofs-history.storage-path="/path/to/proofs-db" \
  --proofs-history.storage-version=v2
```

<Info>
  The default `--proofs-history.window` is **1,296,000 blocks**, corresponding to \~30 days at 2s block times. For chains with a different block time, set `--proofs-history.window=<num_blocks>` explicitly using `target_retention_seconds / block_time_seconds`.
</Info>

For the full set of `--proofs-history.*` flags (window, prune-interval, metrics, etc.), see the [historical proof configuration reference](/node-operators/reference/op-reth-historical-proof-config).

## Running op-node

Start `op-node` as documented in [Start op-node](/node-operators/tutorials/run-node-from-source#start-op-node). No proofs-history-specific changes are needed on the consensus client.

## Verification

After starting both clients, query the sync status of the proofs store via the `debug_proofsSyncStatus` RPC method:

```bash theme={null}
curl -s -X POST -H "Content-Type: application/json" \
  --data '{"jsonrpc":"2.0","method":"debug_proofsSyncStatus","params":[],"id":1}' \
  http://localhost:8545
```

The response has the shape:

```json theme={null}
{"jsonrpc":"2.0","id":1,"result":{"earliest":<block>,"latest":<block>}}
```

Immediately after `proofs init`, both `earliest` and `latest` sit at the chain tip; the window then fills forward as new blocks are committed. `eth_getProof` calls for every block within `[earliest, latest]` will be served from the versioned store. Requests for blocks older than `earliest` will fail or fall back to the default reth implementation.

You can also check the op-reth startup logs for messages confirming the proofs-history ExEx is wired up:

```text theme={null}
INFO reth::cli: Using on-disk storage for proofs history
INFO reth::cli: Installing proofs-history RPC overrides (eth_getProof, debug_executePayload)
INFO reth::cli eth_replaced=true debug_replaced=true: Proofs-history RPC overrides installed
```

## Monitoring

When op-reth is run with the `--metrics=<addr>:<port>` flag, the proofs-history ExEx exposes Prometheus metrics covering proofs-DB sync state (`optimism_trie_block_*`), the background pruner (`optimism_trie_pruner_*`), and `eth_getProof` RPC traffic (`optimism_rpc_eth_api_ext_*`). See the [historical proof configuration reference](/node-operators/reference/op-reth-historical-proof-config#metrics) for the full list.

## Operational Commands

### Manual prune

Pruning runs automatically in the background, driven by the engine task as new blocks are committed, and removes data outside the retention window. You should not need to invoke `op-reth proofs prune` under normal operation.

A manual prune is only required in one situation: at startup, if the proofs database contains more than **1000 blocks** of history beyond the configured `--proofs-history.window`, the node refuses to start rather than stalling on a large prune operation. This typically happens after the node has been offline long enough that the configured window has shifted significantly, or after reducing `--proofs-history.window` to a smaller value than was previously in use.

When this happens, op-reth exits with an error indicating the number of blocks to prune. Run the prune command once to bring the database back within the safety threshold, then restart the node:

```bash theme={null}
op-reth proofs prune \
  --datadir /path/to/reth-datadir \
  --proofs-history.storage-path /path/to/proofs-db \
  --proofs-history.storage-version v2 \
  --proofs-history.window 1296000
```

### Unwind

Recover from corruption by reverting the proofs database to a specific block:

```bash theme={null}
op-reth proofs unwind \
  --datadir /path/to/reth-datadir \
  --proofs-history.storage-path /path/to/proofs-db \
  --proofs-history.storage-version v2 \
  --target <BLOCK_NUMBER>
```

<Note>
  You can only unwind to a block after the earliest block number in the database. Unwinding to a block before the earliest will fail.
</Note>

## Performance

Benchmarked on Base Sepolia (\~700k block window, WETH contract):

| Metric        | Value                                 |
| ------------- | ------------------------------------- |
| Avg latency   | \~15 ms per `eth_getProof`            |
| Throughput    | \~5,000 req/s (10 concurrent workers) |
| Sync overhead | Zero (ExEx processes asynchronously)  |
| Memory        | Bounded by window size — no OOM risk  |

## Next steps

* [op-reth v2.2.3 release notes](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth%2Fv2.2.3) — the release that introduced the historical proof store v2.
* [op-reth historical proof configuration reference](/node-operators/reference/op-reth-historical-proof-config) — full `--proofs-history.*` flag set, RPC endpoints, and Prometheus metrics.
* [op-reth configuration reference](/node-operators/reference/op-reth-config) — all standard op-reth flags.


# Building and running an OP Stack node from source
Source: https://docs.optimism.io/node-operators/tutorials/run-node-from-source

Build and run an OP Stack node (op-reth + op-node) from source code for full nodes and archive nodes.

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

This tutorial walks through the full process of building and running an OP Stack node from source — op-node plus an execution client. Building from source is a flexible alternative to using pre-built Docker images and is useful if you need a specific architecture or want to inspect what you're running.
It builds and runs op-reth and Nethermind; op-geth instructions are retained in a legacy section at the bottom for operators mid-migration.

For permissionless chains setting up historical proofs for withdrawal proving, follow this tutorial first to get a working node, then continue with [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs).

## Hardware requirements

Hardware requirements for OP Mainnet nodes can vary depending on the type of node you plan to run.
Archive nodes generally require significantly more resources than full nodes.
Below are suggested minimum hardware requirements for each type of node.

* 16GB RAM
* Reasonably modern CPU

### SSD capacity requirements

Given the growing size of the blockchain state, choosing the right SSD size is important.
Below are the storage needs as of June 2025:

* **Full Node:** The snapshot size for a full node is approximately 700GB, with the data directory's capacity increasing by about 100GB every six months.
* **Archive Node:** The snapshot size for an archive node is approximately 14TB, with the data directory's capacity increasing by about 3.5TB every six months. A local SSD with a NVME interface is recommended for archive nodes.

Plan for future storage needs and choose SSDs that can handle these increasing requirements.

## Software dependencies

The build environment is managed through [mise](https://mise.jdx.dev/), which installs and manages the toolchains (Rust, Go) needed to build the monorepo. The mise configuration lives in [`mise.toml`](https://github.com/ethereum-optimism/optimism/blob/develop/mise.toml) at the monorepo root.

## Build op-node and the execution client

The Optimism Monorepo does **coordinated releases** — each release commit is tagged simultaneously across components (op-node, op-reth, kona-node, etc.). Pinning to one release tag gives you a known-good combination of all of them built from the same source state. Look up the latest tags on the [Optimism releases page](https://github.com/ethereum-optimism/optimism/releases).

<Steps>
  <Step title="Clone the Optimism Monorepo">
    The monorepo contains the source for both `op-node` and `op-reth`.

    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism.git
    cd optimism
    ```
  </Step>

  <Step title="Pin to a release commit">
    Check out a recent op-node release tag — the same commit carries the matching op-reth tag. For example, `op-node/v1.18.2` is co-tagged with `op-reth/v2.2.4`:

    ```bash theme={null}
    git checkout op-node/v1.18.2
    ```

    <Info>
      `op-reth/v2.2.3` or later is required to enable the historical proof store v2 (`--proofs-history.storage-version=v2`). The op-node/v1.18.x release line carries op-reth ≥ v2.2.3, so any of those tags satisfies that requirement.
    </Info>
  </Step>

  <Step title="Build op-node">
    ```bash theme={null}
    cd op-node && just && cd ..
    ```

    Binary: `op-node/bin/op-node` (relative to the monorepo root).
  </Step>

  <Step title="Build the execution client">
    <Tabs>
      <Tab title="op-reth">
        op-reth lives inside the monorepo at `rust/op-reth/` — no second `git clone` needed.

        ```bash theme={null}
        cd rust/op-reth && cargo build --release --bin op-reth && cd ../..
        ```

        Binary: `rust/target/release/op-reth` (relative to the monorepo root). `rust/` is a Cargo workspace, so the `target/` directory lives at the workspace root, not inside the individual crate. Build outputs are gitignored, so they persist across any future `git checkout`.
      </Tab>

      <Tab title="Nethermind">
        `Nethermind` is an alternative execution client written in .NET. **Prerequisites:** [.NET SDK](https://aka.ms/dotnet/download) 9 or later.

        ```bash theme={null}
        git clone --recursive https://github.com/nethermindeth/nethermind.git
        dotnet build nethermind/src/Nethermind/Nethermind.sln -c release
        ```

        Build artifacts: `nethermind/src/Nethermind/artifacts/bin/Nethermind.Runner/release/`. See the [Nethermind documentation](https://docs.nethermind.io/get-started/running-node/) for more.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Assess blob archiver

Assess if you need to configure a blob archiver service by reading [Configure a Blob Archiver](/node-operators/guides/management/blobs#configure-a-blob-archiver).

## Create a JWT secret

The execution client and `op-node` communicate over the engine API authrpc, secured with a shared 32-byte hex secret. Both binaries must read the **same** secret file. The commands below use a relative path (`./jwt.txt`) for each binary, so the same content must exist at both launch directories.

<Steps>
  <Step title="Generate the secret">
    From the monorepo root:

    ```bash theme={null}
    openssl rand -hex 32 > jwt.txt
    ```

    This creates `optimism/jwt.txt`.
  </Step>

  <Step title="Copy to the op-node launch directory">
    ```bash theme={null}
    cp jwt.txt op-node/jwt.txt
    ```
  </Step>

  <Step title="Copy to the op-reth launch directory">
    The op-reth binary lives at `rust/target/release/op-reth` and the tutorial launches it from `rust/`, so place the JWT there:

    ```bash theme={null}
    cp jwt.txt rust/jwt.txt
    ```
  </Step>
</Steps>

The two copies must remain identical — if you regenerate one side, copy it over to the other before restarting.

## Start the execution client

It's generally easier to start the execution client before `op-node`. The EL will simply not receive any blocks until `op-node` is started.

<Tabs>
  <Tab title="op-reth">
    <Steps>
      <Step title="Navigate to the rust workspace directory">
        op-reth is built into the workspace target dir, so launch from `optimism/rust/`:

        ```bash theme={null}
        cd /path/to/optimism/rust
        ```

        The binary is then at `./target/release/op-reth`.
      </Step>

      <Step title="Set environment variables">
        ```bash theme={null}
        export DATADIR_PATH=... # Path to the desired data directory for op-reth
        ```
      </Step>

      <Step title="Start op-reth">
        <Info>
          For archive-node configuration (historical state for withdrawal proving), see the [OP Mainnet archive nodes](#op-mainnet-archive-nodes) section.
        </Info>

        The JSON-RPC API will become available on port 8545. See the [op-reth configuration reference](/node-operators/reference/op-reth-config) for the full flag set.

        ```bash theme={null}
        ./target/release/op-reth node \
          --chain=optimism_sepolia \
          --datadir=$DATADIR_PATH \
          --http \
          --ws \
          --authrpc.jwtsecret=./jwt.txt \
          --rollup.sequencer=https://sepolia-sequencer.optimism.io
        ```

        For OP Mainnet, set `--chain=optimism` and `--rollup.sequencer=https://mainnet-sequencer.optimism.io`.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Nethermind">
    <Steps>
      <Step title="Navigate to your Nethermind directory">
        Find the directory where you built the `Nethermind` binary.
      </Step>

      <Step title="Start Nethermind">
        <Info>
          For an archive node, use the `op-sepolia_archive` configuration instead of `op-sepolia`. For OP Mainnet, use `op-mainnet` or `op-mainnet_archive` respectively.
        </Info>

        The JSON-RPC API will become available on port 8545. See the [execution clients configuration guide](/node-operators/guides/configuration/execution-clients) for more options.

        ```bash theme={null}
        ./Nethermind.Runner \
          -c op-sepolia \
          --data-dir path/to/data/dir \
          --JsonRpc.JwtSecretFile=./jwt.txt
        ```

        This uses the built-in `op-sepolia` configuration which includes JSON-RPC endpoints, network ports, sequencer URL, and other OP Stack-specific settings.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Start op-node

Once your execution client is running, start `op-node`. It will connect to the EL and begin synchronizing the chain.

<Steps>
  <Step title="Navigate to the op-node directory">
    op-node is built into its own crate directory, so launch from `optimism/op-node/`:

    ```bash theme={null}
    cd /path/to/optimism/op-node
    ```

    The binary is then at `./bin/op-node`.
  </Step>

  <Step title="Set environment variables">
    ```bash theme={null}
    export L1_RPC_URL=...  # URL for the L1 node. Local default: http://127.0.0.1:8545
    export L1_RPC_KIND=... # alchemy, quicknode, infura, parity, nethermind, debug_geth, erigon, basic, any
    export L1_BEACON_URL=... # URL for the L1 Beacon HTTP endpoint. Local default: http://127.0.0.1:3500
    ```
  </Step>

  <Step title="Start op-node">
    <Info>
      The `op-node` RPC should not be exposed publicly. If left exposed, it could accidentally expose admin controls to the public internet.
    </Info>

    <Info>
      `--syncmode=execution-layer` enables [snap sync](/node-operators/reference/consensus-layer-sync), which works for both `op-reth` and `Nethermind` and removes the need to initialize the node with a data directory.
    </Info>

    <Info>
      `--l2.enginekind` tells op-node which kind of execution client it is driving. The binary defaults to `reth`, so this flag is shown for clarity and can be omitted when pairing with op-reth.
    </Info>

    ```bash theme={null}
    ./bin/op-node \
      --l1=$L1_RPC_URL \
      --l1.rpckind=$L1_RPC_KIND \
      --l1.beacon=$L1_BEACON_URL \
      --l2=ws://localhost:8551 \
      --l2.jwt-secret=./jwt.txt \
      --network=op-sepolia \
      --syncmode=execution-layer \
      --l2.enginekind=reth
    ```

    <Info>
      Some L1 nodes (e.g. Erigon) do not support `eth_getProof`. Add `--l1.trustrpc` if your L1 doesn't support it — this means op-node trusts the L1 node to provide correct data.
    </Info>
  </Step>
</Steps>

## Synchronization verification

Once the EL and op-node are running, you should see them begin to communicate and synchronize.

### Snap sync (default)

Initial synchronization can take several hours. At the start of snap sync, `op-node` will log:

```text theme={null}
INFO [03-06|10:56:55.602] Starting EL sync
INFO [03-06|10:56:55.615] Sync progress                            reason="unsafe payload from sequencer while in EL sync" l2_finalized=000000..000000:0 l2_safe=000000..000000:0 l2_pending_safe=000000..000000:0 l2_unsafe=4284ab..7e7e84:117076319 l2_time=1,709,751,415 l1_derived=000000..000000:0
INFO [03-06|10:56:57.567] Optimistically inserting unsafe L2 execution payload to drive EL sync id=4ac160..df4d12:117076320
```

`Starting EL sync` is shown once and the sync-progress / inserting logs repeat until done. `op-node` will log the following when finished:

```text theme={null}
lvl=info msg="Finished EL sync" sync_duration=23h25m0.370558429s finalized_block=0x4f69e83ff1407f2e2882f2526ee8a154ac326590799889cede3af04a7742f18d:116817417
```

The execution client logs its own header- and state-download progress in parallel:

<Tabs>
  <Tab title="op-reth">
    `op-reth` logs sync stages (headers, bodies, execution, state root) with periodic progress lines. Monitor the op-reth logs to confirm it is advancing through stages alongside the op-node `Sync progress` lines.
  </Tab>

  <Tab title="Nethermind">
    Snap sync in `Nethermind` works by:

    1. Downloading only the leaf nodes of the state tree
    2. Generating intermediate nodes locally
    3. Verifying the state root matches

    This approach is up to 10 times faster than traditional full sync.
  </Tab>
</Tabs>

### Full sync

Full sync rebuilds the chain from genesis and can take days to weeks on mature networks. Most operators should use snap sync (above) or [bootstrap from a pre-synced snapshot](https://datadirs.optimism.io/). Full-sync configuration is client-specific:

<Tabs>
  <Tab title="op-reth">
    op-reth's snap sync is the recommended initialization path. For alternative sync configurations, see the [op-reth configuration reference](/node-operators/reference/op-reth-config).
  </Tab>

  <Tab title="Nethermind">
    To use full sync with `Nethermind`, set:

    ```bash theme={null}
    ./Nethermind.Runner \
      -c op-sepolia \
      --Sync.SnapSync=false \
      --Sync.FastSync=false \
      --data-dir path/to/data/dir \
      --JsonRpc.JwtSecretFile=./jwt.txt
    ```

    Full sync will download and verify every block from genesis, which takes significantly longer than snap sync but provides the strongest security guarantees.
  </Tab>
</Tabs>

After the initial sync, `op-node` derives L1 batches into L2 blocks and feeds them to the execution client. You'll see logs like:

```text theme={null}
INFO [06-26|13:31:20.389] Advancing bq origin                      origin=17171d..1bc69b:8300332 originBehind=false
INFO [06-26|14:00:59.460] Sync progress                            reason="processed safe block derived from L1" l2_safe=7fe3f6..900127:4068014 l2_unsafe=7fe3f6..900127:4068014 l1_derived=6079cd..be4231:8301091
INFO [06-26|14:00:59.461] generated attributes in payload queue    txs=1  timestamp=1,673,564,098
INFO [06-26|14:00:59.463] inserted block                           hash=e80dc4..72a759 number=4,068,015 update_safe=true
```

The execution client logs its own block-import progress in parallel; refer to its documentation for log specifics.

## OP Mainnet archive nodes

<Info>
  You only need an archive node if you need historical state. Most node operators should default to full nodes.
</Info>

For op-reth, historical state for withdrawal proving is configured via either `--rpc.eth-proof-window` (no separate proofs database; size to your dispute-game cadence) or `--proofs-history` (bounded memory, larger storage). See:

* [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs) — full setup for `--proofs-history` (v2) on op-reth v2.2.3+.
* [Archive node guide](/node-operators/guides/management/archive-node) — flag overview for both paths.
* [OP Mainnet snapshots](https://datadirs.optimism.io/) — pre-synced op-reth datadirs to bootstrap from.

### Legacy Geth (pre-Bedrock, optional)

Blocks and transactions included in OP Mainnet before the Bedrock Upgrade cannot be executed by modern OP Mainnet nodes. Modern nodes serve these blocks but cannot run stateful queries like `eth_call` against them. For complete archive coverage of pre-Bedrock OP Mainnet state, run a Legacy Geth (`l2geth`) node alongside your modern node. This is **only** relevant to OP Mainnet archive nodes; skip if running a full node or OP Sepolia.

<Steps>
  <Step title="Build l2geth">
    ```bash theme={null}
    git clone https://github.com/ethereum-optimism/optimism-legacy.git
    cd optimism-legacy/l2geth
    make
    ```
  </Step>

  <Step title="Download the legacy Geth data directory">
    Download the snapshot from [Legacy Geth Data Directory (2.9TB)](/node-operators/guides/management/snapshots#op-mainnet-legacy) and verify:

    ```bash theme={null}
    sha256sum mainnet-legacy-archival.tar.zst
    # Expected: 4adedb61125b81b55f9bdccc2e85092050c65ef2253c86e2b79569732b772829
    ```

    Then extract:

    ```bash theme={null}
    tar xvf mainnet-legacy-archival.tar.zst
    ```
  </Step>

  <Step title="Start l2geth">
    ```bash theme={null}
    USING_OVM=true \
      ETH1_SYNC_SERVICE_ENABLE=false \
      RPC_API=eth,rollup,net,web3,debug \
      RPC_ENABLE=true \
      RPC_PORT=8546 \
      ./build/bin/geth --datadir /path/to/l2geth-datadir
    ```
  </Step>
</Steps>

## op-geth (legacy, end of support 2026-05-31)

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

<Accordion title="Build and run op-geth (legacy)">
  Pair op-geth with op-node by setting `--l2.enginekind=geth` instead of `reth` in the op-node command above.

  ### Build op-geth

  <Steps>
    <Step title="Clone op-geth">
      ```bash theme={null}
      git clone https://github.com/ethereum-optimism/op-geth.git
      cd op-geth
      ```
    </Step>

    <Step title="Check out the required release branch">
      Check the [op-geth releases page](https://github.com/ethereum-optimism/op-geth/releases) for the correct branch.

      ```bash theme={null}
      git checkout <name of release branch>
      ```
    </Step>

    <Step title="Build op-geth">
      ```bash theme={null}
      make geth
      ```
    </Step>
  </Steps>

  ### Start op-geth

  For an archive node, also set `--gcmode=archive`.

  ```bash theme={null}
  ./build/bin/geth \
    --http \
    --http.port=8545 \
    --http.addr=localhost \
    --authrpc.addr=localhost \
    --authrpc.jwtsecret=./jwt.txt \
    --verbosity=3 \
    --rollup.sequencerhttp=https://sepolia-sequencer.optimism.io/ \
    --op-network=op-sepolia \
    --datadir=$DATADIR_PATH
  ```

  The op-geth configuration reference has been retired; see the [op-reth configuration reference](/node-operators/reference/op-reth-config) for the equivalent op-reth flags.

  ### op-geth snap-sync stages

  op-geth's snap sync runs in two stages — header download then state download:

  ```text theme={null}
  lvl=info msg="Syncing beacon headers" downloaded=116775778 left=1162878 eta=53.182s
  ```

  ```text theme={null}
  lvl=info msg="Syncing: state download in progress" synced=99.75% state="191.33 GiB" accounts=124,983,227@25.62GiB slots=806,829,266@165.16GiB codes=78965@566.74MiB eta=-2m7.602s
  ```

  ```text theme={null}
  msg="Syncing: chain download in progress" synced=100.00% chain="176.01 GiB" headers=116,817,399@45.82GiB bodies=116,817,286@52.87GiB receipts=116,817,286@77.32GiB eta=77.430ms
  ```

  Once synced, op-geth logs block imports as op-node feeds payloads:

  ```text theme={null}
  INFO [06-26|14:02:12.974] Imported new potential chain segment     number=4,068,194 hash=a334a0..609a83 blocks=1 txs=1
  INFO [06-26|14:02:12.976] Chain head was updated                   number=4,068,194 hash=a334a0..609a83
  ```
</Accordion>

## Next steps

* If your node is up and running, check the [Node Metrics and Monitoring Guide](/node-operators/guides/monitoring/metrics) to keep tabs on it.
* If you run into problems, see the [Node Troubleshooting Guide](/node-operators/guides/troubleshooting).
* For permissionless chains setting up withdrawal proving, continue with [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs).


# Notice archive
Source: https://docs.optimism.io/notices/archive/index

Completed network notices for OP Stack operators, newest first, with the date each change took effect.

Every notice on this page is finished: the upgrade activated, the deprecation
took effect, or the exercise completed. They are kept because live pages link
into them and because they record what operators were asked to do at the time.
Their URLs are permanent.

For notices that still need action, see [Notices](/notices). For the permanent
record of a network upgrade (activation timestamps, governing specification,
and minimum component versions), see the
[hardfork registry](/op-stack/protocol/network-upgrades); contract-only
upgrades are in the registry's
[contract upgrades table](/op-stack/protocol/network-upgrades#contract-upgrades).

## Archived notices

The **Effective** column is the date the change took effect: mainnet hardfork
activation, the end-of-support date, the mainnet execution date of a contract
upgrade, or the start of a time-boxed experiment. A few notices never recorded
one. Those rows say so and are placed at their nearest known point in the
sequence rather than given a date they cannot support.

| Effective  | Notice                                                                                                     | What it covered                                                                                                                                                                                                                            |
| ---------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 2026-07-08 | [Upgrade 19: Karst hard fork](/notices/archive/upgrade-19)                                                 | Karst: the L2 Contract Manager (L2CM), `CANNON_KONA` promoted to the respected game type, a subset of Osaka EIPs on L2, and a preemptive BN256 pairing input-size reduction.                                                               |
| 2026-06-26 | [Deprecation of Req/Res CL P2P sync](/notices/archive/req-resp-cl-sync-deprecation)                        | Retirement of the `op-node` request-response consensus-layer P2P sync client in favor of syncing through the execution client. Removed in `op-node/v1.19.1`.                                                                               |
| 2026-05-31 | [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation)                          | End of support for op-geth and op-program, neither of which supports Karst. Migrate execution to op-reth and fault proofs to kona-client.                                                                                                  |
| 2026-05-26 | [Stake-based priority ordering on OP Mainnet](/notices/archive/stake-based-priority-ordering)              | A time-boxed OP Mainnet experiment giving stakers in the `PolicyEngineStaking` contract priority in transaction ordering, capped at four weeks.                                                                                            |
| Not dated  | [Deprecation of op-deployer upgrade and manage commands](/notices/archive/op-deployer-upgrade-deprecation) | `op-deployer manage` retired, and `op-deployer upgrade` capped at `op-contracts/v5.0.0`. L1 contract upgrades beyond that use superchain-ops or OPCM directly. Postdates `op-contracts/v6.0.0`.                                            |
| Not dated  | [Upgrade 18: Cannon + Kona and Custom Gas Token v2](/notices/archive/upgrade-18)                           | Contract-only upgrade adding the `CANNON_KONA` (8) game type alongside `CANNON` (0), Custom Gas Token v2, and the creator-pattern dispute game refactor. Shipped in [`op-contracts/v6.0.0`](/releases/op-contracts) (released 2026-03-16). |
| 2025-12-03 | [Fusaka upgrade notice](/notices/archive/fusaka-notice)                                                    | Readiness work so OP Stack chains keep deriving from an L1 that has activated Fusaka and its blob parameter-only forks. Not Fusaka adoption on L2.                                                                                         |
| 2025-12-02 | [Upgrade 17: Jovian hard fork](/notices/archive/upgrade-17)                                                | Jovian: a configurable minimum base fee, the data-availability footprint block limit, and Cannon support for Go 1.24.                                                                                                                      |
| 2025-10-02 | [Upgrade 16a](/notices/archive/upgrade-16a)                                                                | Maintenance contract upgrade superseding Upgrade 16: removes the unused interop withdrawal-proving code and adds `SystemConfig` feature toggles.                                                                                           |
| 2025-07-24 | [Upgrade 16: preparing for interop](/notices/archive/upgrade-16)                                           | Contract upgrade making `OptimismPortal` interop-ready, meeting updated Stage 1 requirements, adding Go 1.23 support in Cannon, and raising `MAX_GAS_LIMIT` to 500M. Invalidated existing withdrawal proofs.                               |
| 2025-05-14 | [Superchain withdrawal pause test](/notices/archive/superchain-withdrawal-pause-test)                      | A scheduled exercise of the Superchain-wide `pause` and `unpause` incident-response path. No user or operator action was required.                                                                                                         |
| 2025-05-09 | [Upgrade 15: Isthmus hard fork](/notices/archive/upgrade-15)                                               | Isthmus: Prague features on the OP Stack, the L2 withdrawals root in the block header, and the operator fee.                                                                                                                               |
| Not dated  | [Upgrade 14: MT-Cannon and Isthmus L1 contracts](/notices/archive/upgrade-14)                              | Contract upgrade shipping multithreaded 64-bit Cannon (MT-Cannon) and the Isthmus L1 contracts. Shipped in [`op-contracts/v3.0.0`](/releases/op-contracts) (released 2025-05-08); the notice's own mainnet date was an estimate.           |
| Not dated  | [L1 Pectra user fees and chain profitability](/notices/archive/pectra-fees)                                | How the [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623) gas repricing at L1 Pectra affected chains still posting data as calldata rather than blobs, and which Ecotone scalars to check.                                               |
| 2025-04-02 | [Upgrade 13: OPCM and incident response](/notices/archive/upgrade-13)                                      | Contract upgrade introducing the OP Contracts Manager (OPCM), fault-proof incident response improvements, and the `DeputyPauseModule`.                                                                                                     |
| 2025-03-20 | [Superchain testnets' blob fee bug](/notices/archive/blob-fee-bug)                                         | A testnet-only blob base fee miscalculation that overcharged L1 fees, and the hardfork activation that fixed it. Mainnet chains were never affected.                                                                                       |
| Not dated  | [Preparing for Pectra breaking changes](/notices/archive/pectra-changes)                                   | Breaking changes for chain and node operators when Pectra activated on L1. The page carries only tentative L1 slot times that were later superseded; it was last revised 2025-03-11.                                                       |
| 2025-01-09 | [Preparing for Holocene breaking changes](/notices/archive/holocene-changes)                               | Holocene: stricter block derivation, EIP-1559 parameters made configurable through `SystemConfig`, and the MIPS contract upgrade.                                                                                                          |


# Network Notices
Source: https://docs.optimism.io/notices/index

Active upgrade notices, deprecations, and network change announcements for OP Stack operators.

Notices are time-bound action items for application developers, node operators, and chain operators: upcoming
network upgrades, deprecations, and operational changes. Each hardfork also
has a permanent entry in the
[hardfork registry](/op-stack/protocol/network-upgrades) recording its
activation times, governing spec, and minimum component versions, and
contract-only upgrades are listed in the registry's
[contract upgrades table](/op-stack/protocol/network-upgrades#contract-upgrades) —
notices are archived after activation, registry pages are forever.

## Network upgrades

<CardGroup>
  <Card title="Upgrade 20" href="/notices/upgrade-20" icon="circle-info">
    Prepare Fault Proof services for Super Root Dispute Games and other maintenance smart contract upgrades
  </Card>

  <Card title="Interop Activation Prep" href="/notices/interop-prep" icon="circle-info">
    OP Sepolia and Unichain Sepolia interop activation preparation
  </Card>
</CardGroup>

## Operations

<CardGroup>
  <Card title="Specialized Node Topology" href="/notices/specialized-node-topology" icon="circle-info">
    Guidance for Supernode and Light CL node topology
  </Card>

  <Card title="Subblocks: 200 ms interval and payload changes" href="/notices/subblocks" icon="circle-info">
    A 200 ms subblock interval and four zeroed stream payload fields on OP Sepolia and OP Mainnet
  </Card>
</CardGroup>


# Prepare for interop on OP Sepolia and Unichain Sepolia
Source: https://docs.optimism.io/notices/interop-prep

Node operator action checklist for the OP Sepolia and Unichain Sepolia interop activation, targeted in July of 2026.

OP Stack interop is expected to activate on **OP Sepolia** (chain ID `11155420`) and **Unichain Sepolia** (chain ID `1301`) in **July of 2026**, forming a two-chain interop dependency set on testnet.
Node operators on either chain must change their topology before the activation timestamp: each operator runs one or more [op-supernode](/op-stack/interop/supernode) instances that derive both chains and validate the cross-chain messages between them, and the rest of the fleet runs as [Light CLs](/notices/specialized-node-topology) that follow the supernode.

<Warning>
  **A node that has not been migrated to the [supernode-plus-Light-CL topology](/notices/specialized-node-topology) by the activation timestamp cannot verify cross-chain dependencies.**
  Every op-node in the fleet must run with `--l2.follow.source` (env: `OP_NODE_L2_FOLLOW_SOURCE`) pointed at an op-supernode that derives both chains.
  Without that wiring — flag unset, or pointed at a non-supernode source — the op-node's safe head advances past the activation block without cross-chain validation, so the node cannot serve as a verifier or RPC source for the interop chain.
  The [Specialized op-node topology notice](/notices/specialized-node-topology) describes the pattern in detail.
  Start with that notice if your fleet hasn't moved off the homogeneous topology yet.
</Warning>

<Info>
  The activation timestamps for OP Sepolia and Unichain Sepolia are planned for in **July of 2026** but have not yet been finalized.
  Final timestamps will be published in the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) once governance approves the rollup-config update.
  This page will be updated with the exact timestamps once they are pinned.
  Interop on mainnet OP Stack chains is planned as a follow-up rollout after this testnet activation; mainnet activation timestamps will be announced separately.
</Info>

## What's changing

At the activation timestamp, OP Sepolia and Unichain Sepolia form a two-chain dependency set.
Every block on either chain can contain executing messages that reference initiating messages on the other; a block is only [safe](/op-stack/interop/explainer#block-safety-levels) once every initiating message it depends on has itself reached the same safety level.
The work of tracking both chains and proving those dependencies moves to a new component, [op-supernode](/op-stack/interop/supernode), that runs every chain in the dependency set together as virtual nodes inside one process.
The rest of the operator's fleet stops deriving locally and follows the supernode's safe view through op-node's [Light CL mode](/notices/specialized-node-topology).

For how cross-chain messages and block safety work under interop, see the [interop explainer](/op-stack/interop/explainer).

## Who this affects

This notice applies to anyone running OP Sepolia or Unichain Sepolia nodes after the activation timestamp.

Every op-node in the fleet — replicas, RPC nodes, or any other op-node deployment — must run as a Light CL pointed at an op-supernode that derives both chains.
Each operator stands up at least one op-supernode for the dependency set and reconfigures every op-node in their fleet to follow it.

This rollout is scoped to OP Sepolia and Unichain Sepolia.
Other OP Stack chains will activate the same Lagoon hardfork.
With an empty dependency set there's nothing to cross-validate, so those operators can keep running plain op-node.
Interop on OP Mainnet and Unichain follows in late July 2026, and other OP Stack chains move to the supernode topology only when they join an interop set.

## Required components

Update or install the following components before the activation timestamp.
Versions marked `TBD` will be pinned in this notice once the activation release candidates are finalized.

| Component      | Version | Role                                                                                                                                                                                                                                                                 |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `op-supernode` | `TBD`   | Runs OP Sepolia and Unichain Sepolia as virtual nodes inside one binary and verifies cross-chain messages. Required component. See the [supernode explainer](/op-stack/interop/supernode) and [configuration guide](/node-operators/guides/configuration/supernode). |
| `op-node`      | `TBD`   | Runs as a [Light CL](/notices/specialized-node-topology) on every node in the fleet; safe and finalized views are inherited from the supernode.                                                                                                                      |
| `op-reth`      | `TBD`   | Execution client. Run one per chain in the dependency set — an execution client cannot back two chains (op-node rejects a mismatched chain ID at startup), so a host serving both chains runs at least two execution-client processes.                               |

<Info>
  **op-reth is the required execution client.** op-geth end-of-support is **May 31, 2026** — see [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation). Interop activation lands after that date, so plan your fleet on op-reth.
</Info>

<Info>
  op-supernode does not yet have a stable release.
  Pull the latest candidate from the [op-supernode releases page](https://github.com/ethereum-optimism/optimism/releases?q=op-supernode).
  op-node and op-reth ship stable releases — track their respective release pages until this notice pins the exact activation versions.
</Info>

## Action checklist

The migration has four phases.
Complete each one and verify it on testnet before the activation timestamp.
Start the execution clients first, then the supernode — the supernode drives the ELs through their sync, because an EL has no way to know what chain head to target on its own.
Light CLs come last, since they follow the supernode.
Full per-flag reference for the supernode is in the [op-supernode configuration reference](/node-operators/reference/op-supernode-config); this notice walks through the testnet-specific setup.

The command examples in the steps are minimum viable configurations; they cover the flags required for the interop topology and nothing else.
Layer your usual production flags (monitoring, logging, P2P tuning, RPC modules, resource limits) on top as your environment requires.

<Steps>
  <Step title="Stand up execution clients for both chains">
    Run at least one op-reth process for OP Sepolia and at least one for Unichain Sepolia.
    Execution clients are not shared across chains.
    For each chain, plan one EL per consensus client connecting to it — one per supernode virtual node, plus one per Light CL in your fleet.
    Each execution client needs its own JWT secret file (a single shared file across both ELs is fine — see the note at the end of this step) and its own engine-API listen address.
    ELs can start unsynced; they wait until the supernode connects before they know what chain head to sync to.
    The supernode then drives each EL through its initial sync via the engine API, and tolerates the common case where one chain's EL is already synced and the other isn't.
    Configure each EL's history retention so the supernode can backfill initiating-message logs after restarts or downtime; the [EL retention recommendation](/node-operators/guides/configuration/supernode#configure-el-retention-for-supernode-backfill) in the supernode guide covers the retention window, the relevant op-reth pruning flags, and the extra requirements that apply if you also run op-challenger.

    ```bash theme={null}
    # OP Sepolia execution client
    op-reth node \
      --chain=optimism-sepolia \
      --datadir=/var/lib/op-reth-op-sepolia \
      --authrpc.addr=127.0.0.1 \
      --authrpc.port=8551 \
      --authrpc.jwtsecret=/etc/op/jwt-secret.txt

    # Unichain Sepolia execution client
    op-reth node \
      --chain=unichain-sepolia \
      --datadir=/var/lib/op-reth-unichain-sepolia \
      --authrpc.addr=127.0.0.1 \
      --authrpc.port=8561 \
      --authrpc.jwtsecret=/etc/op/jwt-secret.txt
    ```

    The example binds the engine RPC to `127.0.0.1`. If op-reth runs in a Docker container, or on a different host from the supernode, set `--authrpc.addr=0.0.0.0` (or a specific interface IP reachable from the supernode) and restrict access at the network layer.

    Each EL in the fleet has exactly one consensus client connected to it.
    The supernode drives its ELs via per-chain virtual nodes; each Light CL also gets its own EL.
    The supernode can share one JWT secret path across all of its virtual nodes, with per-chain overrides if an EL needs its own secret; the [shared JWT secret recommendation](/node-operators/guides/configuration/supernode) in the supernode guide covers the flags.
    Each Light CL connects to its EL with its own `--l2.jwt-secret` flag.
  </Step>

  <Step title="Stand up op-supernode for both chains">
    Run op-supernode with both chains in `--chains` (`11155420,1301`), a shared L1 RPC, and a shared beacon endpoint.
    The [example configuration](/node-operators/guides/configuration/supernode#example-configuration) in the supernode guide is written for exactly this dependency set (OP Sepolia plus Unichain Sepolia); use it as your starting point, and keep the engine kind set to `reth` for both chains since the fleet runs op-reth.
    Follow the guide's recommendation to configure a beacon archiver fallback from the start, so a supernode that has been offline for an extended period can still recover pruned blobs.

    For the full flag reference, see the [op-supernode configuration reference](/node-operators/reference/op-supernode-config); for recommendations, see the [supernode configuration guide](/node-operators/guides/configuration/supernode).
  </Step>

  <Step title="Migrate every op-node in the fleet to Light CL">
    On every op-node, set `--l2.follow.source` to your op-supernode's per-chain RPC endpoint (the `/<chainID>` path prefix).
    This disables local derivation; the op-node becomes a Light CL and inherits its safe and finalized view from the supernode.

    ```bash theme={null}
    # OP Sepolia verifier / RPC op-node
    op-node \
      --network=op-sepolia \
      --l1=<your-sepolia-l1-eth-rpc> \
      --l1.beacon=<your-sepolia-l1-beacon-rpc> \
      --l2=http://op-sepolia-reth:8551 \
      --l2.jwt-secret=/etc/op/jwt-secret.txt \
      --l2.follow.source=http://op-supernode:8545/11155420 \
      --rpc.addr=0.0.0.0 \
      --rpc.port=9545

    # Unichain Sepolia verifier / RPC op-node
    op-node \
      --network=unichain-sepolia \
      --l1=<your-sepolia-l1-eth-rpc> \
      --l1.beacon=<your-sepolia-l1-beacon-rpc> \
      --l2=http://unichain-sepolia-reth:8561 \
      --l2.jwt-secret=/etc/op/jwt-secret.txt \
      --l2.follow.source=http://op-supernode:8545/1301 \
      --rpc.addr=0.0.0.0 \
      --rpc.port=9546
    ```

    `--l1` and `--l1.beacon` are still required at startup even in Light CL mode — op-node rejects the configuration without them.
    The Light CL stops issuing L1 RPC calls for derivation work itself; it still keeps L1 references open for runtime config updates and engine-API book-keeping.
    Unsafe-head progression over P2P is unchanged.

    For background on the topology and why it scales, see the [specialized op-node topology notice](/notices/specialized-node-topology).
  </Step>

  <Step title="Plan the production topology before activation">
    For production fleets, run several supernodes as a highly available pool behind a consensus-aware proxyd and point the Light CLs at the pool rather than at a single supernode; a lone supernode is fine for evaluating the setup, but it is a single point of failure for safe-head progression on both chains.
    Put this in place before the activation timestamp: the [HA pool recommendation](/node-operators/guides/configuration/supernode#run-an-ha-pool-of-supernodes-behind-a-consensus-aware-proxyd) in the supernode guide covers the pool size, routing strategy, and failure behavior.
  </Step>
</Steps>

## Verify your setup before activation

Run these checks against your topology before the activation timestamp.
None of them require interop to be active on either chain; they exercise the supernode-plus-Light-CL plumbing on its own so the activation block does not surface configuration errors for the first time.

### Confirm the supernode is hosting both chains

Watch the supernode's logs using whatever you already use (`docker logs -f op-supernode`, `journalctl -fu op-supernode`, `kubectl logs -f op-supernode`, etc.).
Each chain container tags its log lines with its `chain_id`, so a healthy supernode produces interleaved derivation lines for both chains.
The most common line during catch-up is `"Advancing bq origin"` (the batch-queue is walking forward through L1):

```text theme={null}
t=2026-06-20T12:00:00+0000 lvl=info msg="Advancing bq origin" chain_id=11155420 vn_id=7754 origin=0x...:4071413 originBehind=false
t=2026-06-20T12:00:00+0000 lvl=info msg="Advancing bq origin" chain_id=1301     vn_id=d5ca origin=0x...:6728414 originBehind=false
```

Both `chain_id=11155420` and `chain_id=1301` should appear regularly.
If you only see one chain, the other's container failed to start or its execution client is unreachable — error-level lines tagged with the missing chain explain why.
Once the supernode catches up and starts promoting heads, you will also see `msg="Sync progress"` lines with `l2_safe`, `l2_unsafe`, and `l2_finalized` fields tagged with the same `chain_id`.

If you have Prometheus scraping the supernode, the gauge `op_node_supernode_refs_number{layer="l2",type="l2_safe"}` carries the per-chain safe head on the `virtual_node_chain_id` label — a single Grafana panel makes the per-chain progression continuously visible.

### Confirm a Light CL is following the supernode

Watch a Light CL's logs the same way and look for `"Follow Source: Process external refs"` and `"Follow Upstream"` lines.
A working Light CL produces these continuously while it polls the supernode's `optimism_syncStatus`:

```text theme={null}
t=2026-06-20T12:00:00+0000 lvl=info msg="Safety levels" unsafe=enabled safe=http://op-supernode:8545/11155420
t=2026-06-20T12:00:00+0000 lvl=info msg="Follow Upstream" eSafe=0x...:12345678 eLocalSafe=0x...:12345678 eFinalized=0x...:12345670 eCurrentL1=0x...:4071600
t=2026-06-20T12:00:00+0000 lvl=info msg="Follow Source: Process external refs" externalSafe=0x...:12345678 externalLocalSafe=0x...:12345678 externalFinalized=0x...:12345670
```

The first `"Safety levels"` line is the smoke test: if `safe=` shows your supernode URL and per-chain prefix, the wiring is right.
Once the supernode is past initial sync and starts promoting safe heads, `eSafe` and `externalSafe` carry climbing block numbers.
If the Light CL never advances past genesis (`eSafe=...:0`) for many minutes, `--l2.follow.source` is pointed at the wrong URL or namespace — recheck the per-chain prefix (`/11155420` for OP Sepolia, `/1301` for Unichain Sepolia).

If you scrape Prometheus, the equivalent gauge on a Light CL is `op_node_default_refs_number{layer="l2",type="l2_safe"}` — one Grafana panel per Light CL plus one panel per supernode chain, side by side, makes any divergence obvious.

## Troubleshooting

* **Safe head advances but RPC consumers report invalid blocks.** The op-node isn't following an op-supernode — either `--l2.follow.source` is unset, or it points at a non-supernode source — so safe-head promotion skips cross-chain validation. Point `--l2.follow.source` at a supernode that derives both chains.
* **Blobs missing for L1 blocks older than \~18 days.** The primary beacon node has pruned them. Configure `--l1.beacon-fallbacks` against a non-pruning beacon or an archiver service. See the [blob archiver guide](/node-operators/guides/management/blobs#configure-a-blob-archiver) for options.
* **Light CL safe head lags the supernode by more than a few blocks.** Check the network path between Light CL and supernode (or supernode `proxyd`). The Light CL polls `optimism_syncStatus` over RPC; a high-latency or rate-limited path here directly delays safe-head propagation.

## Resources

* [Interop explainer](/op-stack/interop/explainer) — how cross-chain messages and block safety work under interop.
* [op-supernode explainer](/op-stack/interop/supernode) — what op-supernode is, why it exists, and how it pairs with Light CL.
* [Supernode configuration guide](/node-operators/guides/configuration/supernode) — recommended settings and starter configuration.
* [op-supernode configuration reference](/node-operators/reference/op-supernode-config) — full flag and environment-variable catalogue.
* [Specialized op-node topology notice](/notices/specialized-node-topology) — operator-facing pattern for running Light CL fleets behind a safe source.
* [Interop reorg awareness](/op-stack/interop/reorg) — how the safety model handles equivocation and L1 reorgs.
* [Cross-chain security measures](/op-stack/security/interop-security) — how the safety level for inbound cross-chain messages is configured at the chain level.
* [Running op-reth with Historical Proofs](/node-operators/tutorials/reth-historical-proofs) — only relevant if you also run op-challenger; configures the supernode's ELs to serve historical proofs.


# Specialized op-node topology with light nodes
Source: https://docs.optimism.io/notices/specialized-node-topology

OP Labs highly recommends migrating from homogeneous op-node fleets to a specialized topology where only designated source nodes derive from L1 and the rest run as light nodes via --l2.follow.source.

Historically, every `op-node` in a fleet has independently derived the [safe chain](https://docs.optimism.io/op-stack/reference/glossary#safe-l2-block) from L1 while also consolidating [unsafe blocks](https://docs.optimism.io/op-stack/reference/glossary#unsafe-l2-block) received over gossip. As fleets grow and upcoming features like interop raise the cost of derivation, we **highly recommend** migrating to a **specialized topology** in which a small number of `op-node` instances are dedicated to L1 derivation and the rest defer to those sources.

In the specialized topology, **light nodes** are started with `--l2.follow.source` pointing at a derivation source. The source is an `op-node` for chains without interop activation, or an [`op-supernode`](/op-stack/interop/supernode) for chains in an interop dependency set (one supernode derives every chain in the set together and adds cross-chain message verification). Light nodes disable their own independent derivation and instead receive the safe chain from the source, while continuing to track the unsafe tip via gossip and the engine API.

<Warning>
  **Required for upcoming interop activation.** This topology is required for node operators on **OP Sepolia** and **Unichain Sepolia** once interop activates on those chains in late June 2026 — see [Prepare for interop on OP Sepolia and Unichain Sepolia](/notices/interop-prep) for the action checklist. The corresponding mainnet activation will carry the same requirement.
</Warning>

## What this means

* **Source nodes** derive the full chain from L1. For chains without interop, this is a traditional `op-node`. For chains in an interop dependency set, it is an `op-supernode`, which derives every chain in the set together and verifies cross-chain messages.
* **Light nodes** are `op-node` instances started with `--l2.follow.source=<source RPC endpoint>`. They stop deriving from L1 themselves and receive the safe chain from the designated source — an op-node RPC for non-interop chains, an op-supernode RPC (with the chain's `/<chainID>` path prefix) for interop chains.
* `op-node` is **not** being deprecated, and the homogeneous topology is **not** being removed. For chains where interop has not activated, this is a recommended operational upgrade rather than a required migration. For OP Sepolia and Unichain Sepolia, it becomes required at interop activation (see the Warning above).
* Only the derivation role changes. Light nodes continue to serve RPC, participate in gossip, and drive their connected execution client as before.

## Why this matters

### L1 utilization reduction

Only the source nodes ingest L1 data for derivation. Light nodes no longer issue L1 RPC calls for the derivation pipeline, which meaningfully reduces L1 API load and provider costs for operators running many nodes.

### Performance specialization

Light nodes shed the L1 derivation workload and can focus on advancing the unsafe chain and serving RPC, while source nodes focus exclusively on derivation.

### Asymmetric scaling

RPC-serving capacity and derivation capacity can now be scaled independently. Operators can add or remove light nodes to match read traffic without changing L1 load, and can size the source tier separately based on derivation requirements and redundancy targets.

### Lower cost for future rollouts

Future upgrades — including interop — will require more sophisticated derivation logic. Centralizing derivation behind a small, well-defined source tier minimizes the operational surface area affected by those upgrades and reduces the per-node cost of adopting them.

## How to migrate

### Node operators

Plan a migration from a homogeneous fleet of derivation-enabled `op-node` instances to a specialized topology:

1. Stand up the **source tier**. For chains without interop, designate one or more `op-node` instances as sources, configured with full L1 derivation. For chains in an interop dependency set, the source tier is one or more `op-supernode` instances covering every chain in the set. Either way, size and monitor the source tier with redundancy for failover.
2. Provision the remaining `op-node` instances as **light nodes** by setting `--l2.follow.source=<source op-node RPC endpoint>` (env: `OP_NODE_L2_FOLLOW_SOURCE`). Ensure light nodes can reach the source endpoint over a reliable, low-latency network path.
3. Validate that light nodes track the safe chain correctly against the source before shifting production traffic.
4. Update dashboards and alerting so the source tier's health is treated as a dependency of the light-node tier.

#### Highly available topology with consensus-aware proxyd

For production deployments, we recommend placing the derivation tier behind a [consensus-aware `proxyd`](/chain-operators/tools/proxyd#consensus-awareness) and exposing light nodes to users through a separate RPC-serving tier:

<img alt="Specialized op-node topology: three source op-nodes with EL (Reth) feed a consensus-aware proxyd via CL API, which fans out to two light op-nodes via --l2.follow.source" />

* **Deriver tier** — a small, redundant set of source instances (`op-node` for non-interop chains, `op-supernode` for interop chains). These sit behind a `proxyd` configured with routing strategy: `consensus_aware_consensus_layer`, which aggregates the multiple sources into a single highly available endpoint and hides individual failures or reorgs from downstream consumers.
* **Light-node tier** — a horizontally scalable pool of light `op-node` instances started with `--l2.follow.source` pointed at the deriver-tier `proxyd` endpoint. This tier can be scaled up and down independently based on read traffic.
* **Edge tier** — an API gateway or user-facing `proxyd` that fronts the light-node tier and handles external RPC traffic, rate limiting, and routing.

In all cases, consider your existing topology and apply node specialization in a way that works best with your deployment stack. The goal is to have a minimal, well defined source tier (op-node or op-supernode, per chain) and a scalable collection of light nodes pointed at it.

### Chain operators

All guidance for Node Operators is applicable to Chain Operators. For `op-node` instances serving as Sequencers, we suggest those nodes use `--l2.follow.source` to offload the work of derivation. Benchmarking indicates removing derivation eliminates some bottlenecks when producing blocks, and the role
of the Sequencer is to maintain and extend the Unsafe Chain.

<Info>
  On chains where interop has not activated, the specialized topology is a recommendation, not a hard requirement. Existing homogeneous deployments on those chains continue to work, and migration can be done incrementally, one light node at a time.
</Info>

<Warning>
  `op-node` is not sufficient as a derivation source for chains in an interop dependency set — those chains use [`op-supernode`](/op-stack/interop/supernode), which derives every chain in the set together and verifies cross-chain messages. Future protocol features may impose similar requirements on other chains. Operators who keep running large fleets of derivation-enabled `op-node` instances on chains where the source role is changing should expect a higher operational burden: more L1 API cost today, and a per-node cost to upgrade every derivation-enabled instance as new derivation requirements land. Specializing the topology now minimizes the number of nodes affected by those changes.
</Warning>

## Resources

* [Interop prep notice](/notices/interop-prep) — node-operator action checklist for the OP Sepolia and Unichain Sepolia interop activation, where this topology is required rather than recommended.
* `--l2.follow.source` flag (env: `OP_NODE_L2_FOLLOW_SOURCE`) — configures an `op-node` as a light node pointed at a source `op-node` RPC endpoint.
* `--l2.follow.source.rpc-timeout` flag (env: `OP_NODE_L2_FOLLOW_SOURCE_RPC_TIMEOUT`) — tunes the RPC call timeout used when talking to the source (default `10s`).


# Subblocks: 200 ms interval and stream payload changes
Source: https://docs.optimism.io/notices/subblocks

Subblocks (formerly Flashblocks) move to a 200 ms interval on OP Sepolia and OP Mainnet, and zero four fields in the stream payload.

Subblocks (formerly Flashblocks) stream pre-confirmations on OP Stack chains.
Two changes are rolling out to OP Sepolia and OP Mainnet: the subblock interval drops from 250 ms to 200 ms, and four fields in the stream payload are set to their zero value.

The stream keeps its existing wire format, and the payload type is still named `ExecutionPayloadFlashblockDeltaV1`.

<Warning>
  The subblock stream sets `state_root`, `block_hash`, `withdrawals_root`, and `withdrawals` to their zero value.
  The stream remains wire compatible, so reads return a zero value rather than raising an error.
  Audit stream integrations before **August 17, 2026**.
</Warning>

## What this means

* **The interval drops from 250 ms to 200 ms.** This brings OP Sepolia and OP Mainnet to `FLASHBLOCKS_TIME = 200ms`, the default in the [Flashblocks specification](https://specs.optimism.io/protocol/flashblocks.html).
* **Four payload fields are set to their zero value.** All four remain present in `ExecutionPayloadFlashblockDeltaV1`. Nothing is removed from the wire format.
* **Every other field, including `receipts_root` and `logs_bloom`, continues to carry a real value.**

| Field              | Zero value on the stream |
| ------------------ | ------------------------ |
| `state_root`       | `0x0000...0000`          |
| `block_hash`       | `0x0000...0000`          |
| `withdrawals_root` | `0x0000...0000`          |
| `withdrawals`      | `[]`                     |

An integration that reads any of these fields receives a zero value and continues, rather than failing loudly at the parse boundary.
We recommend you audit your application or integration for these reads directly ahead of the migration.

## The rollout is gradual

This is a rolling change rather than a single switch, so you may see both the previous and the new behavior for a period.

## Action required

For teams consuming the subblock stream directly:

* Audit integrations for reads of `state_root`, `block_hash`, `withdrawals_root`, and `withdrawals`.
* Confirm that a zero value in any of them cannot propagate into downstream state, balances, or proofs.
* RPC providers that forward stream payloads to their own consumers should pass this notice on to those consumers.

## Timeline

| Network    | Target rollout  |
| ---------- | --------------- |
| OP Sepolia | August 17, 2026 |
| OP Mainnet | August 31, 2026 |

Both dates are targets and may move.

## Key links

| Resource                  | Link                                                                                         |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| Flashblocks specification | [specs.optimism.io](https://specs.optimism.io/protocol/flashblocks.html)                     |
| Subblocks explainer       | [How Subblocks work](/op-stack/features/subblocks)                                           |
| App integration guide     | [Integrate Subblocks in your app](/app-developers/guides/transactions/integrating-subblocks) |


# Upgrade 20
Source: https://docs.optimism.io/notices/upgrade-20

Prepare Fault Proof services and contract integrations for the Upgrade 20 move to Super Root Dispute Games.

Upgrade 20 is an L1 smart contract upgrade for OP Stack chains.
It moves Fault Proofs from Output Root Dispute Games to Super Root Dispute Games and includes `SystemConfig` and OP Contracts Manager (OPCM) maintenance changes.

## Why Upgrade 20

Output Root Dispute Games commit to one chain's state at an L2 block number.
Interop requires a dispute game format that can commit to the state of multiple chains at the same timestamp.
Super Root Dispute Games provide that format.

Upgrade 20 moves each chain to Super Root Dispute Games before shared cross-chain dispute infrastructure is enabled.
Each game created after this upgrade still contains one chain's Output Root.
The upgrade does not enable Interop, call `OPCM.migrate()`, or move a chain to a shared Dispute Game setup.

Super Root Dispute Games use a timestamp as the `l2SequenceNumber` and validate an incorrect proposal timestamp through the Fault Proof state transition.
This removes the separate L2 block number challenge used by Output Root Dispute Games.
The `OptimismPortal` continues to support both formats, so games and withdrawal proofs created before the upgrade remain valid.

## What's included

### Super Root Dispute Games

Upgrade 20 adds the following Super Root Dispute Game types:

* `SUPER_PERMISSIONED` (game type `5`) for chains that use permissioned Fault Proofs.
* `SUPER_CANNON_KONA` (game type `9`) for chains that use permissionless Fault Proofs.

A permissioned chain remains permissioned.
A permissionless chain runs both Super Root Dispute Game types and uses `SUPER_CANNON_KONA` as its respected game type.
Existing Dispute Games continue to resolve through their original game types.

The upgrade keeps each chain's existing `AnchorStateRegistry` and `DisputeGameFactory`.
It uses an `OPCM.upgrade()` transaction rather than migrating the chain to a shared Dispute Game setup.

### SystemConfig Interface Cleanup

Upgrade 19 recomputed the onchain `SystemConfig` batch inbox address for chains deployed before OPCM.
The change did not affect derivation because OP Stack clients read the batch inbox address from the chain's rollup configuration, but it left the redundant onchain value out of sync.

Upgrade 20 removes `batchInbox()` and clears its legacy storage slot.
It also removes the deprecated `setGasConfig(uint256,uint256)` function, which could leave `scalar()` out of sync with the fee scalar values that OPCM preserves during an upgrade.
The updated `SystemConfig` has contract version `4.0.0`.

The deprecated `overhead()` getter remains available for compatibility with existing integrations, but the upgrade sets the stored value to zero.
Because `setGasConfig(uint256,uint256)` was its only writer, the value stays zero after the upgrade.
To preserve the two-word `FEE_SCALARS` event payload without requiring a hardfork, calls to `setGasConfigEcotone(uint32,uint32)` encode zero in the first word.

## Breaking Changes

### Chain Operators

Chain operators must coordinate the L1 contract cutover with the services that propose, challenge, and monitor Fault Proofs.

* Switch `op-proposer` to the new Super Root RPC and game type at the contract cutover.
* Configure `op-challenger` and `op-dispute-mon` to support Super Root Dispute Games while retaining the configuration needed to finish games already in progress.
* For permissionless Fault Proofs, stage the reviewed `kona-client` Interop variant prestate before the cutover.
* Update operational tooling that calls the removed `SystemConfig` functions.

The [OP Stack component changes](#prepare-op-stack-components), [`SystemConfig` integration changes](#update-systemconfig-integrations), and [prestate workflow](#locate-or-build-the-absolute-prestate) are described below.

### Node Operators

Upgrade 20 has no L2 hardfork, and it does not require an `op-node` or `op-reth` configuration change.
If the node also provides a Super Root RPC to Fault Proof services, keep that endpoint reachable during and after the cutover.

### App Developers and Infrastructure Integrators

Ordinary L2 contracts and transactions are not affected.
Update an integration if it does any of the following:

* Calls `SystemConfig.batchInbox()` or `SystemConfig.setGasConfig(uint256,uint256)`.
* Decodes the first word of a `FEE_SCALARS` `ConfigUpdate` event as the current `overhead()` value.
* Reads `SystemConfig.overhead()` and expects the legacy value to remain unchanged.
* Reads Dispute Game root claims directly and assumes the claim is an Output Root.
* Uses an OP Stack SDK to check, prove, or finalize L2-to-L1 withdrawals.

For Super Root Dispute Games, direct Dispute Game integrations must recognize game types `5` and `9` and use `rootClaimByChainId(uint256)` to obtain the chain's Output Root.
The `overhead()` getter remains available for compatibility but is deprecated, and it returns zero after Upgrade 20.
Applications that use `viem/op-stack` for withdrawal proving must upgrade to `viem` `2.51.0` or later and follow the [withdrawal tooling changes](#update-withdrawal-tooling).
Bridge operators and developers of withdrawal tooling that read Dispute Game contracts directly must follow the same guidance.
Tooling that delegates the withdrawal flow to an SDK must use a version that supports Super Root Dispute Games.

### Users

No action is required.
Withdrawal proofs submitted before Upgrade 20 remain valid.
Users do not need to re-prove them.
Existing Output Root Dispute Games continue to resolve, and the `OptimismPortal` supports withdrawal proofs from both Output Root and Super Root Dispute Games.

## Prepare OP Stack components

Use the following configuration changes when staging the Upgrade 20 component releases:

| Component                              | Required change                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `op-challenger`                        | Add `--superroot-rpc` (`OP_CHALLENGER_SUPERROOT_RPC`) and keep the existing game types so the challenger can finish games already in progress. On a permissionless chain, append `super-cannon-kona` to `--game-types` (`OP_CHALLENGER_GAME_TYPES`) and configure the reviewed Kona Interop prestate. On a permissioned chain, do not add `super-permissioned`; the simplified game does not require a trace type, and `op-challenger` handles its lifecycle automatically. |
| `op-dispute-mon`                       | Add `--superroot-rpc` (`OP_DISPUTE_MON_SUPERROOT_RPC`). Keep `--rollup-rpc` while Output Root Dispute Games remain in progress.                                                                                                                                                                                                                                                                                                                                             |
| `op-proposer`                          | Switch at the contract upgrade cutover. Replace `--rollup-rpc` with `--superroot-rpcs` (`OP_PROPOSER_SUPERROOT_RPCS`) and set `OP_PROPOSER_GAME_TYPE=5` for a permissioned chain or `OP_PROPOSER_GAME_TYPE=9` for a permissionless chain.                                                                                                                                                                                                                                   |
| `op-node`, `op-reth`, and `op-batcher` | No configuration change is required. Upgrade 20 has no hardfork activation.                                                                                                                                                                                                                                                                                                                                                                                                 |

The Super Root RPC must return a root for the chain or dependency set that the Dispute Game covers.
For a single-chain upgrade, use the chain's `op-node` RPC endpoint or the chain-specific endpoint exposed by an `op-supernode`.

## Update `SystemConfig` integrations

<Warning>
  Calls to `SystemConfig.batchInbox()` and `SystemConfig.setGasConfig(uint256,uint256)` revert after Upgrade 20.
</Warning>

If your tooling reads or writes `SystemConfig` directly:

* Read the batch inbox address from the chain's rollup configuration or its entry in the [Superchain Registry](https://github.com/ethereum-optimism/superchain-registry).
* Replace `setGasConfig(uint256,uint256)` calls with [`setGasConfigEcotone(uint32,uint32)`](/chain-operators/reference/fee-parameters) for the base fee and blob base fee scalars.
* If you decode `FEE_SCALARS` `ConfigUpdate` events, treat the first word as zero rather than the current value returned by `overhead()`.
* If you read `overhead()`, expect zero. The upgrade clears any legacy value.

## Update withdrawal tooling

Super Root Dispute Games anchor withdrawals by L2 timestamp instead of L2 block number, and their root claim contains a Super Root instead of the chain's Output Root.
Application tooling that discovers a Dispute Game or builds a withdrawal proof must support both changes.

| Tooling                                          | Required change                                                                                                                                                                                                                       |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`viem/op-stack`](https://viem.sh/op-stack)      | Use `viem` `2.51.0` or later. For prove-readiness calls, pass the initiating withdrawal block timestamp as `l2Timestamp`. Pass the `game` returned by `waitToProve` to `buildProveWithdrawal`; do not pass the legacy `output` value. |
| `ethers`, wagmi, and other general EVM libraries | No library update is required for ordinary contract reads, writes, or L2 transactions. Update only custom withdrawal or Dispute Game code that makes the Output Root assumptions described above.                                     |

After the Upgrade 20 cutover, a `viem` withdrawal prove flow must read the timestamp of the L2 block that contains the initiating transaction:

```js theme={null}
const receipt = await publicClientL2.getTransactionReceipt({
  hash: withdrawalHash
});
const withdrawalBlock = await publicClientL2.getBlock({
  blockNumber: receipt.blockNumber
});

const { game, withdrawal } = await publicClientL1.waitToProve({
  receipt,
  l2Timestamp: withdrawalBlock.timestamp,
  targetChain: publicClientL2.chain
});

const proveArgs = await publicClientL2.buildProveWithdrawal({
  game,
  withdrawal
});
```

Pass the same `l2Timestamp` when calling `getTimeToProve` or `getWithdrawalStatus` for a Super Root withdrawal.
`waitToFinalize` and the finalization transaction do not require the timestamp.
See the [`viem` Super Root withdrawal support release](https://github.com/wevm/viem/releases/tag/viem%402.51.0) for the upstream compatibility change.

## Locate or build the absolute prestate

Permissionless chains need the Upgrade 20 `kona-client` Interop variant absolute prestate for `SUPER_CANNON_KONA`. Use the `kona-client-int` artifact even when Interop is not scheduled for the chain.

<Tabs>
  <Tab title="Standard chain configuration">
    Use the `cannon64-kona-interop` hash published for the Upgrade 20 release in [`standard-prestates.toml`](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-prestates.toml).

    Check out the Kona release tag associated with the published Upgrade 20 prestate hash, reproduce both Kona prestates, and read the interop hash:

    ```bash theme={null}
    just reproducible-prestate-kona
    jq -r .pre rust/kona/prestate-artifacts-cannon-interop/prestate-proof.json
    ```

    Confirm the output matches the published hash.
    Host the generated hash-named `.bin.gz` file on the prestate server used by `op-challenger`.
  </Tab>

  <Tab title="Custom chain configuration">
    First, stage the chain data described in [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate).
    Check out the Kona release tag associated with the reviewed Upgrade 20 prestate and build the interop variant with the same custom configuration:

    ```bash theme={null}
    cd rust
    KONA_CUSTOM_CONFIGS_DIR=/absolute/path/to/custom-configs \
      just build-kona-reproducible-prestate-variant \
      kona-client-int prestate-artifacts-cannon-interop
    jq -r .pre kona/prestate-artifacts-cannon-interop/prestate-proof.json
    ```

    Rebuild from a clean checkout with the same inputs and confirm the hash is identical.
    Host the generated hash-named `.bin.gz` file at a URL reachable by every challenger that participates on the chain.
    A custom prestate hash is specific to its embedded chain configuration and does not appear in `standard-prestates.toml`.
  </Tab>
</Tabs>

## Upgrade timing

Upgrade 20 is applied as an L1 contract upgrade and has no L2 hardfork activation timestamp.
Pending governance approval, we expect the upgrade to be executed in September.

The [Output Root to Super Root upgrade runbook](/chain-operators/tutorials/upgrade-chain-to-super-roots) describes the onchain upgrade and cutover checks.

## Verify readiness

Before the cutover:

* Confirm `op-proposer`, `op-challenger`, and `op-dispute-mon` start with the staged Super Root configuration and can reach the configured Super Root RPC.
* On a permissionless chain, reproduce the `kona-client` Interop variant prestate and confirm its hash matches the reviewed Upgrade 20 value.
* Run integration tests that cover every direct `SystemConfig` call and every withdrawal or Dispute Game code path listed in this notice.

If you have questions or need support, contact your Optimism point of contact.


# OP Mainnet
Source: https://docs.optimism.io/op-mainnet/index

Routes builders deploying on OP Mainnet to the network information, contract addresses, finality reference, and chain history they need.

You are building on OP Mainnet. If you are early in your journey, you do not
need to run your own chain: deploy your app directly on OP Mainnet and use
this section as your reference for the network itself.

<CardGroup>
  <Card title="Deploy your first app on OP Mainnet" href="/app-developers/quickstarts/get-started">
    Go from zero to a working app on OP Mainnet with the app developer
    quickstart.
  </Card>

  <Card title="Connect to the network" href="/op-mainnet/network-information/connecting-to-op">
    Get RPC endpoints, chain IDs, currency symbols, and block explorers for
    OP Mainnet and OP Sepolia.
  </Card>

  <Card title="Look up contract addresses" href="/op-mainnet/network-information/op-addresses">
    Find the L1 and L2 contract addresses for OP Mainnet and OP Sepolia.
  </Card>

  <Card title="Check transaction finality" href="/op-mainnet/network-information/transaction-finality">
    See how quickly your transactions reach soft and hard finality on OP
    Mainnet.
  </Card>

  <Card title="Trace pre-Bedrock history" href="/op-mainnet/pre-bedrock-history/regenesis-history">
    Understand OP Mainnet's regenesis events and where pre-Bedrock data lives
    today.
  </Card>

  <Card title="Need your own chain after all?" href="/">
    Route by role from the documentation home: chain operators, node
    operators, and protocol learners each have their own section.
  </Card>
</CardGroup>


# Connecting to OP Mainnet
Source: https://docs.optimism.io/op-mainnet/network-information/connecting-to-op

Documentation for OP Mainnet and OP Sepolia. This page covers network information including network names, chain IDs, RPC endpoints, currency symbols, block explorers, and contract addresses.

This page provides network information for OP Mainnet and OP Sepolia, including RPC endpoints, chain IDs, and block explorers.

<Info>
  The public RPC URLs provided below are rate limited and do not support websocket connections.
  If you are experiencing rate limiting issues or need websocket functionality, consider [running your own node](/node-operators/overview) or signing up for a [third-party RPC provider](/app-developers/reference/rpc-providers).
</Info>

## OP Mainnet

| Parameter                            | Value                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Network Name                         | `OP Mainnet`                                                                                    |
| Chain ID                             | `10`                                                                                            |
| Currency Symbol<sup>1</sup>          | ETH                                                                                             |
| Explorer                             | [https://explorer.optimism.io](https://explorer.optimism.io)                                    |
| Public RPC URL                       | [https://mainnet.optimism.io](https://mainnet.optimism.io)                                      |
| Sequencer URL<sup>2</sup>            | [https://mainnet-sequencer.optimism.io](https://mainnet-sequencer.optimism.io)                  |
| Subblocks websocket URL <sup>3</sup> | [wss://op-mainnet-fb-ws-pub.optimism.io/ws](wss://op-mainnet-fb-ws-pub.optimism.io/ws)          |
| Contract Addresses                   | Refer to the [Contract Addresses page](/op-mainnet/network-information/op-addresses#op-mainnet) |
| Connect Wallet                       | [Click here to connect your wallet to OP Mainnet](https://chainid.link?network=optimism)        |

1. The "currency symbol" is required by some wallets like MetaMask.
2. The sequencer URL is write only.
3. Strictly rate-limited public URL. Please rely on Ethereum JSON RPC or reach out to the Optimism team for a more relaxed private endpoint.

## OP Sepolia

| Parameter                            | Value                                                                                           |
| ------------------------------------ | ----------------------------------------------------------------------------------------------- |
| Network Name                         | `OP Sepolia`                                                                                    |
| Chain ID                             | `11155420`                                                                                      |
| Currency Symbol<sup>1</sup>          | ETH                                                                                             |
| Explorer                             | [https://testnet-explorer.optimism.io](https://testnet-explorer.optimism.io)                    |
| Public RPC URL                       | [https://sepolia.optimism.io](https://sepolia.optimism.io)                                      |
| Subblocks websocket URL <sup>3</sup> | [wss://op-sepolia-fb-ws.optimism.io/ws](wss://op-sepolia-fb-ws.optimism.io/ws)                  |
| Sequencer URL<sup>2</sup>            | [https://sepolia-sequencer.optimism.io](https://sepolia-sequencer.optimism.io)                  |
| Contract Addresses                   | Refer to the [Contract Addresses page](/op-mainnet/network-information/op-addresses#op-sepolia) |
| Connect Wallet                       | [Click here to connect your wallet to OP Sepolia](https://chainid.link?network=op-sepolia)      |

1. The "currency symbol" is required by some wallets like MetaMask.
2. The sequencer URL is write only.
3. Strictly rate-limited public URL. Please rely on Ethereum JSON RPC or reach out to the Optimism team for a more relaxed private endpoint.


# OP Mainnet Contract Addresses
Source: https://docs.optimism.io/op-mainnet/network-information/op-addresses

A comprehensive list of L1 and L2 contract addresses for OP Mainnet and OP Sepolia.

This page lists all contract addresses for OP Mainnet and OP Sepolia. For high-level details and source code, see the [Smart Contracts Overview](/op-stack/protocol/smart-contracts).

<Info>
  Contract addresses are automatically synced from the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/tree/main).
</Info>

## L2 Contract Addresses

### OP Mainnet

<L2ContractTable />

### OP Sepolia

<L2ContractTable />

## L1 Contract Addresses

### Ethereum Mainnet

<L1ContractTable />

### Ethereum Testnet (Sepolia)

<L1ContractTable />

## Shared Contracts

### Ethereum Mainnet

<SuperchainContractTable />

### Ethereum Testnet (Sepolia)

<SuperchainContractTable />

## Legacy Contracts

<Info>
  Legacy contracts are from previous versions of the OP Stack and are maintained for backwards compatibility.
</Info>

### OP Mainnet Legacy (L2)

<L2ContractTable />

### Ethereum Mainnet Legacy (L1)

<L1ContractTable />


# Snapshots
Source: https://docs.optimism.io/op-mainnet/network-information/snapshots

Find download links for data directories and database snapshots for running your own node.

# Node snapshots

This page contains download links for data directories and node snapshots.
State snapshots are pre-synced node data that let you start an OP Stack execution client from a recent chain state instead of replaying from genesis. You download the snapshot and run your node from it, which dramatically cuts initial sync time.
For step-by-step instructions on downloading, verifying, and extracting a snapshot, follow the [Restore a node from a snapshot guide](/node-operators/guides/management/restore-from-snapshot).

<Info>
  Data directories and node snapshots are **not required** in the following cases:

  * When using [snap sync](/node-operators/reference/consensus-layer-sync) with op-geth
  * When using [Nethermind](https://docs.nethermind.io/get-started/running-node/l2-networks#op-stack) (automatically handles snapshots)

  They are still required for archive nodes and in instances when you need to trace the entire chain with `op-reth` or `op-geth`.
</Info>

OP Mainnet underwent a large [database migration](https://web.archive.org/web/20240110231645/https://blog.oplabs.co/reproduce-bedrock-migration/) as part of the [Bedrock Upgrade](https://web.archive.org/web/20230608050602/https://blog.oplabs.co/introducing-optimism-bedrock/) in 2023.
Node operators using `op-reth` or `op-geth` must have a migrated OP Mainnet database to run an archival node.
Migrated OP Mainnet databases can be generated manually or pre-migrated databases can be downloaded from the links below.

## Available OP Mainnet Snapshots

<Info>
  Using [aria2](https://aria2.github.io/) to download snapshots can significantly speed up the download process.
</Info>

All snapshots for OP Mainnet can be found at the OP Labs managed [Data Directories](https://datadirs.optimism.io/) website.
All geth snapshots are configured for pebbleDB and the hash state scheme.

### Nethermind

[Nethermind](https://docs.nethermind.io/get-started/running-node/l2-networks#op-stack) automatically handles downloading and applying the necessary snapshots when you start the node. No manual snapshot download is required. The node will:

1. Start with an empty database
2. Automatically download the required ancient data
3. Apply the data and continue syncing

This process is fully automated and requires no additional configuration.
When you run `Nethermind` with the `-c op-mainnet` flag, it uses this configuration automatically.

## 3rd Party Snapshots

[Allnodes](https://www.allnodes.com) provides full node snapshots for OP Mainnet and Testnet. You can find them [here](https://www.publicnode.com/snapshots#optimism).
**Please note:** Allnodes is a 3rd party provider, and the Optimism Foundation hasn't verified the snapshots.


# Transaction finality on OP Mainnet
Source: https://docs.optimism.io/op-mainnet/network-information/transaction-finality

How long transactions take to reach each finality stage on OP Mainnet.

OP Mainnet follows the standard OP Stack finality model. A transaction reaches soft finality as soon as the Sequencer processes it (sub-second preconfirmation with Subblocks) and reaches hard finality, guaranteed by Ethereum, once the batch containing it is included in an Ethereum block and that block is finalized, typically 15 to 30 minutes after submission. For the full explanation of the journey from soft finality to hard finality, including the trust assumptions at each stage, see [Transaction finality](/op-stack/transactions/transaction-finality).

<Note>
  A common misconception is that transactions on OP Mainnet take 7 days to finalize. **This is incorrect.** Only *withdrawals* to Ethereum through the Standard Bridge wait 7 days; transaction finality itself typically takes about 15 to 30 minutes.
</Note>

## Typical timings on OP Mainnet

| Stage                              | What has happened                                                                    | Typical time after submission |
| ---------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------- |
| Subblock preconfirmation           | The Sequencer includes the transaction in a [subblock](/op-stack/features/subblocks) | \~200 milliseconds            |
| Soft finality (L2 block inclusion) | The transaction is in an L2 block distributed over the peer-to-peer network          | \~2 seconds                   |
| Data on Ethereum                   | A batch containing the transaction lands in an Ethereum block                        | A few minutes                 |
| Hard finality (finalized)          | Ethereum finalizes the block containing the batch                                    | \~15 to 30 minutes            |

These timings depend on Ethereum network conditions. The inclusion on Ethereum's blockchain depends on the batcher's submission cadence: OP Mainnet produces enough data to post batches every few minutes. The finalized stage then adds Ethereum's own time to finality, normally about two to three epochs (roughly 13 to 19 minutes) after the batch lands on Ethereum.

## Withdrawals to Ethereum

Withdrawals of ETH and ERC-20 tokens through the Standard Bridge wait a 7-day challenge period before the funds can be claimed on Ethereum. This is a property of the bridge's Fault Proof protection, not of transaction finality: the OP Mainnet chain itself does not take 7 days to finalize, and a successful challenge never reorgs the L2 chain. See [Withdrawal flow](/op-stack/bridging/withdrawal-flow) for how the challenge period works.


# Lost pre-regenesis data
Source: https://docs.optimism.io/op-mainnet/pre-bedrock-history/lost-pre-regenesis-data

Understand why some OP Mainnet transaction data from January to July 2021 cannot be fully recovered.

This page explains why part of OP Mainnet's earliest transaction history is permanently incomplete.
For how to look up the pre-regenesis history that *is* available, see [accessing pre-regenesis history](/op-mainnet/pre-bedrock-history/regenesis-history).

Because of the final regenesis on 11 November 2021, transactions from before that date are not part of the current blockchain and do not appear on [Etherscan](https://explorer.optimism.io/?utm_source=op-docs\&utm_medium=docs).
Most of that history remains queryable through external tools, but one early slice of it was lost.

## Lost data directories

Three data directories that were used by legacy L2Geth Sequencer instances
during the period of January 2021 to July 2021 had been errantly deleted during
an infra cleanup in August 2023.

These data directories contained information about the effects of transactions,
once executed. This information can only be obtained by properly executing the
transaction chain. The most valuable data within these directories was (1) events
emitted by smart contracts during each transaction and (2) the success state of
the transaction (whether or not the transaction executed or reverted). This
information is valuable for tracking things like ETH transfers or ERC-20 token
transfers. Without this we can still know the final set of balances but the
intermediate balances become opaque.

The transaction data for this period of time was published to a smart contract
on Ethereum called the [CanonicalTransactionChain](https://etherscan.io/address/0x5e4e65926ba27467555eb562121fac00d24e9dd2).
While it is theoretically possible to recover the data by downloading and
re-executing this chain of transactions from Ethereum, this is a labor intensive
and costly task that may not fully recover the data. The OP Labs team did
attempt data recovery efforts, including reaching out to several partners.

## Impact

No state, balances, or user assets were lost. Most of the impact is felt by data
providers who want complete data sets for analysis purposes and by individuals
who may want this information for tax purposes.

Since this was very early during the history of OP Mainnet there are relatively
few transactions in this period and this data is infrequently requested. Most
requests for this data came from individuals who needed access to this information
for the 2021 tax season though this is mostly no longer relevant today (many
people who needed this data already retrieved it).

## Going forward

We recognize the inconvenience this has caused some of our community and their
users and we're sorry for the frustrations. In an effort to prevent similar
situations from happening again in the future, we are evaluating and updating
existing processes and frameworks.


# Accessing pre-regenesis history
Source: https://docs.optimism.io/op-mainnet/pre-bedrock-history/regenesis-history

Learn how to access pre-regenesis history using the Etherscan CSV exporting tool.

This guide explains how to access transaction history between 23 June 2021 and the final regenesis.
Because of our final regenesis on 11 November 2021, older transactions are not part of the current blockchain and do not appear on [Etherscan](https://explorer.optimism.io/?utm_source=op-docs\&utm_medium=docs).

<Info>
  Event and transaction-status data from January to July 2021 was partially lost and cannot be fully recovered.
  See [lost pre-regenesis data](/op-mainnet/pre-bedrock-history/lost-pre-regenesis-data) for what is missing, why, and the impact.
</Info>

## Dune access

You can use a query on [Dune Analytics](https://dune.com), similar to [this query](https://dune.com/queries/354886?addr=%5Cx25E1c58040f27ECF20BBd4ca83a09290326896B3).
You have to log on with a Dune account, but their free tier is sufficient.

<Steps>
  <Step title="Browse to the [OVM1.0 User Address Transactions](https://dune.com/optimismfnd/OVM1.0-User-Address-Transactions) Dashboard on Dune." />

  <Step title="Enter the address you wish to search in the `Address` text box in the top left." />

  <Step title="Run the query (This requires log in. A free Dune account is sufficient)." />
</Steps>

Alternatively, to run custom queries in Dune, you can use the `optimism_legacy_ovm1` schema defined in [Dune Docs here](https://dune.com/docs/data-tables/?h=ovm#optimism).


# Cross-Domain Overview
Source: https://docs.optimism.io/op-stack/bridging/cross-domain

An overview of the lifecycle of an OP Stack cross-chain transaction, linking the detailed explainers for deposits, transaction flow, and withdrawals.

Cross-domain communication in the OP Stack involves moving assets and messages between L1 and L2. Key components, such as the Standard Bridge, the cross-domain messenger contracts, and the `OptimismPortal`, ensure these transactions are executed securely and transparently. This page summarizes the lifecycle of a cross-chain transaction in three flows and links the detailed explainer for each: deposit flow, transaction flow, and withdrawal flow.

## Deposit flow

A *deposit* is any L2 transaction triggered by a transaction or event on L1. An L1 account or contract (often the L1 Standard Bridge) sends a message through the `L1CrossDomainMessenger`, which passes it to the `OptimismPortal` contract on L1. The portal emits a `TransactionDeposited` event, `op-node` derives a deposit transaction from that event, and the `L2CrossDomainMessenger` relays the call to its target on L2. For the step-by-step walkthrough, see [Deposit flow](/op-stack/bridging/deposit-flow).

## Transaction flow

Every L2 transaction has two requirements: its data must be written to L1 (done in compressed batches by `op-batcher`), and it must be executed by the execution client to update the L2 state, after which `op-proposer` posts a commitment to the resulting state to L1. For the step-by-step walkthrough, see [Transaction flow](/op-stack/transactions/transaction-flow); for when a transaction can be relied on as irreversible, see [Transaction finality](/op-stack/transactions/transaction-finality).

## Withdrawal flow

A *withdrawal* is a transaction sent from L2 back to L1. It requires three user transactions: a withdrawal initiating transaction on L2, recorded by the `L2ToL1MessagePasser`; a withdrawal proving transaction on L1, which proves the withdrawal against an output root; and, once the fault challenge period (7 days on mainnet, shorter on test networks) has passed, a withdrawal finalizing transaction on L1 that executes the withdrawal. For the step-by-step walkthrough, see [Withdrawal flow](/op-stack/bridging/withdrawal-flow).


# Deposit flow
Source: https://docs.optimism.io/op-stack/bridging/deposit-flow

Learn the deposit flow process for L2 deposit transactions, triggered by events on L1.

<Info>
  **Learn the OP Stack — stop 8 of 13.**
  You've followed a transaction that starts and ends on L2. This page
  adds the first cross-layer direction: how a transaction triggered on L1
  becomes an L2 transaction. When you're done, continue to
  [Withdrawal flow](/op-stack/bridging/withdrawal-flow).
</Info>

This page explains the deposit flow process for L2 deposit transactions, triggered by transactions or events on L1. In Optimism terminology, "*deposit transaction*" refers to any L2 transaction that is triggered by a transaction or event on L1.

The process is somewhat similar to the way [most networking stacks work](https://en.wikipedia.org/wiki/Encapsulation_\(networking\)).
Information is encapsulated in lower layer packets on the sending side and then retrieved and used by those layers on the receiving side while going up the stack to the receiving application.

<img alt="Deposit Flow Diagram." />

## L1 processing

1. An L1 entity, either a smart contract or an externally owned account (EOA), sends a deposit transaction to [`L1CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol), using [`sendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L191-L211).
   This function accepts three parameters:

   * `_target`, target address on L2.
   * `_message`, the L2 transaction's calldata, formatted as per the [ABI](https://docs.soliditylang.org/en/v0.8.19/abi-spec.html) of the target account.
   * `_minGasLimit`, the minimum gas limit allowed for the transaction on L2. Note that this is a *minimum* and the actual amount provided on L2 may be higher (but never lower) than the specified gas limit. The actual amount provided on L2 is often higher because the portal contract on L2 performs some processing before submitting the call to `_target`.

2. The L1 cross domain messenger calls [its own `_sendMessage` function](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol#L83-L91).
   It uses these parameters:

   * `_to`, the destination address, is the messenger on the other side.
     In the case of deposits, this is always [`0x4200000000000000000000000000000000000007`](https://testnet-explorer.optimism.io/address/0x4200000000000000000000000000000000000007).
   * `_gasLimit`, the gas limit.
     This value is calculated using [the `baseGas` function](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L357-L396).
   * `_value`, the ETH that is sent with the message.
     This amount is taken from the transaction value.
   * `_data`, the calldata for the call on L2 that is needed to relay the message.
     This is an [ABI encoded](https://docs.soliditylang.org/en/v0.8.19/abi-spec.html) call to [`relayMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L222-L320).

3. [`_sendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/L1CrossDomainMessenger.sol#L83-L91) calls the portal's [`depositTransaction` function](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684-L738).

   Note that other contracts can also call [`depositTransaction`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684-L738) directly.
   However, doing so bypasses certain safeguards, so in most cases it's a bad idea.

4. [The `depositTransaction` function](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684-L738) runs a few sanity checks, and then emits a [`TransactionDeposited`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L149-L155) event.

## L2 processing

1. The `op-node` component [looks for `TransactionDeposited` events on L1](https://github.com/ethereum-optimism/optimism/blob/develop/op-node/rollup/derive/deposits.go#L15-L34).
   If it sees any such events, it [parses](https://github.com/ethereum-optimism/optimism/blob/develop/op-node/rollup/derive/deposit_log.go) them.

2. Next, `op-node` [converts](https://github.com/ethereum-optimism/optimism/blob/develop/op-node/rollup/derive/deposits.go#L36-L52) those `TransactionDeposited` events into [deposit transactions](https://specs.optimism.io/protocol/deposits.html?utm_source=op-docs\&utm_medium=docs#user-deposited-transactions).

3. In most cases, user deposit transactions call the [`relayMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L222-L320) function of [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L22).

4. `relayMessage` runs a few sanity checks and then, if everything is good, [calls the real target contract with the relayed calldata](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L298).

## Denial of service (DoS) prevention

As with all other L1 transactions, the L1 costs of a deposit are borne by the transaction's originator.
However, the L2 processing of the transaction is performed by the Optimism nodes.
If there were no cost attached, an attacker could submit a transaction that had high execution costs on L2, and that way perform a denial of service attack.

To avoid this DoS vector, [`depositTransaction`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684-L738), and the functions that call it, require a gas limit parameter.
[This gas limit is encoded into the `TransactionDeposited` event](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L733-L737), and used as the gas limit for the user deposit transaction on L2.

This L2 gas is paid for by burning L1 gas [here](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/ResourceMetering.sol#L149).

## Replaying failed deposits

Deposit transactions can fail on L2 — usually because not enough gas was provided, or the L2 state did not allow the transaction to succeed. When that happens the message is not lost: `L2CrossDomainMessenger` records it as a failed message, and you can replay it later, optionally with more gas.

To walk through triggering a failed deposit and replaying it end to end, follow the tutorial [Replaying a failed deposit](/app-developers/tutorials/bridging/replay-failed-deposit).


# Withdrawal flow
Source: https://docs.optimism.io/op-stack/bridging/withdrawal-flow

Learn the withdrawal flow process for transactions sent from L2 to L1.

<Info>
  **Learn the OP Stack — stop 9 of 13.**
  You know how transactions enter L2 from L1. This page adds the return
  direction: the initiate, prove, and finalize steps a withdrawal takes
  back to L1. When you're done, continue to
  [Submitting transactions from L1](/app-developers/tutorials/bridging/cross-dom-bridge-eth).
</Info>

In Optimism terminology, a *withdrawal* is a transaction sent from L2 (OP Mainnet, OP Sepolia etc.) to L1 (Ethereum mainnet, Sepolia, etc.).

Withdrawals require the user to submit three transactions:

1. **Withdrawal initiating transaction**, which the user submits on L2.
2. **Withdrawal proving transaction**, which the user submits on L1 to prove that the withdrawal is legitimate (based on a Merkle-Patricia trie root that commits to the state of the `L2ToL1MessagePasser`'s storage on L2)
3. **Withdrawal finalizing transaction**, which the user submits on L1 after the fault challenge period has passed, to actually run the transaction on L1.

You can read the full [withdrawal specifications here](https://specs.optimism.io/protocol/withdrawals.html?utm_source=op-docs\&utm_medium=docs).

<Info>
  You can see an example of how to implement this process [in the bridging tutorials](/app-developers/tutorials/bridging/cross-dom-bridge-erc20).
</Info>

## Withdrawal initiating transaction

1. On L2, a user, either an externally owned account (EOA) directly or a contract acting on behalf of an EOA, calls the [`sendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol#L191) function of the [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L22) contract.

   This function accepts three parameters:

   * `_target`, target address on L1.
   * `_message`, the L1 transaction's calldata, formatted as per the [ABI](https://docs.soliditylang.org/en/v0.8.19/abi-spec.html) of the target address.
   * `_minGasLimit`, The minimum amount of gas that the withdrawal finalizing transaction can provide to the withdrawal transaction. This is enforced by the `SafeCall` library, and if the minimum amount of gas cannot be met at the time of the external call from the `OptimismPortal` -> `L1CrossDomainMessenger`, the finalization transaction will revert to allow for re-attempting with a higher gas limit. In order to account for the gas consumed in the `L1CrossDomainMessenger.relayMessage` function's execution, extra gas will be added on top of the `_minGasLimit` value by the `CrossDomainMessenger.baseGas` function when `sendMessage` is called on L2.

2. `sendMessage` is a generic function that is used in both cross domain messengers. It calls [`_sendMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L47), which is specific to [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L22).

3. `_sendMessage` calls [`initiateWithdrawal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol#L78) on [`L2ToL1MessagePasser`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol#L19). This function calculates the hash of the raw withdrawal fields. It then marks that hash as a sent message in [`sentMessages`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol#L27) and emits the fields with the hash in a [`MessagePassed`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL1MessagePasser.sol#L40) event.

   The raw withdrawal fields are:

   * `nonce` - A single use value to prevent two otherwise identical withdrawals from hashing to the same value
   * `sender` - The L2 address that initiated the transfer, typically [`L2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2CrossDomainMessenger.sol#L22)
   * `target` - The L1 target address
   * `value` - The amount of WEI transferred by this transaction
   * `gasLimit` - Gas limit for the transaction, the system guarantees that at least this amount of gas will be available to the transaction on L1. Note that if the gas limit is not enough, or if the L1 finalizing transaction does not have enough gas to provide that gas limit, the finalizing transaction returns a failure, it does not revert.
   * `data` - The calldata for the withdrawal transaction

4. When `op-proposer`proposes a new `output`, the output proposal includes the [output root](https://specs.optimism.io/glossary.html?utm_source=op-docs\&utm_medium=docs#l2-output-root), provided as part of the block by `op-node`.
   This new output root commits to the state of the `sentMessages` mapping in the `L2ToL1MessagePasser` contract's storage on L2, and it can be used to prove the presence of a pending withdrawal within it.

## Withdrawal proving transaction

Once an output root that includes the `MessagePassed` event is published to L1, the next step is to prove that the message hash really is in L2. Typically this is done by viem.

### Offchain processing

1. A user calls viem's `proveWithdrawal()` function with the withdrawal transaction receipt. This function internally handles the preparation of the proving transaction parameters.

2. To get the withdrawal details from the L2 transaction, viem uses the `getWithdrawals()` function which extracts the raw withdrawal fields from the `MessagePassed` event in the transaction receipt.

3. To get the proof, viem uses the withdrawal proving functionality to generate the necessary Merkle proof.

4. Finally, viem calls [`OptimismPortal.proveWithdrawalTransaction()`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L375) on L1.

### Onchain processing

[`OptimismPortal.proveWithdrawalTransaction()`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L375) runs a few sanity checks. Then it verifies that in `L2ToL1MessagePasser.sentMessages` on L2 the hash for the withdrawal is turned on, using a Merkle proof against the output root claimed by a fault dispute game. If everything checks out, it writes the dispute game and the timestamp of the proof in `provenWithdrawals` and emits an event. A withdrawal can be proven more than once (for example, against a different dispute game if the original game turns out to be invalid), and re-proving resets the proof timer.

The next step is to wait the fault challenge period (7 days on mainnet, shorter on test networks), to ensure that the L2 output root used in the proof is legitimate, and that the proof itself is legitimate and not a hack.

## Withdrawal finalizing transaction

Finally, once the fault challenge period passes, the withdrawal can be finalized and executed on L1.

To do so, a user, either an externally owned account (EOA) directly or a contract acting on behalf of an EOA, calls the [`finalizeWithdrawalTransaction`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L481) function of the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L37) contract.

## Expected internal reverts in withdrawal transactions

During the withdrawal process, users may observe internal reverts when viewing the transaction on **Etherscan**. This is a common point of confusion but is expected behavior.

These internal reverts often show up in yellow on the Etherscan UI and may cause concern that something went wrong with the transaction. However, these reverts occur due to the non-standard proxy used in Optimism, specifically the **Chugsplash Proxy**. The Chugsplash Proxy sometimes triggers internal calls that revert as part of the designed flow of the withdrawal process.

### Why do these reverts happen?

The Chugsplash Proxy operates differently than standard proxies. During a withdrawal transaction, it may trigger internal contract calls that result in reverts, but these reverts do not indicate that the withdrawal has failed. Instead, they are part of the internal logic of the system and are expected in certain scenarios.

### Key takeaways:

* **Internal Reverts Are Expected**: These reverts are part of the normal operation of the Chugsplash Proxy during withdrawal transactions and do not represent an error.
* **No Cause for Concern**: Although Etherscan highlights these reverts, they do not affect the final success of the transaction.
* **User Assurance**: If you encounter these reverts during a withdrawal transaction, rest assured that the withdrawal will still finalize as expected.

### Offchain processing

1. A user calls viem's `finalizeWithdrawal()` function with the withdrawal transaction receipt.
   This function internally handles the preparation of the finalization transaction parameters.

2. To get the withdrawal details from the L2 transaction, viem uses the `getWithdrawals()` function which extracts the raw withdrawal fields from the `MessagePassed` event in the transaction receipt.

3. Finally, viem calls [`OptimismPortal.finalizeWithdrawalTransaction()`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L481-L483) on L1.

### Onchain processing

1. [`OptimismPortal.finalizeWithdrawalTransaction()`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L481-L483) runs several checks. The interesting ones are:

   * [Verify that the withdrawal has already been proven](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L647-L652).
   * [Verify that the proof was submitted long enough ago that the proof maturity delay has already passed](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L662-L665).
   * [Verify that the dispute game the withdrawal was proven against resolved in favor of the proposed output root, and that its claim has not since been invalidated](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L667-L670).
   * [Verify that the withdrawal has not been finalized before to prevent replay attacks](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L642-L645).

   If any of these checks fail, the transaction reverts.

2. Mark the withdrawal as finalized in `finalizedWithdrawals`.

3. Run the actual withdrawal transaction (call the `target` contract with the calldata in `data`).

4. Emit a [`WithdrawalFinalized`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L173) event.


# cannon
Source: https://docs.optimism.io/op-stack/components/cannon

Canonical hub for cannon, the OP Stack fault proof virtual machine — what it does, who runs it, and where its guides, releases, source, and spec live.

cannon is the OP Stack's fault proof virtual machine (FPVM): an onchain MIPS
instruction emulator that lets a disputed L2 state transition be re-executed,
one instruction at a time, on L1.

## Overview

cannon has two halves that must behave identically:

* **Onchain `MIPS64.sol`** — a Solidity implementation of big-endian 64-bit
  MIPS (MIPS64r1) instruction execution, used to verify a single disputed
  instruction on L1.
* **Offchain `mipsevm`** — an instrumented emulator of the same
  instruction set that runs the full program and produces the witness data
  needed to repeat any one step onchain.

The program cannon executes is the fault proof program,
[kona-client](/releases/kona-client), compiled to a MIPS ELF binary; the
[kona-host](/releases/kona-host) binary runs alongside as the preimage
server that supplies chain data during execution. Together they make fault
disputes resolvable: participants bisect an execution trace down to a single
MIPS instruction, and that one instruction is proven onchain.

**Who runs it:** dispute game participants, not everyday node operators.
[op-challenger](/op-stack/fault-proofs/challenger) invokes the cannon binary
automatically when a fault dispute reaches the execution-trace stage, and
chain operators build cannon prestates when configuring permissionless fault
proofs. For how cannon fits into the dispute game, see the
[fault proofs explainer](/op-stack/fault-proofs/explainer) and the
[Cannon](/op-stack/fault-proofs/cannon) and
[MIPS](/op-stack/fault-proofs/mips) deep-dive pages.

## Get started

* [Cannon usage](https://github.com/ethereum-optimism/optimism/tree/develop/cannon#usage)
  — the in-repo README walks through building cannon, loading a kona-client
  ELF into an initial VM state, and running the emulator.

## How-tos

* [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate)
  — build and verify the cannon prestate of kona-client that op-challenger
  runs at dispute time.
* [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate)
  — the same, for chains not yet in the public Superchain Registry.

## Configuration & flags reference

* cannon has no configuration reference page on this site yet; it is
  configured entirely through CLI flags, documented by `cannon --help` and
  the [in-repo README](https://github.com/ethereum-optimism/optimism/tree/develop/cannon#usage).

## Releases

* [cannon release tags on GitHub](https://github.com/ethereum-optimism/optimism/releases?q=cannon%2Fv\&expanded=false)
  — cannon does not have a page under [Releases](/releases) yet.

## Source & spec links

* [Source: `cannon/`](https://github.com/ethereum-optimism/optimism/tree/develop/cannon)
  in the Optimism monorepo; the onchain contracts live in
  [`packages/contracts-bedrock/src/cannon`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/src/cannon).
* [Cannon overview docs](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/docs/README.md)
  — in-repo documentation of the onchain/offchain split and the witness
  data (packed state, memory proofs, preimage data).
* [Cannon fault proof VM specification](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html)
  — the normative definition of the VM.


# Stack Components
Source: https://docs.optimism.io/op-stack/components/index

One canonical hub page per OP Stack component, grouped by protocol role.

This section gives every OP Stack component exactly one identity page — its
**hub** — so "where do I find docs for component X" always has the same
answer. Each hub follows the same
[skeleton](/op-stack/contribute/component-hub-template): what the component
is, who runs it, where to start, and where its guides, configuration
reference, releases, source, and spec live.

Components are grouped by their role in the protocol. For how these roles fit
together conceptually — data availability, sequencing, derivation, execution,
settlement — see the [OP Stack components](/op-stack/protocol/components)
explanation. For release history across all components, see
[Releases](/releases).

Hubs are shipping in reviewed batches. Components without a hub yet are
listed with their release history; their hub pages follow.

## Sequencing

Producing L2 blocks and making their data available.

| Component    | What it does                                                | Hub                                      | Releases                           |
| ------------ | ----------------------------------------------------------- | ---------------------------------------- | ---------------------------------- |
| op-batcher   | Posts L2 transaction batches to the data availability layer | [Hub](/op-stack/components/op-batcher)   | [Releases](/releases/op-batcher)   |
| op-conductor | High-availability sequencer coordination service            | [Hub](/op-stack/components/op-conductor) | [Releases](/releases/op-conductor) |

## Derivation & execution

Deriving the canonical L2 chain from the data availability layer and
executing its blocks.

| Component | What it does                                         | Hub                                   | Releases                        |
| --------- | ---------------------------------------------------- | ------------------------------------- | ------------------------------- |
| op-node   | OP Stack consensus-layer (rollup node) client, in Go | [Hub](/op-stack/components/op-node)   | [Releases](/releases/op-node)   |
| kona-node | Rust implementation of the OP Stack rollup node      | [Hub](/op-stack/components/kona-node) | [Releases](/releases/kona-node) |
| op-reth   | OP Stack execution-layer client built on Reth        | [Hub](/op-stack/components/op-reth)   | [Releases](/releases/op-reth)   |

## Settlement & proofs

Proposing L2 state to L1 and proving its validity.

| Component     | What it does                                                             | Hub                                       | Releases                                                                                            |
| ------------- | ------------------------------------------------------------------------ | ----------------------------------------- | --------------------------------------------------------------------------------------------------- |
| op-proposer   | Proposes L2 output roots to L1                                           | [Hub](/op-stack/components/op-proposer)   | [Releases](/releases/op-proposer)                                                                   |
| op-challenger | Dispute game challenge agent                                             | [Hub](/op-stack/components/op-challenger) | [Releases](/releases/op-challenger)                                                                 |
| cannon        | Onchain MIPS instruction emulator — the fault proof VM                   | [Hub](/op-stack/components/cannon)        | [Release tags](https://github.com/ethereum-optimism/optimism/releases?q=cannon%2Fv\&expanded=false) |
| kona-client   | Fault proof program (client) that executes the OP Stack state transition | [Hub](/op-stack/components/kona-client)   | [Releases](/releases/kona-client)                                                                   |
| kona-host     | Fault proof host that serves preimage data to kona-client                | [Hub](/op-stack/components/kona-host)     | [Releases](/releases/kona-host)                                                                     |
| op-contracts  | OP Stack L1 and L2 smart contracts                                       | [Hub](/op-stack/components/op-contracts)  | [Releases](/releases/op-contracts)                                                                  |

## Deployment & infrastructure

Deploying chains and operating the infrastructure around them.

| Component   | What it does                               | Hub                                     | Releases                          |
| ----------- | ------------------------------------------ | --------------------------------------- | --------------------------------- |
| op-deployer | OP Stack chain deployment and upgrade tool | [Hub](/op-stack/components/op-deployer) | [Releases](/releases/op-deployer) |
| proxyd      | RPC request router and proxy               | [Hub](/op-stack/components/proxyd)      | [Releases](/releases/proxyd)      |


# kona-client
Source: https://docs.optimism.io/op-stack/components/kona-client

Canonical hub for kona-client, the OP Stack fault proof program, covering what it does, who runs it, and where its guides, releases, source, and spec live.

kona-client is the OP Stack's fault proof program: a Rust program, built as
part of the [Kona](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona) project, that executes the L2
state transition so a disputed output root can be verified inside a fault
proof VM.

## Overview

kona-client derives the disputed span of the L2 chain from L1 data,
re-executes its blocks, and checks the result against the claimed L2 output
root. It runs sandboxed, with no network access: every piece of chain data it
consumes (L1 headers, transactions, receipts, blobs, L2 state) arrives
through the preimage oracle ABI, served by its companion host process,
[kona-host](/op-stack/components/kona-host). It is built so that the same
inputs produce not only the same outputs but the same execution trace.

That determinism is what makes fault disputes resolvable. For dispute games,
kona-client is compiled to a big-endian 64-bit MIPS (MIPS64) ELF binary and
run inside the [cannon](/op-stack/components/cannon) FPVM; this pairing backs
the `CANNON_KONA` dispute game (game type 8), the respected game type for
permissionless fault proofs since [Upgrade 19](/notices/archive/upgrade-19). Because
every honest participant computes the identical execution trace, a dispute
can be bisected down to a single MIPS instruction and that one instruction
proven on L1.

kona-client succeeded op-program, the Go fault proof program behind the
legacy `CANNON` (game type 0) and `PERMISSIONED_CANNON` (game type 1) games;
op-program has reached end of support (see
[End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation)),
and the kona binaries are the maintained fault proof program today.

**Who runs it:** nobody invokes it by hand in production.
[op-challenger](/op-stack/fault-proofs/challenger) runs cannon when a fault
dispute reaches the execution-trace stage, and cannon executes the
kona-client ELF committed to by the chain's absolute prestate. Chain
operators pin that prestate when configuring fault proofs; developers can
also run kona-client natively through kona-host for testing.

## Get started

* [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate):
  build and verify the absolute prestate, the onchain commitment to a
  specific kona-client build, whose preimage op-challenger runs at dispute
  time.

## How-tos

* [Generating a custom kona-client absolute prestate](/chain-operators/tutorials/kona-custom-prestate):
  build a kona-client that embeds a chain configuration not yet in the
  public Superchain Registry.
* [Switch to Kona Proofs](/chain-operators/guides/features/switching-to-kona-proofs):
  move an existing chain's respected game type to the Kona-based fault
  proofs.
* [Run a fault-proof challenger](/use-cases/run-a-fault-proof-challenger):
  stand up the op-challenger deployment that exercises kona-client, from
  prestate selection through configuration and monitoring.

## Configuration & flags reference

* kona-client has no configuration reference page and no operator-facing
  flags. Its inputs (the L1 head, the disputed output roots, the chain
  configuration) arrive as bootstrap data over the preimage oracle, as
  defined in the
  [fault proof program specification](https://specs.optimism.io/fault-proof/index.html#fault-proof-program).

## Releases

* [kona-client release history](/releases/kona-client)

## Source & spec links

* [Source: `rust/kona/bin/client`](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/bin/client)
  in the Optimism monorepo.
* [Fault proof program development](/op-stack/fault-proofs/kona/fpp-dev/intro): how
  fault proof programs like kona-client are structured
  (prologue, execution, epilogue) and built on the Kona SDK.
* [Fault proof program specification](https://specs.optimism.io/fault-proof/index.html#fault-proof-program):
  the normative definition of the program's prologue, main content, and
  epilogue.


# kona-host
Source: https://docs.optimism.io/op-stack/components/kona-host

Canonical hub for kona-host, the fault proof host that serves preimage data to kona-client, covering what it does, who runs it, and where its guides, releases, source, and spec live.

kona-host is the OP Stack's fault proof host program: a native Rust binary,
built as part of the [Kona](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona) project, that runs the
preimage server supplying chain data to
[kona-client](/op-stack/components/kona-client) while it executes.

## Overview

kona-client runs with no network access, so it cannot fetch chain data
itself: everything it reads arrives as a preimage requested by key over the
preimage oracle ABI. kona-host is the other end of that channel. It fetches
the requested data (L1 headers, transactions, receipts, blobs, L2 state)
from its configured L1, L1 beacon, and L2 endpoints, responds to the
client's hints so the right preimages are ready when asked for, and serves
them back. Without it, the
fault proof program would have no way to learn the chain state it is asked
to verify.

kona-host runs in `single` mode (one pre-interop chain) or `super` mode (an
interop superchain cluster), and its preimage server starts in one of two
ways: `server` mode, where it only serves preimages to a client program run
by an FPVM (when [cannon](/op-stack/components/cannon) executes kona-client,
it launches kona-host as a subprocess, passing the host command after a `--`
separator on `cannon run`), and `native` mode, where kona-host runs
kona-client itself in a native process, useful for witness generation and
testing.

**Who runs it:** dispute game participants, indirectly:
[op-challenger](/op-stack/fault-proofs/challenger)'s `--cannon-kona-server`
flag points at a kona-host binary, which cannon launches when a fault
dispute reaches the execution-trace stage. Developers also run it directly
in native mode to execute kona-client without an FPVM.

## Get started

* [kona-host usage](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/bin/host#usage):
  the in-repo README documents the host modes, the preimage server modes,
  and the CLI surface.

## How-tos

* [Run a fault-proof challenger](/use-cases/run-a-fault-proof-challenger):
  stand up an op-challenger deployment, including pointing
  `--cannon-kona-server` at a kona-host build that matches the configured
  prestate.
* [Spin up challenger](/chain-operators/tutorials/create-l2-rollup/op-challenger-setup):
  configure op-challenger for a new chain, including where to get the
  kona-host binary it needs.

## Configuration & flags reference

* kona-host has no configuration reference page on this site yet; it is
  configured entirely through CLI flags, documented by `kona-host --help`
  and the
  [in-repo README](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/bin/host#usage).

## Releases

* [kona-host release history](/releases/kona-host)

## Source & spec links

* [Source: `rust/kona/bin/host`](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/bin/host)
  in the Optimism monorepo.
* [Pre-image oracle specification](https://specs.optimism.io/fault-proof/index.html#pre-image-oracle):
  the normative definition of the ABI kona-host implements, including the
  preimage key types, hinting, and bootstrapping.


# kona-node
Source: https://docs.optimism.io/op-stack/components/kona-node

Canonical hub for kona-node, the Rust implementation of the OP Stack rollup node, with links to its guides, reference, releases, source, and spec.

kona-node is the Rust implementation of the OP Stack consensus-layer (rollup
node) client, built as part of the [Kona](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona) project.

## Overview

kona-node performs the same protocol role as [op-node](/op-stack/protocol/components):
it reads batch data and deposits from the data availability layer, derives the
canonical L2 chain, and drives an execution-layer client (such as
[op-reth](/node-operators/guides/configuration/execution-clients)) through the
Engine API. It also participates in the unsafe-block gossip network and can
run in sequencer mode.

It exists to bring client diversity to the OP Stack: with independent rollup
node implementations, a bug in one client cannot take down every node on a
chain. Kona is in active development and kona-node should be considered
experimental.

**Who runs it:** node operators, as the consensus-layer half of a node stack,
paired with an execution client. Chain operators can also run it in sequencer
mode.

## Get started

* [Install kona-node](/node-operators/kona-node/install/overview): pre-built
  binaries, Docker images, or building from source. Check the
  [system requirements](/node-operators/kona-node/requirements) first.

## How-tos

* [Run a node](/node-operators/kona-node/run/overview): using the
  [binary](/node-operators/kona-node/run/binary) or the
  [Docker recipe](/node-operators/kona-node/run/docker), including
  [how sync works](/node-operators/kona-node/run/mechanics) and
  [RPC trust considerations](/node-operators/kona-node/run/rpc-trust).
* [Run a sequencer node](/node-operators/kona-node/run/sequencer): flags,
  key management, and example configurations for sequencer mode.
* [Monitoring](/node-operators/kona-node/monitoring): logging, Prometheus
  metrics, and Grafana dashboards.

## Configuration & flags reference

* [kona-node CLI reference](/node-operators/kona-node/configuration): every
  CLI flag and environment variable for the `node` subcommand, plus default
  ports and default runtime behavior.
* [`kona-node` subcommands](/node-operators/kona-node/subcommands): the
  other subcommands the binary ships.
* [JSON-RPC reference](/node-operators/kona-node/rpc/overview): the P2P,
  rollup, and admin RPC namespaces.

## Releases

* [kona-node release history](/releases/kona-node)

## Source & spec links

* [Source: `rust/kona/bin/node`](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona/bin/node)
  in the Optimism monorepo.
* [Kona source and README](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona): the Kona
  project in the Optimism monorepo; the node's
  [design internals](/node-operators/kona-node/design/intro) are documented
  beside the operator guides.
* [Rollup node specification](https://specs.optimism.io/protocol/rollup-node.html):
  the normative definition of the rollup node's role.


# op-batcher
Source: https://docs.optimism.io/op-stack/components/op-batcher

Canonical hub for op-batcher, the OP Stack batch submitter — what it does, who runs it, and where its guides, reference, releases, source, and spec live.

op-batcher is the OP Stack's batch submitter: the service that makes an L2
chain's transaction data available by posting it to the data availability
layer.

## Overview

op-batcher reads unsafe blocks from the sequencer, compresses them into
channels, splits the channels into frames, and submits those frames to the
data availability layer — as Ethereum calldata or blob transactions, or via
an [Alt-DA](/op-stack/features/experimental/alt-da-mode) layer. It can also
select between calldata and blobs automatically based on current L1 prices.

It exists because an OP Stack chain is *derived* from the data availability
layer: until op-batcher posts a block's data, verifier nodes cannot derive it
and the chain's safe head does not advance. Batches must also land within the
chain's sequencing window — see the
[batcher guide](/chain-operators/guides/configuration/batcher) for the policy
constraints.

**Who runs it:** the chain operator, as part of the sequencer's
infrastructure, submitting from the chain's batch submitter address. During
data availability backlogs, op-batcher can also instruct the block builder to
throttle how much DA-consuming data new L2 blocks include.

## Get started

* [Spin up batcher](/chain-operators/tutorials/create-l2-rollup/op-batcher-setup)
  — set up and configure op-batcher as part of standing up an OP Stack
  chain.

## How-tos

* [Configure the batcher](/chain-operators/guides/configuration/batcher):
  batcher policy, cost tuning, multi-blob transactions, and sequencer
  throttling.
* [Post batch data as blobs](/chain-operators/guides/features/blobs): switch
  the chain's data availability type to blobs.
* [Enable span batches](/chain-operators/guides/features/enable-span-batches):
  configure the batch type on op-batcher.
* [How to run an Alt-DA mode chain](/chain-operators/guides/features/alt-da-mode-guide):
  post data to an Alt-DA layer instead of Ethereum.

## Configuration & flags reference

* [Batcher configuration reference](/chain-operators/reference/batcher-configuration)
  — every CLI flag and environment variable, with defaults. The reference
  page states the release it was written against.

## Releases

* [op-batcher release history](/releases/op-batcher)

## Source & spec links

* [Source: `op-batcher/`](https://github.com/ethereum-optimism/optimism/tree/develop/op-batcher)
  in the Optimism monorepo — its [README](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/readme.md)
  documents the internal architecture and design principles.
* [DA throttling deep-dive](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/throttling.md)
  — in-repo documentation of the throttling controllers (step, linear,
  quadratic, and PID), their configuration, and runtime management over
  RPC.
* [Batch submitter specification](https://specs.optimism.io/protocol/batcher.html)
  — the normative definition of the batcher's role.


# op-challenger
Source: https://docs.optimism.io/op-stack/components/op-challenger

Canonical hub for op-challenger, the OP Stack dispute game challenge service, covering what it does, who runs it, and where its guides, releases, source, and spec live.

op-challenger is the OP Stack's dispute game challenge service
that monitors fault dispute games on L1, defends valid output proposals, and
challenges invalid ones.

## Overview

op-challenger watches the games created through the `DisputeGameFactory` (on
a fault proof chain, every output proposal is a dispute game). Checking each
claim against a trusted, synced rollup node, it defends proposals it agrees
with, posts counterclaims against those it does not, resolves claims and
games once the game clocks expire, and claims the bonds paid out to it. When
a dispute is bisected down to a single VM instruction, op-challenger runs the
fault proof VM, [cannon](/op-stack/components/cannon), executing kona-client
with kona-host serving preimage data, to prove that instruction onchain. For
a deeper walkthrough of this behavior, see the
[OP-Challenger explainer](/op-stack/fault-proofs/challenger).

It exists because fault proofs only secure withdrawals if someone actually
responds to invalid claims before the game clocks run out. op-challenger is
the implementation of the dispute protocol's *honest actor*: it defends the
chain by ensuring games resolve to the correct state, which is what the
`OptimismPortal` ultimately trusts for withdrawals.

**Who runs it:** chain operators run at least one challenger to defend their
chain, and on a permissionless fault proof chain anyone can run one. A
challenger needs a synced, trusted rollup node to verify claims against, and
a funded account to post bonds from.

## Get started

* [Spin up challenger](/chain-operators/tutorials/create-l2-rollup/op-challenger-setup):
  set up and configure op-challenger as part of standing up an OP Stack
  chain.

## How-tos

* [How to configure challenger for your chain](/chain-operators/guides/configuration/op-challenger-config-guide):
  the configuration options that matter in production.
* [Run a fault-proof challenger](/use-cases/run-a-fault-proof-challenger):
  the whole operational path in one pass: bond budgeting, prestate
  selection, infrastructure, configuration, and monitoring.
* [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate):
  build and verify the prestate op-challenger runs at dispute time.
* [Migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless):
  upgrade and test op-challenger as part of the migration.

## Configuration & flags reference

* [Challenger configuration reference](/chain-operators/reference/challenger-configuration):
  every CLI flag and environment variable, with flag tables generated from
  the op-challenger release named on the page. The
  [configuration guide](/chain-operators/guides/configuration/op-challenger-config-guide)
  above covers the production-relevant options.

## Releases

* [op-challenger release history](/releases/op-challenger)

## Source & spec links

* [Source: `op-challenger/`](https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger)
  in the Optimism monorepo; its
  [README](https://github.com/ethereum-optimism/optimism/blob/develop/op-challenger/README.md)
  documents the quickstart and the manual-testing subcommands
  (`create-game`, `move`, `resolve`, `list-games`, `run-trace`, and more).
* [Honest challenger specification](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html):
  the normative behavior op-challenger implements.
* [Fault dispute game specification](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html):
  the game it plays.


# op-conductor
Source: https://docs.optimism.io/op-stack/components/op-conductor

Canonical hub for op-conductor, the high-availability sequencer coordination service, covering what it does, who runs it, and where its guides, reference, releases, and source live.

op-conductor is the OP Stack's high-availability sequencer coordination
service: it manages a cluster of sequencers so that exactly one leads the
chain at a time and block production survives single-node failures.

## Overview

op-conductor runs alongside each sequencer in a multi-node cluster, typically
three nodes spread across regions or availability zones. It participates in a
Raft consensus layer to elect the leader and to store the latest unsafe
block, monitors its sequencer's health, starts or stops sequencing based on
leadership and health, and serves admin RPCs for manual recovery scenarios.
The design provides three guarantees: no unsafe reorgs, no unsafe head stall
during a network partition, and continued uptime with no more than one node
failure in a standard three-node setup. For how this works in detail, see the
[OP Conductor explainer](/chain-operators/tools/op-conductor).

It exists because a single sequencer is a single point of failure: without
coordination, a crashed sequencer halts block production, and a naive
failover can produce two active sequencers or reorg unsafe blocks.
op-conductor is not Byzantine fault tolerant: it assumes all participating
nodes are honest, performs no authentication or authorization of RPC
requests, and is intended to run inside a private network.

**Who runs it:** chain operators running a high-availability sequencer setup,
with one conductor instance per sequencer node. The rollup node's sequencer
mode integrates with it on both op-node (`--conductor.enabled` and
`--conductor.rpc`) and kona-node (`--conductor.rpc`). Chains running a single
sequencer do not need it.

## Get started

* [Setup](/chain-operators/tools/op-conductor/setup): add op-conductor to
  an existing multi-sequencer OP Stack network without downtime.

## How-tos

* [Launch a chain with fault proofs and HA sequencing](/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing):
  the whole production path in one pass, from contract deployment through
  conductor cluster setup and failover drills.
* [Network architecture](/chain-operators/guides/management/network-architecture):
  where op-conductor sits in a production topology, including its use as a
  leader-aware RPC proxy for op-batcher.

## Configuration & flags reference

* [Configuration and RPCs](/chain-operators/tools/op-conductor/reference):
  every CLI flag and environment variable, with flag tables generated from
  the op-conductor release named on the page, plus the `conductor`
  namespace RPC methods for cluster management.

## Releases

* [op-conductor release history](/releases/op-conductor)

## Source & spec links

* [Source: `op-conductor/`](https://github.com/ethereum-optimism/optimism/tree/develop/op-conductor)
  in the Optimism monorepo; its
  [README](https://github.com/ethereum-optimism/optimism/blob/develop/op-conductor/README.md)
  documents the architecture, the conductor state transitions, and
  walkthroughs of each failure scenario.
* op-conductor is operational tooling and has no section of its own in the
  OP Stack specifications; the sequencing role it coordinates is specified
  in the
  [rollup node specification](https://specs.optimism.io/protocol/rollup-node.html).


# op-contracts
Source: https://docs.optimism.io/op-stack/components/op-contracts

Canonical hub for op-contracts, the OP Stack L1 and L2 smart contracts, covering what they do, how they are deployed and upgraded, and where their reference, releases, source, and specs live.

op-contracts is the OP Stack's smart contract layer: the L1 contracts that
anchor an OP Stack chain to Ethereum and the L2 predeploy contracts that
every OP Stack chain ships in its genesis state. Both live in
`packages/contracts-bedrock` in the Optimism monorepo and release together as
`op-contracts/vX.Y.Z`.

## Overview

The L1 contracts, deployed on Ethereum, facilitate cross-domain message
passing and maintain the valid state root of the L2: deposits enter the chain
through them, withdrawals are proven and finalized against dispute game
results, and the chain's onchain configuration lives in them. The L2
predeploys sit at predetermined addresses in the genesis state and provide
the chain's built-in functionality, from the cross-domain messengers and
bridges to the fee vaults and the gas price oracle. For a
contract-by-contract tour of both layers, see the
[smart contract overview](/op-stack/protocol/smart-contracts).

It exists because an OP Stack chain's security anchors on Ethereum: the
bridge, the state proposals that dispute games check, and the withdrawal path
that [op-challenger](/op-stack/components/op-challenger) defends are all
enforced by these contracts.

**Who runs it:** nobody operates op-contracts as a service; the contracts run
onchain. Chain operators deploy a chain's L1 contracts with
[op-deployer](/op-stack/components/op-deployer) and upgrade them through the
[OP Contracts Manager](/chain-operators/reference/opcm), which deploys and
upgrades the contracts for a chain in a single transaction.

## Get started

* [Deploy L1 contracts with op-deployer](/chain-operators/tutorials/create-l2-rollup/op-deployer-setup):
  install op-deployer, prepare your environment, and deploy the L1
  contracts for a new OP Stack chain.

## How-tos

* [Upgrade using superchain-ops](/chain-operators/tutorials/l1-contract-upgrades/superchain-ops-guide):
  upgrade a chain's L1 contracts with the superchain-ops task workflow,
  the path for chains that require security council signing or a more
  secure upgrade process.
* [Upgrade L1 contracts using op-deployer](/chain-operators/tutorials/l1-contract-upgrades/op-deployer-upgrade):
  version availability and migration paths for op-deployer's deprecated
  `upgrade` command, which supports upgrades only up to
  `op-contracts/v5.0.0`.

## Configuration & flags reference

op-contracts has no CLI; its configuration surface is the deployment
configuration the contracts are deployed with.

* [Rollup deployment configuration](/chain-operators/reference/rollup-deployment-configuration):
  every deploy config field, generated from source and keyed to the
  finalized op-deployer release named on the page.
* [What is a standard chain?](/op-stack/protocol/superchain-registry#what-is-a-standard-chain):
  the standard configuration values a chain must adhere to.

## Releases

* [op-contracts release history](/releases/op-contracts). Production
  contract releases are always tagged `op-contracts/vX.Y.Z`; releases
  tagged `v<semver>` without a component name contain no smart contracts.
* [Smart contract versioning policy](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/book/src/policies/versioning.md):
  the in-repo definition of the release process.

## Source & spec links

* [Source: `packages/contracts-bedrock/`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock)
  in the Optimism monorepo.
* [Contracts book](https://devdocs.optimism.io/contracts-bedrock):
  the in-repo developer book, covering interface documentation,
  architecture, and contract policies.
* [Deposits specification](https://specs.optimism.io/protocol/deposits.html):
  the normative definition of the deposit path the L1 contracts implement.
* [Withdrawals specification](https://specs.optimism.io/protocol/withdrawals.html):
  the normative definition of the withdrawal path.
* [Predeploys specification](https://specs.optimism.io/protocol/predeploys.html):
  the normative definition of the L2 predeploy contracts.


# op-deployer
Source: https://docs.optimism.io/op-stack/components/op-deployer

Canonical hub for op-deployer, the OP Stack chain deployment tool, covering what it does, who runs it, and where its guides, reference, releases, and source live.

op-deployer is the OP Stack's chain deployment tool: a CLI that
deploys the L1 smart contracts for new OP Stack chains, driven by a
declarative configuration file.

## Overview

op-deployer reads an *intent* file describing a chain's desired configuration
and makes the minimum set of smart contract calls required to make the
deployment match it. It is distributed as a standalone binary with no
additional dependencies, its configuration is optimized for deploying
Standard OP Chains, and it exposes lower-level primitives and Go libraries
for more complex setups. Its `upgrade` and `manage` commands are deprecated;
see the
[deprecation notice](/notices/archive/op-deployer-upgrade-deprecation) for the
supported upgrade paths and alternatives.

It exists because deploying an OP Stack chain means deploying a large,
interdependent set of L1 contracts at specific supported versions.
op-deployer turns that into a declarative, repeatable process, and each of
its releases maps to the contract releases it supports.

**Who runs it:** chain operators and developers deploying chains. It runs
on demand, from a workstation, in CI pipelines, or inside local development
environments; it is not a long-running service.

Unlike most components, op-deployer already has a full documentation set on
this site, under [OP Deployer](/chain-operators/tools/op-deployer/overview)
in the Chain Operators tab; this hub routes into it.

## Get started

* [Deploy L1 contracts with op-deployer](/chain-operators/tutorials/create-l2-rollup/op-deployer-setup):
  install op-deployer, prepare your environment, and deploy a chain's L1
  contracts as the first step of standing up an OP Stack chain. To install
  the binary on its own, see
  [Install op-deployer](/chain-operators/tools/op-deployer/installation).

## How-tos

* [Custom deployments](/chain-operators/tools/op-deployer/usage/custom-deployments):
  manage deployments that depart from the standard configuration.
* [Release workflows](/chain-operators/tools/op-deployer/usage/release-workflows):
  backport fixes onto earlier op-deployer versions and add support for new
  contract versions.
* [Upgrade L1 contracts using op-deployer](/chain-operators/tutorials/l1-contract-upgrades/op-deployer-upgrade):
  version availability and migration paths for the deprecated `upgrade`
  command, which supports upgrades only up to `op-contracts/v5.0.0`. For
  later upgrades, see the
  [deprecation notice](/notices/archive/op-deployer-upgrade-deprecation).

## Configuration & flags reference

* Command reference:
  [init](/chain-operators/tools/op-deployer/usage/init),
  [apply](/chain-operators/tools/op-deployer/usage/apply),
  [bootstrap](/chain-operators/tools/op-deployer/usage/bootstrap), and
  [verify](/chain-operators/tools/op-deployer/usage/verify) document each
  command's flags and the intent file settings.
* [Artifacts locators](/chain-operators/tools/op-deployer/reference/artifacts-locators):
  how op-deployer points at contract artifacts.
* [Known limitations](/chain-operators/tools/op-deployer/known-limitations):
  current limitations and their workarounds.

## Releases

* [op-deployer release history](/releases/op-deployer)
* [OP Deployer releases reference](/chain-operators/tools/op-deployer/reference/releases):
  which op-deployer version supports which contract release.

## Source & spec links

* [Source: `op-deployer/`](https://github.com/ethereum-optimism/optimism/tree/develop/op-deployer)
  in the Optimism monorepo; its
  [README](https://github.com/ethereum-optimism/optimism/blob/develop/op-deployer/README.md)
  declares this documentation set as its source of truth.
* [Architecture reference](/chain-operators/tools/op-deployer/reference/architecture/overview):
  op-deployer's internals, including its deployment pipeline and execution
  engine.
* op-deployer is deployment tooling and has no section of its own in the
  OP Stack specifications; the standard chain configuration it deploys is
  specified in
  [OP Stack Configurability](https://specs.optimism.io/protocol/configurability.html).


# op-node
Source: https://docs.optimism.io/op-stack/components/op-node

Canonical hub for op-node, the OP Stack rollup node in Go, covering what it does, who runs it, and where its guides, reference, releases, source, and spec live.

op-node is the OP Stack's consensus-layer client, written in Go: the rollup
node that derives the canonical L2 chain from L1 data and drives an execution
client to process the resulting blocks.

## Overview

op-node builds, relays, and verifies the canonical chain of L2 blocks. As a
sequencer it builds new blocks; as a verifier it derives blocks from the data
the chain posted to L1 and accepts only blocks that can be reproduced from
that data. The blocks themselves are executed by an execution client, such as
op-reth, which op-node controls through the Engine API; the two run in a
one-to-one pairing. op-node also relays the sequencer's new (unsafe) blocks
over a P2P network for low-latency access to the latest state; the relay is
optional and never affects the ability to verify.

It exists because an OP Stack chain is *derived*: the canonical chain is
defined by data available on L1, and the rollup node is the component that
turns that data into verified L2 blocks. It plays the role a beacon node
plays on L1, and it implements the rollup node specification.

**Who runs it:** every node operator. Each OP Stack node pairs a rollup node,
op-node or [kona-node](/releases/kona-node) (the Rust implementation of the
same role), with an execution client. Chain operators additionally run
op-node in sequencer mode to build new blocks.

## Get started

* [Running a Node With Docker](/node-operators/tutorials/node-from-docker):
  run op-node and op-reth from the official Docker images. To build and run
  from source instead, see
  [Building and running an OP Stack node from source](/node-operators/tutorials/run-node-from-source).

## How-tos

* [Consensus client configuration](/node-operators/guides/configuration/consensus-clients):
  configure op-node (or kona-node) and connect it to your execution client.
* [Fetch blob data for your node](/node-operators/guides/management/blobs): give op-node the
  L1 beacon endpoint it needs to fetch blob batch data, including blobs
  older than the beacon retention window.
* [Node troubleshooting](/node-operators/guides/troubleshooting): solutions
  to common node problems, many of them surfaced in op-node logs.

## Configuration & flags reference

* [op-node configuration options](/node-operators/reference/op-node-config):
  every CLI flag and environment variable, with flag tables generated from
  the op-node release named on the page.
* [op-node JSON-RPC API](/node-operators/reference/op-node-json-rpc): the
  rollup-specific RPC methods op-node serves.

## Releases

* [op-node release history](/releases/op-node)

## Source & spec links

* [Source: `op-node/`](https://github.com/ethereum-optimism/optimism/tree/develop/op-node)
  in the Optimism monorepo; its
  [README](https://github.com/ethereum-optimism/optimism/blob/develop/op-node/README.md)
  documents the quickstart, design principles, and failure modes (L1
  downtime, L1 reorgs, sequencer window expiry, and more).
* [Rollup node specification](https://specs.optimism.io/protocol/rollup-node.html):
  the normative definition of the rollup node's role.
* [L2 chain derivation specification](https://specs.optimism.io/protocol/derivation.html):
  the normative definition of how the canonical L2 chain is derived from L1
  data.


# op-proposer
Source: https://docs.optimism.io/op-stack/components/op-proposer

Canonical hub for op-proposer, the OP Stack output proposer, covering what it does, who runs it, and where its guides, reference, releases, source, and spec live.

op-proposer is the OP Stack's output proposer: the service that submits
output roots, claims about the L2 chain's state, to L1 so that withdrawals
can be proven against them.

## Overview

op-proposer queries its rollup node for an output root (a commitment to the
L2 state at a given block) and submits it to L1 on a configured interval. On
a chain running fault proofs, each proposal is a transaction to the
`DisputeGameFactory` that creates a new dispute game: a claim that stands
unless successfully challenged. By default op-proposer proposes only
finalized L2 state, because a proposal of state that does not hold true later
is an invalid claim that carries dispute game penalties. (A pre-fault-proof
proposal path still exists in the code but is effectively unused.)

It exists because proposals are how L1 learns about L2 state: withdrawals are
authenticated against resolved proposals, so a user proves a withdrawal
against a proposed output root and finalizes it once that proposal's dispute
game resolves in its favor. Without op-proposer, no new output roots reach L1
and withdrawals cannot be proven.

**Who runs it:** the chain operator, as one of the chain's core services. On
chains with permissioned fault proofs, only the designated
[proposer role](/op-stack/protocol/privileged-roles) can submit proposals;
with [permissionless fault proofs](/op-stack/fault-proofs/explainer) anyone
can propose, but the operator still runs op-proposer so proposals land
regularly.

## Get started

* [Spin up proposer](/chain-operators/tutorials/create-l2-rollup/op-proposer-setup):
  set up and configure op-proposer as part of standing up an OP Stack
  chain.

## How-tos

* [Migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless):
  configure the dispute components and switch the respected game type.
* [Switch to Kona proofs](/chain-operators/guides/features/switching-to-kona-proofs):
  move a chain to Kona-based fault proofs, including updating the game type
  op-proposer creates.

## Configuration & flags reference

* [Proposer configuration](/chain-operators/guides/configuration/proposer):
  every configuration option and environment variable, plus the proposer
  policy constraints that govern what gets proposed and when.

## Releases

* [op-proposer release history](/releases/op-proposer)

## Source & spec links

* [Source: `op-proposer/`](https://github.com/ethereum-optimism/optimism/tree/develop/op-proposer)
  in the Optimism monorepo; its
  [README](https://github.com/ethereum-optimism/optimism/blob/develop/op-proposer/README.md)
  documents the proposal flow (with a sequence diagram), design principles,
  and failure modes.
* [L2 output root proposals specification](https://specs.optimism.io/protocol/proposals.html):
  the normative definition of output-root proposals.
* [Withdrawals specification](https://specs.optimism.io/protocol/withdrawals.html):
  how withdrawals are proven against proposals.


# op-reth
Source: https://docs.optimism.io/op-stack/components/op-reth

Canonical hub for op-reth, the OP Stack execution client built on reth, covering what it does, who runs it, and where its guides, reference, releases, source, and spec live.

op-reth is the OP Stack's execution-layer client, written in Rust and built on
[reth](https://github.com/paradigmxyz/reth): it executes the L2 blocks the
rollup node derives and maintains the resulting chain state.

## Overview

op-reth provides the EVM execution environment for OP Stack chains. A rollup
node ([op-node](/op-stack/components/op-node) or
[kona-node](/op-stack/components/kona-node)) derives the
canonical chain from L1 data and drives op-reth through the Engine API;
op-reth executes the payloads, maintains the chain state, and serves JSON-RPC.
It extends upstream reth with the OP Stack protocol changes, such as the
deposit transaction type and L2 fee handling, and bakes the
[Superchain Registry](https://github.com/ethereum-optimism/superchain-registry)'s
chain configurations into the binary, so registry chains work by name via the
`--chain` flag.

It exists because every OP Stack node splits into a consensus half and an
execution half, mirroring post-merge Ethereum, and the execution client is the
half that runs the EVM. op-reth is the primary supported execution client and
the implementation maintained by Optimism: new OP Stack feature development,
including hardfork support, happens on op-reth. See
[Choose your node stack](/use-cases/choose-your-node-stack) for the selection
reasoning.

**Who runs it:** every node operator, paired one-to-one with a rollup node.
Chain operators run it as the execution half of their sequencer, where it
builds the new blocks the sequencing rollup node requests.

## Get started

* [Running a Node With Docker](/node-operators/tutorials/node-from-docker):
  run op-reth and op-node from the official Docker images. To build and run
  from source instead, see
  [Building and running an OP Stack node from source](/node-operators/tutorials/run-node-from-source).

## How-tos

* [Execution client configuration](/node-operators/guides/configuration/execution-clients):
  install op-reth, connect it to your consensus client, and set the
  OP Stack specific rollup flags.
* [Sync OP Mainnet](/node-operators/op-reth/run/faq/sync-op-mainnet): import
  Bedrock state and sync OP Mainnet from scratch.
* [Building an archive node](/node-operators/guides/management/archive-node):
  archive versus full nodes, and how to prune op-reth safely.
* [Running op-reth with historical proofs](/node-operators/tutorials/reth-historical-proofs):
  provision the historical proof store that fault-proof infrastructure
  needs.

## Configuration & flags reference

* [op-reth configuration options](/node-operators/reference/op-reth-config):
  routes to the imported op-reth CLI reference, versioned with the op-reth
  source tree.
* [Understanding the op-reth CLI](/node-operators/op-reth/cli/overview): how
  the commands, chain selection, and configuration model fit together.
* [op-reth JSON-RPC reference](/node-operators/reference/op-reth-json-rpc):
  the RPC namespaces op-reth serves.

## Releases

* [op-reth release history](/releases/op-reth)

## Source & spec links

* [Source: `rust/op-reth/`](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-reth)
  in the Optimism monorepo.
* [Reth book, OP Stack chapter](https://reth.rs/run/opstack): the upstream
  reth project's operational documentation, maintained with reth releases.
* [L2 execution engine specification](https://specs.optimism.io/protocol/exec-engine.html):
  the normative definition of the OP Stack's changes to the execution
  engine.
* [Deposits specification](https://specs.optimism.io/protocol/deposits.html):
  the normative definition of the deposit transaction type op-reth
  implements.


# proxyd
Source: https://docs.optimism.io/op-stack/components/proxyd

Canonical hub for proxyd, the RPC request router and proxy, covering what it does, who runs it, and where its guide, configuration, releases, and source live.

proxyd is the OP Stack's RPC request router and proxy: a daemon that fronts a
fleet of backend nodes and presents them to clients as one reliable RPC
endpoint.

## Overview

proxyd whitelists RPC methods, routes them to groups of backend services,
automatically retries failed backend requests, load-balances across backends,
caches immutable responses, and exposes metrics for request latency, error
rates, and backend health. In consensus-aware mode it additionally tracks
each backend's `latest`, `safe`, and `finalized` blocks, resolves a consensus
group of healthy backends, and rewrites requests and responses to enforce
that consensus, so clients see a consistent view of the chain and experience
fewer reorgs.

It exists because serving production RPC traffic from a single node is
fragile: one crashed, forked, or lagging backend becomes user-visible
downtime. proxyd turns a pool of replicas into a fault-tolerant serving
layer. It is infrastructure around the chain, not a protocol component.

**Who runs it:** chain operators and RPC providers serving public or internal
RPC from a pool of replica nodes. It is also the recommended front for a
high-availability pool of op-supernode instances.

## Get started

* [Run proxyd](/chain-operators/tools/proxyd): build the binary, create a
  configuration file, and start the service.

## How-tos

* [Network architecture](/chain-operators/guides/management/network-architecture):
  where proxyd sits in a production topology, including running public RPC
  behind proxyd in consensus-aware routing mode.
* [Supernode configuration](/node-operators/guides/configuration/supernode):
  front a high-availability pool of op-supernode instances with a
  consensus-aware proxyd.

## Configuration & flags reference

proxyd is configured through a TOML file rather than CLI flags, and no
generated configuration reference exists on this site yet.

* [example.config.toml](https://github.com/ethereum-optimism/infra/blob/main/proxyd/example.config.toml):
  the full list of options, with commentary, in the proxyd source.
* The [proxyd guide](/chain-operators/tools/proxyd) documents the
  consensus-awareness, caching, and metrics settings.

## Releases

* [proxyd release history](/releases/proxyd)

## Source & spec links

* [Source: `proxyd/`](https://github.com/ethereum-optimism/infra/tree/main/proxyd)
  in the Optimism infra repository, the monorepo's extension repository for
  ecosystem infrastructure; its
  [README](https://github.com/ethereum-optimism/infra/blob/main/proxyd/README.md)
  documents the request lifecycle, WebSocket support, and consensus
  awareness.
* proxyd is RPC infrastructure and has no section of its own in the
  OP Stack specifications.


# Choose a content type
Source: https://docs.optimism.io/op-stack/contribute/choose-a-content-type

A maintainer-facing decision table for picking the right documentation type, composition, and operational metadata.

This page is for docs maintainers and contributors, not readers. It settles
the two questions that come up in almost every content pull request — "which
kind of page am I writing?" and "which frontmatter does it carry?" — by
decision table, so the answer is cited rather than re-argued per PR. The
pattern follows Cloudflare's maintainer-facing content-type selection page in
its [documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/).

Before choosing a type, check the
[content guide](/op-stack/contribute/content-guide) that the content belongs
on docs.optimism.io at all.

## The taxonomy: four quadrants, four compositions

Documentation pages on docs.optimism.io carry a `diataxis:` frontmatter key
with one of the four [Diátaxis](https://diataxis.fr/) quadrant values —
`tutorial`, `how-to`, `reference`, or `explanation`. That taxonomy is
complete and does not grow: the composed types below are **compositions of
the quadrants, not new quadrants**, and they never appear as `diataxis:`
values.

A composed type is declared with a second, optional frontmatter key,
`content-type:`, carried *alongside* `diataxis:`. It takes exactly four
values, one per published spec:

| Composed type                                         | `content-type:`  | `diataxis:`                                                                           | What the composition is                                                                                                            |
| ----------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| [Solution guide](/op-stack/contribute/solution-guide) | `solution-guide` | `how-to`                                                                              | A goal-scoped how-to at journey altitude: it sequences existing pages across quadrants and adds only the connective decision logic |
| [Learning unit](/op-stack/contribute/learning-unit)   | `learning-unit`  | The underlying page's quadrant (usually `explanation`; `tutorial` for hands-on stops) | A thin sequencing layer over one existing page inside an ordered track                                                             |
| [Curriculum hub](/op-stack/contribute/curriculum-hub) | `curriculum-hub` | `explanation`                                                                         | An oriented index that composes all four quadrants for one feature under one sidebar node                                          |
| [Router/landing](/op-stack/contribute/router-landing) | `router-landing` | Omitted — see below                                                                   | Pure navigation: the page only routes readers to pages in the quadrants                                                            |

Rules that keep this an extension rather than a fork:

* **`content-type:` never replaces `diataxis:`.** Every page that documents,
  instructs, or explains anything keeps its quadrant tag. The one sanctioned
  omission is `content-type: router-landing`: a pure router contains no
  documentation mode of its own to classify, so it carries `content-type:`
  and no `diataxis:` key. If a router grows explanatory or instructional
  content, it is no longer a router — reclassify it.
* **Only these four `content-type:` values exist.** Proposing a fifth means
  amending this page and publishing a spec for it, through normal docs
  review.
* **Pages of the four base types don't carry `content-type:` at all.** An
  ordinary how-to is just `diataxis: how-to`.
* **`keywords.config.yaml` is not extended for composed types.** The
  composed types are declared only in page frontmatter, per the rows
  above.

### Notice metadata

A [notice](/op-stack/contribute/notice) is time-bound operational content
for an upgrade, deprecation, or other change that requires readers to
prepare. Its dominant reader need is authoritative information about a
specific change, so a notice carries `diataxis: reference`.

The additional `content_type: notice` metadata key (with an underscore)
marks the page's operational purpose and lifecycle for the notice index and
site search. It does not create a fifth quadrant or composition. The
`content-type:` key (with a hyphen) remains limited to the four composition
values above.

Use a notice when the page must answer all of these questions:

* What is changing and why?
* Which personas are affected, and what breaks or remains compatible for
  each one?
* What must each affected reader do before the cutover?
* When and how does the change take effect?

After the change is complete, archive the notice and move durable facts into
the relevant guide, reference, or
[network upgrade registry](/op-stack/protocol/network-upgrades).

## How-to guide vs. tutorial vs. solution guide

These three are confusable because all three are action-oriented. The
distinctions are the starting state, the scope, and who owns the steps.

| Question                             | How-to guide                          | Tutorial                                                     | Solution guide                                                                                                       |
| ------------------------------------ | ------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| What state does the reader start in? | A working environment, already set up | A clean machine (or close to it) — setup is part of the page | A working system, plus a goal that spans components                                                                  |
| How wide is the scope?               | One discrete task on one component    | One end-to-end build, environment setup included             | One goal across multiple components, often multiple documentation properties                                         |
| Who owns the steps?                  | The page owns its steps               | The page owns its steps                                      | The page **derives**: each stop links an existing page and states what to extract; the page adds only decision logic |
| What does it end with?               | Verification of the task              | Verification of the whole working state, then cleanup        | Verification of the outcome, then curated next steps                                                                 |
| Frontmatter                          | `diataxis: how-to`                    | `diataxis: tutorial`                                         | `diataxis: how-to` + `content-type: solution-guide`                                                                  |

Quick tests:

* If the page must install or configure the environment before the real
  work starts, it's a **tutorial**.
* If the page's steps are its own — copy-pasteable commands the reader
  executes on one component — it's a **how-to guide**.
* If the page's main job is sequencing *other* pages toward a goal and
  deciding between options along the way, it's a **solution guide**. A
  solution guide that starts restating the steps of the pages it links is
  violating the [dual-sourcing ban](/op-stack/contribute/content-guide#link-dont-restate-the-dual-sourcing-ban)
  — cut the restatement and link.

Exemplars: [Configure the batcher](/chain-operators/guides/configuration/batcher)
(how-to at configuration-guide depth);
[Bridging your ERC-20 token](/app-developers/tutorials/bridging/cross-dom-bridge-erc20)
(tutorial); the first solution guide ships with the Use Cases section — until
it lands, the [solution guide spec](/op-stack/contribute/solution-guide)
carries the template.

## Explanation vs. learning unit

Both are understanding-oriented. The distinction is who the reader is and
what the page may assume.

| Question              | Explanation                                               | Learning unit                                                                                                                                       |
| --------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Who arrives?          | Anyone, in any order, usually from search or a cross-link | A learner progressing through an ordered track or curriculum hub                                                                                    |
| What may it assume?   | Only what it states in its own intro                      | Everything covered by the previous stops in its track                                                                                               |
| Who owns the content? | The page owns its conceptual material                     | The unit **frames** existing material: it adds sequencing context (what you now know, what this stop adds, where to go next) and links, never forks |
| Frontmatter           | `diataxis: explanation`                                   | The underlying page's quadrant + `content-type: learning-unit`                                                                                      |

Quick tests:

* If removing the page from its nav group would leave it fully
  comprehensible, it's an **explanation**.
* If the page opens with "in the previous stop…" or only makes sense at
  position N of a sequence, it's a **learning unit**.
* If you're about to *copy* an explanation into a track so you can reorder
  it — stop. Learning units link and frame; they never duplicate. Add a
  framing header to the existing page instead (see the
  [learning unit spec](/op-stack/contribute/learning-unit)).

Exemplars: [The OP Stack](/op-stack/introduction/op-stack) and the
[fault proofs explainer](/op-stack/fault-proofs/explainer) (explanations that
would gain learning-unit framing inside a track without being rewritten).

## Next steps

* Read the type spec before writing the page:
  [solution guide](/op-stack/contribute/solution-guide),
  [learning unit](/op-stack/contribute/learning-unit),
  [curriculum hub](/op-stack/contribute/curriculum-hub),
  [router/landing](/op-stack/contribute/router-landing), or
  [notice](/op-stack/contribute/notice).
* For the four base quadrants, the
  [style guide's content types section](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/STYLE_GUIDE.md#content-types)
  remains the reference.
* For what belongs on the site at all, see the
  [content guide](/op-stack/contribute/content-guide).


# Component hub template
Source: https://docs.optimism.io/op-stack/contribute/component-hub-template

The uniform skeleton every OP Stack component hub page follows, with guidance for each section.

Every component listed in the [Stack Components](/op-stack/components/index)
section gets exactly one identity page — its **hub** — and every hub follows
the same skeleton. Structural uniformity is the point: a reader who has used
one hub knows where to look on every other hub, and reviewers can check a new
hub against this template mechanically, section by section.

The pattern follows Cloudflare's
[documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/),
which gives every product's documentation set the same shape and documents
each product in a single canonical place.

## The skeleton

A hub page contains these sections, in this order, using these exact H2
headings:

```mdx theme={null}
---
title: <component name>
description: <one sentence: what the component is and does>
diataxis: explanation
---

<One-paragraph orientation: what this component is, in plain language.>

## Overview

<What the component does, why it exists, and who runs it.>

## Get started

<The one canonical starting point: a tutorial or setup guide.>

## How-tos

<Links to the task guides that involve this component.>

## Configuration & flags reference

<Link to the component's configuration reference page.>

## Releases

<Link to the component's release history.>

## Source & spec links

<Links to the source directory, in-repo deep docs, and the normative spec.>
```

## Section guidance

Hubs are thin identity-and-links pages, not content pages. They follow the
[content guide](/op-stack/contribute/content-guide)'s dual-sourcing ban:
wherever a canonical source exists — a guide, a reference page, a spec
section, an in-repo document — the hub links it and never restates it.

### Overview

Answer three questions in at most a few short paragraphs: **what** the
component does, **why** it exists (what breaks without it), and **who runs
it** (chain operators, node operators, dispute participants, nobody directly).
Volatile facts — versions, activation dates, flag defaults — do not belong
here; they live in generated or source-linked pages.

### Get started

Exactly one canonical starting point. If a tutorial exists on this site, link
it. If the component's only setup documentation is its in-repo README, link
that and say so.

### How-tos

Link the task guides on this site that configure or operate the component.
Do not summarize them — one line per link describing the task.

### Configuration & flags reference

Link the component's configuration reference page. While these pages are
hand-maintained, note the release they were written against (the reference
page itself carries that provenance). When a generated reference exists, this
slot points at the generated page instead — the hub does not change shape.
If no reference page exists yet, link the component's `--help` surface via its
README and say the docs reference is pending.

### Releases

Link the component's page under [Releases](/releases) when it has one,
otherwise the component's release tags on GitHub.

### Source & spec links

Always in this order, when they exist:

1. The source directory in the monorepo (or the component's home repository).
2. In-repo deep documentation (design docs, runbooks) worth surfacing.
3. The component's section of the [OP Stack specifications](https://specs.optimism.io/)
   — deep-link the exact page, never the spec root.

## What hubs are not

* **Not a second guide.** If you find yourself writing instructions, that
  content belongs in a how-to page the hub links.
* **Not a reference.** No flag tables, no RPC methods, no version matrices.
* **Not a news page.** Release announcements live on the releases pages.

Questions about a hub that this template does not settle go through the
[content guide](/op-stack/contribute/content-guide)'s canonical-home matrix;
if the matrix does not cover the case either, raise it in the docs PR.


# Content guide
Source: https://docs.optimism.io/op-stack/contribute/content-guide

What content belongs on docs.optimism.io, the canonical home for each content type, and how to mark third-party content.

This page defines what content belongs on docs.optimism.io and, for every
content type, which source is canonical. It exists so that "where does this
live?" is settled by citing a rule, not re-argued in every pull request.
Reviewers should link the relevant section of this page when requesting
changes.

The approach is adapted from the Kubernetes
[content guide](https://kubernetes.io/docs/contribute/style/content-guide/),
which governs kubernetes.io with the same two ideas: a short allowlist test
for what the site hosts, and a strict preference for linking canonical
sources over restating them.

## What's allowed: the three-clause test

Content belongs on docs.optimism.io only if at least one of the following is
true (adapted from the Kubernetes content guide's third-party content rules):

1. **It documents first-party OP Stack software** — software whose source of
   truth lives in [Optimism](https://github.com/ethereum-optimism)
   repositories, such as the components listed on the
   [Releases](/releases) page.
2. **It documents third-party software that the OP Stack needs to function**
   — for example, an L1 execution client or key-management tooling that an
   OP Stack chain cannot run without. Such content must be marked with the
   [`<ThirdPartyContent>` component](#marking-third-party-content).
3. **It routes to canonical content that lives elsewhere** — a selection,
   orientation, or hub page whose job is to send readers to the right
   canonical home (for example, a curated matrix of SDKs that links each
   SDK's own documentation).

Content that satisfies none of the three clauses — tooling promotion,
project-specific marketing, or documentation for software that is neither
first-party nor required by the OP Stack — belongs on the third party's own
site, not here.

## Link, don't restate: the dual-sourcing ban

Wherever a canonical source already exists, **link it — never restate it**.
The Kubernetes content guide states the reason plainly: dual-sourced content
"requires double the effort to maintain and grows stale more quickly."

In practice:

* **Never paraphrase normative protocol text.** Explain the concept in your
  own words at explanation depth, then deep-link the exact section of the
  [OP Stack specifications](https://specs.optimism.io/) for the normative
  definition.
* **Never copy reference material from another living document.** If a
  component's book, README, or upstream API reference already documents
  something, link to it.
* **Never fork a table of facts** (versions, addresses, activation times,
  flag lists) that another system maintains. Render from the source of
  truth or link it.

## Canonical homes

One home per thing. The matrix below assigns a canonical home to each content
type across the three layers of the OP Stack documentation surface — the
protocol, the components, and the periphery — and states what
docs.optimism.io holds for each.

| Layer      | Content type                                                                                                                                                                                                         | Canonical home                                                                  | What docs.optimism.io holds                                                                                                                                                                                               |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Protocol   | Normative protocol behavior                                                                                                                                                                                          | [specs.optimism.io](https://specs.optimism.io/)                                 | Explanation and routing pages that cite the spec with deep links — never restated normative text                                                                                                                          |
| Protocol   | Hardfork activations and chain metadata                                                                                                                                                                              | [superchain-registry](https://github.com/ethereum-optimism/superchain-registry) | Pages rendered from the registry's structured data, joined — not hand-copied                                                                                                                                              |
| Components | Concepts, how-tos, and tutorials for running components                                                                                                                                                              | docs.optimism.io (full ownership)                                               | The pages themselves, e.g. the [batcher guide](/chain-operators/guides/configuration/batcher)                                                                                                                             |
| Components | Flags and configuration reference                                                                                                                                                                                    | The component's source at a tagged release                                      | A reference page generated from source where a generator exists; otherwise a hand-maintained page pinned to a named release, e.g. the [batcher configuration reference](/chain-operators/reference/batcher-configuration) |
| Components | Implementation internals and developer books (e.g. [kona](https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona), [op-reth](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-reth)) | The component's developer documentation, maintained beside its source           | Orientation and selection pages that link into the deep material                                                                                                                                                          |
| Periphery  | SDKs and ecosystem tooling (e.g. [viem](https://viem.sh/op-stack), wagmi)                                                                                                                                            | The upstream project's own documentation                                        | One curated hub with a support matrix; every listing marked with `<ThirdPartyContent>`                                                                                                                                    |

Precedents for the matrix, clause by clause:

* **Spec joined, never mirrored.** Kubernetes documents feature lifecycles
  through its structured
  [feature gates reference](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/)
  rather than copying design documents into prose.
* **One identity page per component.** Cloudflare publishes a uniform
  per-product
  [content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/)
  so every product's documentation set has the same shape.
* **A curated matrix over the periphery.** Stripe's
  [SDK page](https://docs.stripe.com/sdks) differentiates its client
  surfaces in one table; ethereum.org publishes written
  [listing criteria](https://ethereum.org/en/contributing/adding-products/)
  so curation is policy application rather than per-PR debate.
* **The component declares its docs home.** Each component's README should
  point at its canonical documentation, following the
  [op-deployer README](https://github.com/ethereum-optimism/optimism/blob/develop/op-deployer/README.md)
  model.

When two pages could both claim a topic, the matrix decides. If the matrix
does not cover the case, raise it in the docs PR and propose a new row —
amendments to this page go through the same review as any other docs change.

## Marking third-party content

<Info>
  This section documents the `<ThirdPartyContent>` component, following the
  Kubernetes [`thirdparty-content` shortcode](https://kubernetes.io/docs/contribute/style/content-guide/)
  pattern: every third-party mention is stamped the same way, so third-party
  content stays greppable and auditable.
</Info>

Pages or sections that document or list third-party software (clauses 2 and 3
of the [three-clause test](#whats-allowed-the-three-clause-test)) must open
with the `<ThirdPartyContent>` component:

```mdx theme={null}
import ThirdPartyContent from "/snippets/third-party-content.mdx"

<ThirdPartyContent />
```

Which renders:

<Warning>
  Items on this page refer to third-party projects or products that are not
  maintained by Optimism. They are provided for convenience; refer to each
  project's own documentation as the source of truth.
</Warning>

When an entire page is about a single third-party project or product, use the
single-project variant instead:

```mdx theme={null}
import ThirdPartyContentSingle from "/snippets/third-party-content-single.mdx"

<ThirdPartyContentSingle />
```

Which renders:

<Warning>
  This page refers to a third-party project or product that is not maintained
  by Optimism. It is provided for convenience; refer to the project's own
  documentation as the source of truth.
</Warning>

## Citing the normative spec

<Info>
  This section documents the `<NormativeSpec>` component, the standing
  callout that applies the [dual-sourcing ban](#link-dont-restate-the-dual-sourcing-ban)
  to protocol pages: every page whose subject is normatively defined in the
  [OP Stack specifications](https://specs.optimism.io/) is stamped the same
  way, so spec citations stay uniform and greppable.
</Info>

The component is **reserved for explainer pages** — pages whose frontmatter
declares `diataxis: explanation`, primarily the concept pages in the OP Stack
section. An explainer page whose subject is normatively defined in the spec
must open with the `<NormativeSpec>` component, deep-linking the exact spec
section that defines its subject:

```mdx theme={null}
import { NormativeSpec } from "/snippets/normative-spec.mdx"

<NormativeSpec
  what="The derivation pipeline"
  title="L2 chain derivation specification"
  href="https://specs.optimism.io/protocol/derivation.html"
  note="This page is a short orientation; it does not restate the spec."
/>
```

Which renders:

<NormativeSpec title="L2 chain derivation specification" href="https://specs.optimism.io/protocol/derivation.html" />

All four variables are required: `what` names the subject the spec defines,
`title` and `href` name and deep-link the governing spec section (a rendered
`specs.optimism.io` URL on its current path, per the
[link policy](/op-stack/contribute/link-policy)), and `note` states what the
page does instead of restating the spec.

Guides, tutorials, and reference pages do **not** open with the component.
They should not go deep into protocol workings at all — that depth belongs
on an explainer page or in the spec itself. Where a guide, tutorial, or
reference page needs to touch a spec-defined concept, link the relevant spec
section inline at the point of use instead.

One deliberate exception: the
[hardfork registry pages](/op-stack/protocol/network-upgrades) are reference
pages, but the registry's purpose is the spec pointer, so they carry the
same component with the spec URL from their structured frontmatter.

## Next steps

* Read the [style guide](/op-stack/contribute/style-guide)
  for voice, tone, and formatting conventions.
* Read the [contributing guide](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/DOCS_CONTRIBUTING.md)
  for development setup and the pull request process.
* Have questions? Open an issue in the
  [Optimism monorepo](https://github.com/ethereum-optimism/optimism/issues).


# Curation review policy
Source: https://docs.optimism.io/op-stack/contribute/curation-policy

The review cadence for curated pages, the last-reviewed frontmatter contract, the sweep that keeps curated content fresh, and the rule for delisting what rots.

Some pages in these docs are **curated artifacts**: they do not document one
component, they select, sequence, or recommend across many. A solution guide
is a chain of links and decisions; a router page is a set of chosen entry
points; a selection page compares options that keep evolving. Curated content
is the most valuable kind of page and the fastest to rot, because nothing
breaks when it goes stale. This page is the standing policy that keeps it
fresh.

## What counts as a curated artifact

Any page whose main job is choosing or sequencing rather than documenting:

* **Solution guides** (`content-type: solution-guide`), each a chain of
  links plus decision tables.
* **Router and landing pages** (`content-type: router-landing`), including
  the section indexes that choose what to surface.
* **Curriculum hubs and learning-track indexes** (`content-type:
  curriculum-hub`), which sequence existing pages into a path.
* **Selection and comparison pages**: any page presenting dated facts about
  alternatives (client choices, tool matrices).
* **Prompt libraries and AI onboarding pages**: curated prompts and
  integration instructions that reference specific product surfaces.

Ordinary tutorials, how-to guides, reference pages, and explanations are not
curated artifacts; they are maintained by the normal review flow for their
component.

## The `last-reviewed:` contract

Every curated artifact carries a review stamp in its frontmatter:

```yaml theme={null}
last-reviewed: YYYY-MM-DD
```

The stamp means: on that date, a reviewer confirmed the page's links resolve,
its load-bearing claims still match source, and its recommendations are still
the ones we would make. It is set on merge for a new page and bumped only by
a review that actually re-verified the page, never by an unrelated edit
passing through.

The frontmatter is deliberately greppable so staleness is checkable
mechanically:

```bash theme={null}
# from docs/public-docs/
grep -rn "last-reviewed:" --include="*.mdx" .
```

## Sweep intervals by artifact class

| Artifact class                                                | Sweep interval | Rationale                                                                                        |
| ------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------------ |
| Solution guides, selection and comparison pages               | 90 days        | They carry decision logic and version-sensitive facts; a stale recommendation misleads directly. |
| Prompt libraries and AI onboarding pages                      | 90 days        | They name concrete product surfaces (URLs, server endpoints) that change without notice.         |
| Router/landing pages, curriculum hubs, learning-track indexes | 180 days       | They mostly sequence links; the linked pages carry their own accuracy burden.                    |

A page past its interval is not automatically wrong, but it is unverified,
and unverified curation is treated as a defect: it goes to the front of the
next sweep.

## What a sweep does

Each sweep pass picks the curated artifact whose `last-reviewed:` is oldest
relative to its class interval and re-verifies it:

1. **Chain integrity**: every link on the page resolves, including the
   off-site exits, per the [link policy](/op-stack/contribute/link-policy).
   For solution guides this covers the whole chain the guide sequences, not
   just the guide page: one dead link breaks the paved path.
2. **Load-bearing claims**: defaults, thresholds, version numbers, and "as
   of" markers are re-checked against source, and every "as of" date is
   either re-confirmed (and re-dated) or the claim is corrected.
3. **The stamp**: `last-reviewed:` is bumped to the sweep date in the same
   change, so the stamp and the verification never drift apart.

Sweeps run as scheduled, review-gated docs automation, with the results
landing as ordinary reviewable pull requests; a human still owns every merge.

## The delisting rule

Curated pages recommend things, and a recommendation we can no longer stand
behind is removed, not hedged:

* If a sweep finds a curated entry (an exit link, a listed tool, a
  recommended option) that is dead, deprecated, or no longer something the
  docs would recommend, the entry is **removed or replaced in that sweep's
  change**, not annotated with a warning and left in place.
* If an entire curated page can no longer be verified (its subject was
  deprecated, its journey no longer exists), the page is removed from the
  nav and redirected per the
  [redirects guidance](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/REDIRECTS_GUIDE.md),
  with the removal recorded in the pull request.

Listing is a maintenance commitment: a curated entry that nobody re-verifies
on schedule loses its place. This is the same bargain the
[content guide](/op-stack/contribute/content-guide) makes for canonical
homes, applied to curation.

## Adding a new curated page

A new curated artifact enters the rotation on merge:

1. Carry `last-reviewed:` set to a date within its review cycle (normally
   the merge date) plus the `content-type:` its
   [content-type contract](/op-stack/contribute/choose-a-content-type)
   requires.
2. Its pull request states the artifact class, so reviewers know which
   interval it signed up for.
3. No exemptions: a curated page that cannot commit to its class's sweep
   interval should not ship as a curated page.


# Content type: curriculum hub
Source: https://docs.optimism.io/op-stack/contribute/curriculum-hub

The published contract for curriculum hubs — purpose, tone, required components, title grammar, and a copy-paste template.

A **curriculum hub** gathers everything a reader needs to master one feature
— fault proofs, interop — under a single sidebar node, ordered from gentle
introduction to normative spec. It is the answer to "I want to actually
understand X": one place, one reading order, all four documentation modes
composed for one topic.

This page is the contract for the type. A new curriculum hub is reviewed
against it; cite the relevant section in review instead of re-arguing it.

## Purpose

* Give each major feature **one front door** with a recommended reading
  order, instead of pages scattered across nav groups.
* **Compose, don't rewrite**: the hub resequences existing pages and adds
  at most a few short learning-unit pages where the sequence has a gap.
* Make the exits explicit: every hub ends at the **normative spec** (and
  audits, where they exist) so depth-seekers are routed off-site on
  purpose, never stranded.

## Composition

A curriculum hub composes all four quadrants for one feature: explanation
(the gentle intro and deep dives), tutorial/how-to (the hands-on stops),
reference (component and configuration pages), and the spec exit. The hub's
index page carries `diataxis: explanation` (it orients the reader in the
feature) plus `content-type: curriculum-hub`. Stops inside the hub keep
their own quadrant values; new gap-filling stops follow the
[learning unit contract](/op-stack/contribute/learning-unit).

See [Choose a content type](/op-stack/contribute/choose-a-content-type) for
how the composed types relate to the `diataxis:` taxonomy.

## Tone

* The index page orients: what the feature is, why it matters, and how
  the materials fit together — in a few short paragraphs, not an essay.
* Every listed stop gets a one-line reason ("read this to …"), written
  for the learner deciding whether to click, not as a summary.
* Confidence about order, honesty about depth: say what is skippable and
  what is normative.

## Required components

Every curriculum hub must have:

1. **One sidebar node**: the hub is a single nav group; a hub that spans
   groups has failed its purpose.
2. **An index page** with frontmatter `title`, `description`,
   `diataxis: explanation`, `content-type: curriculum-hub`, and
   `last-reviewed: YYYY-MM-DD` (hubs are curated artifacts and enter the
   review sweep on merge).
3. **An ordered path** on the index, in this shape (sections may be merged
   or omitted only where the feature genuinely lacks the material):
   * `## Start here` — the gentle introduction.
   * `## Go deeper` — mechanism and architecture material.
   * `## Get hands-on` — the tutorials and how-tos, where they exist.
   * `## Economics and incentives` — where the feature has them.
   * `## The normative spec` — deep links into
     [specs.optimism.io](https://specs.optimism.io/) on **current spec
     paths** (never retired path generations), per the
     [content guide](/op-stack/contribute/content-guide).
   * `## Audits and security` — where audits exist.
4. **One-line reasons** on every link.
5. **No duplicated content**: the hub links existing pages; a stop needing
   rework gets an issue, not a fork. Gap-filling stops are new
   [learning units](/op-stack/contribute/learning-unit), capped at a few
   per hub.

## Title grammar

The hub's nav group and index title are the feature's plain name in sentence
case: "Fault proofs", "Interoperability". No "hub", "curriculum", "guide to",
or "learn" in the title — the shape is visible from the sidebar; the name
should match what readers search for.

## Template

Copy this template for a new hub's index page:

```mdx theme={null}
---
title: <Feature name>
description: <One sentence: what the feature is and what this hub covers.>
diataxis: explanation
content-type: curriculum-hub
last-reviewed: <YYYY-MM-DD>
---

<Two or three short paragraphs: what <feature> is, why it matters to this
audience, and how the materials below fit together.>

## Start here

*   [<Gentle introduction>](</path>) — read this first for the mental model.

## Go deeper

*   [<Mechanism page>](</path>) — <what it explains, one line>.
*   [<Architecture page>](</path>) — <what it explains, one line>.

## Get hands-on

*   [<Tutorial or how-to>](</path>) — <what you'll build or do, one line>.

## Economics and incentives

*   [<Economics page>](</path>) — <what it covers, one line>.

## The normative spec

The definitive definition of <feature> behavior lives in the OP Stack
specifications:

*   [<Spec section title>](https://specs.optimism.io/<current-path>) —
    <what it defines, one line>.

## Audits and security

*   [<Audit or security page>](</path>) — <what was audited or what the
    security model is, one line>.
```

## Exemplars

Calibrate against the shipped hubs:

* [Fault proofs](/op-stack/fault-proofs/index): the first shipped hub,
  sequencing the six existing fault-proofs pages plus the hands-on
  guides, bond economics, spec exits, and security material.
* [Interoperability](/op-stack/interop/index): the second shipped hub,
  which shows how to frame a hub honestly for a feature still in active
  development.


# Contribute to the docs
Source: https://docs.optimism.io/op-stack/contribute/index

The contributor policies and content-type contracts for docs.optimism.io, routed by the task you came to do.

This section holds the policies and templates that govern contributions to
docs.optimism.io. Each page is a contract: reviewers cite its sections in
docs PRs instead of re-arguing them, so read the pages that match what you
are about to write.

<CardGroup>
  <Card title="Check what belongs on this site" href="/op-stack/contribute/content-guide">
    Find the canonical home for what you want to write, and what stays out
    of the docs entirely.
  </Card>

  <Card title="Write in the site's voice" href="/op-stack/contribute/style-guide">
    Match the voice, tone, formatting, and naming conventions every page
    follows.
  </Card>

  <Card title="Pick the right content type" href="/op-stack/contribute/choose-a-content-type">
    Use the decision table to choose a content type, then follow its
    published contract and template.
  </Card>

  <Card title="Publish a network notice" href="/op-stack/contribute/notice">
    Write time-bound, persona-specific upgrade or deprecation guidance from
    the reusable notice template.
  </Card>

  <Card title="Link the specs and source correctly" href="/op-stack/contribute/link-policy">
    Write cross-repo links in the canonical form the link linter enforces.
  </Card>

  <Card title="Keep curated pages fresh" href="/op-stack/contribute/curation-policy">
    Follow the review cadence, the last-reviewed contract, and the rule for
    delisting content that rots.
  </Card>

  <Card title="Add a component hub" href="/op-stack/contribute/component-hub-template">
    Build a new component's identity page against the uniform hub skeleton.
  </Card>

  <Card title="Change the Learn track" href="/op-stack/contribute/learn-track-syllabus">
    Propose changes to the "Learn the OP Stack" track through its governance
    artifact.
  </Card>

  <Card title="Looking for something else?" href="/">
    Browse the documentation by role: app developer, chain operator, or node
    operator.
  </Card>
</CardGroup>


# Learn track syllabus
Source: https://docs.optimism.io/op-stack/contribute/learn-track-syllabus

The governance artifact for the "Learn the OP Stack" track, including its scope contract, curriculum owner, stop list with rationale, design rules, and changelog.

This page is the syllabus for the
[Learn the OP Stack](/op-stack/learn/index) track: the maintainer-facing
record of what the track covers, why each stop sits where it does, who owns
the curriculum, and how the track changes. The reader-facing front door is
the [track index](/op-stack/learn/index); this page exists so the track has
an owner and a change history instead of drifting, following the MDN
curriculum pattern of a published syllabus with its own changelog.

## Scope contract

The track takes a reader **from newcomer to comfortable**. A finisher has
deployed a test chain, followed a transaction from submission to finality on
Ethereum, moved assets in both directions between layers, and run a node,
and knows where the deeper material lives. Exhaustive detail is out of
scope by design: depth lives in the reference sections and the
[OP Stack specifications](https://specs.optimism.io/), and the track exits
to them.

This sentence is the governance model. A proposed stop that adds depth
rather than progression fails the scope test, however good the page is;
route it through the "After the track" exits on the index instead.

## Ownership

* **Curriculum owner:** Matthew Cruz
  ([@sbvegan](https://github.com/sbvegan)).
* The owner arbitrates scope questions, reviews any change to the stop
  list or its order, and is the named reviewer when the track index comes
  up in the [curation sweep](/op-stack/contribute/curation-policy)
  (learning-track indexes sweep on the 180-day interval).
* A syllabus change merged without the owner's review is reverted on
  sight, not debated after the fact.

## The syllabus

Thirteen stops: three concept blocks punctuated by three hands-on projects,
so each block of ideas is consolidated by using it. Stops are existing
pages; the track adds only a framing note per stop, per the
[learning unit contract](/op-stack/contribute/learning-unit).

| Stop | Page                                                                                       | Kind             | What it adds at this position                                                                        |
| ---- | ------------------------------------------------------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------- |
| 1    | [The OP Stack](/op-stack/introduction/op-stack)                                            | Concept          | The mental model: what the stack is, what it powers, what you can build.                             |
| 2    | [Design philosophy & principles](/op-stack/protocol/design-principles)                     | Concept          | Why the stack is shaped the way it is; vocabulary the rest of the docs assume.                       |
| 3    | [Differences from Ethereum](/op-stack/protocol/differences)                                | Concept          | Grounds "EVM equivalent" before any hands-on work; prevents false transfer from Ethereum experience. |
| 4    | [OP Stack components](/op-stack/protocol/components)                                       | Concept          | Names the layers and modules the learner is about to deploy in project 1.                            |
| 5    | [Creating your own L2 rollup testnet](/chain-operators/tutorials/create-l2-rollup)         | Project          | Consolidates part 1: deploy a rollup testnet with op-deployer and start each component just named.   |
| 6    | [Transaction flow](/op-stack/transactions/transaction-flow)                                | Concept          | Reinterprets the components the learner just ran as stages in one transaction's life.                |
| 7    | [Transaction fees on OP Mainnet](/op-stack/transactions/fees)                              | Concept          | The fee components of a transaction; the economic consequence of the flow in stop 6.                 |
| 8    | [Deposit flow](/op-stack/bridging/deposit-flow)                                            | Concept          | First direction of cross-layer movement: L1-triggered L2 transactions.                               |
| 9    | [Withdrawal flow](/op-stack/bridging/withdrawal-flow)                                      | Concept          | Second direction: the initiate, prove, finalize sequence, and why it exists.                         |
| 10   | [Submitting transactions from L1](/app-developers/tutorials/bridging/cross-dom-bridge-eth) | Project          | Consolidates part 2: walk a deposit and a withdrawal from code with Viem.                            |
| 11   | [Fault proofs explainer](/op-stack/fault-proofs/explainer)                                 | Concept          | Why the withdrawal the learner just proved can be trusted: permissionless proposals and challenges.  |
| 12   | [OP Stack interoperability explainer](/op-stack/interop/explainer)                         | Concept          | Where the stack is going: a network of chains that feels like a single blockchain.                   |
| 13   | [Running a node with Docker](/node-operators/tutorials/node-from-docker)                   | Capstone project | Ends the track operating real infrastructure: run a node on a live network with the official images. |

## Design rules

1. **Stops are existing pages, never forks.** A stop that needs rewording
   gets an issue filed against the page, not a track-local copy. The only
   track-owned artifacts are the [index](/op-stack/learn/index), this
   syllabus, and the framing notes.
2. **Framing notes follow the
   [learning unit contract](/op-stack/contribute/learning-unit)** (framing
   header form): track name, stop position, one sentence of arrival
   context, one sentence of what the stop adds, link to the next stop.
   Nothing else on the page changes.
3. **Cap: 15 stops.** Past that the track has stopped being linear and
   started being a second navigation; split material into the "After the
   track" exits instead.
4. **Projects are spaced, not appended.** Each concept block ends in a
   hands-on stop that uses it (Rust Book cadence). A resequencing that
   leaves two projects adjacent or a concept block unconsolidated needs
   the owner's explicit sign-off.
5. **Resequencing procedure:** update the index, renumber every affected
   framing note ("stop N of M"), verify every next-stop link, and add a
   changelog entry below. Position lives only in framing notes and the
   index, never in page titles, so stops can move without retitling.
6. **Every change lands with a changelog entry.** The changelog is the
   curriculum's memory; an entry states what changed and why, one line
   each.

## Changelog

| Date       | Change                                                                                                                                                                                          |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-07-21 | Initial syllabus: 13 stops (three concept blocks, three projects: deploy a chain, bridge both directions, run a node). Curriculum owner: Matthew Cruz ([@sbvegan](https://github.com/sbvegan)). |

## Next steps

* Reader-facing front door: [Learn the OP Stack](/op-stack/learn/index).
* Framing-note contract: [learning unit](/op-stack/contribute/learning-unit).
* Review cadence: [curation review policy](/op-stack/contribute/curation-policy).


# Content type: learning unit
Source: https://docs.optimism.io/op-stack/contribute/learning-unit

The published contract for learning units — purpose, tone, required components, title grammar, and copy-paste templates for both forms.

A **learning unit** is one stop in an ordered learning sequence — the "Learn
the OP Stack" track or a per-feature curriculum hub. It gives an existing
page a place in a syllabus: what the learner already knows on arrival, what
this stop adds, and where to go next. Content is linked and framed, never
duplicated.

This page is the contract for the type. A new learning unit is reviewed
against it; cite the relevant section in review instead of re-arguing it.

## Purpose

* Let newcomers progress **linearly** through material that was written to
  be read in any order.
* Add **sequencing context only**: orientation, prerequisites-by-position,
  and a pointer to the next stop.
* Protect the underlying pages: a track that needs a page reworded forks
  nothing — it files an issue against the page itself.

## Composition

A learning unit is a composition, not a fifth quadrant. It has two forms:

* **Framing header** (the default): a short framing block prepended to an
  existing page that serves as a track stop. The page keeps its own
  `diataxis:` value; nothing else about it changes.
* **Standalone unit page** (the exception): a new short page written
  because a sequence needs a stop that no existing page provides (for
  example, a bridging paragraph between two concepts in a curriculum hub).
  It carries the quadrant of what it actually is — usually
  `diataxis: explanation`, or `diataxis: tutorial` for a hands-on stop —
  plus `content-type: learning-unit`.

See [Choose a content type](/op-stack/contribute/choose-a-content-type) for
the explanation-vs-learning-unit decision table.

## Tone

* Welcoming but not chatty; the learner is mid-sequence, so respect their
  momentum.
* Second person, present tense: "you now know…", "this page adds…".
* The frame never editorializes about the underlying page ("this excellent
  guide…") and never summarizes it — a one-line statement of what the stop
  adds is the ceiling.

## Required components

**Framing header** (on an existing page):

1. An `<Info>` block at the top of the page body, below the frontmatter and
   any existing callouts.
2. Inside it, in order: the track name and stop position ("stop N of M"),
   one sentence of arrival context (what the learner knows from previous
   stops), one sentence of what this stop adds, and a link to the next stop
   (or a completion line on the last stop).
3. Nothing else changes on the page: same `diataxis:` value, same content.

**Standalone unit page**:

1. **Frontmatter**: `title`, `description`, `diataxis:` (the quadrant of
   what the page actually is), `content-type: learning-unit`.
2. **The same framing block** as above, so every stop reads uniformly.
3. **A body that earns its existence**: material no existing page owns. If
   an existing page covers it, use a framing header on that page instead.
4. **A forward exit**: the last line links the next stop, or the track
   index on completion.

## Title grammar

* A framing header adds **no title** — the underlying page keeps its own.
* A standalone unit page titles the concept as a plain noun phrase in
  sentence case ("Fault proof economics", "From transactions to blocks").
  Position ("Part 3:", "Lesson 3") never appears in the title — order
  lives in the track's nav group and the framing block, so stops can be
  resequenced without retitling.

## Templates

Framing header — copy onto an existing page that becomes a track stop:

```mdx theme={null}
<Info>
  **<Track name> — stop <N> of <M>.**
  You've <what the previous stops covered>. This page <what this stop
  adds>. When you're done, continue to [<next stop title>](</path/to/next>).
</Info>
```

Standalone unit page:

```mdx theme={null}
---
title: <Concept noun phrase>
description: <One sentence: the concept and what understanding it unlocks.>
diataxis: explanation
content-type: learning-unit
---

<Info>
  **<Track name> — stop <N> of <M>.**
  You've <what the previous stops covered>. This page <what this stop
  adds>. When you're done, continue to [<next stop title>](</path/to/next>).
</Info>

<The concept, at the smallest size that lets the learner continue the
sequence. Link the canonical deep material rather than reproducing it.>

## Next stop

Continue to [<next stop title>](</path/to/next>), where you'll <what comes
next>.
```

## Exemplars

No track is wired yet — the learn track and curriculum hubs consume this
contract when they ship. Calibrate against the pages that would become
stops, and the external patterns:

* [The OP Stack](/op-stack/introduction/op-stack) and the
  [fault proofs explainer](/op-stack/fault-proofs/explainer) — existing
  explanations that would gain a framing header, unchanged otherwise.
* [Bridging your ERC-20 token](/app-developers/tutorials/bridging/cross-dom-bridge-erc20)
  — the shape of a hands-on stop (`diataxis: tutorial`).
* The [Rust Book](https://doc.rust-lang.org/book/) — the cadence this
  type exists to reproduce: strictly ordered chapters, hands-on projects
  spaced through the sequence, depth exiled to reference.


# Cross-repo link policy
Source: https://docs.optimism.io/op-stack/contribute/link-policy

The canonical form for every link from docs.optimism.io into the specs, source repositories, and other pages — and the linter that enforces it.

The documentation joins three layers — the [OP Stack specifications](https://specs.optimism.io/),
the component source repositories, and these docs — with links. Links rot
silently: a retired spec path keeps "working" through a hand-maintained
redirect table, a commit-pinned contract link never 404s while teaching a
two-generations-old architecture, and a misplaced tracking parameter breaks an
anchor without breaking the page. This page defines one canonical form for
each link target, and every rule on it is enforced by a deterministic linter
(`scripts/lint-link-policy.mjs`).

This policy is an annex of the [content guide](/op-stack/contribute/content-guide):
the guide decides *where* content lives and when to link instead of restate;
this page defines *how* those links must be written.

## Linking the specs

**Always link the rendered site, on its current paths.**

* Link `https://specs.optimism.io/...`, never a GitHub blob of a file under
  the specs repo's `specs/` directory — every `specs/**.md` source has a
  rendered page, and the rendered page is the canonical, navigable form.
  (GitHub links to non-rendered specs-repo files, such as `book.toml`, are
  fine.)
* Use the page's **current** path. Retired paths (for example
  `/experimental/fault-proof/...`, now `/fault-proof/...`) survive only
  through a hand-maintained redirect table in the specs repo's `book.toml`
  and can disappear without notice. The linter vendors that redirect table
  and reports the current path to use.
* **Deep anchors must resolve.** An anchor like `#frame-format` must match a
  real heading slug in the target page. The linter resolves every specs
  anchor against a checkout of the specs source (`--specs-src`), so a heading
  rename upstream surfaces as a lint failure here instead of a silently dead
  fragment.

## Query parameters come before the fragment

UTM decoration (or any query string) goes **before** the `#fragment`, per the
URL standard — a query appended after the fragment becomes part of the
fragment, and the anchor never resolves.

```text theme={null}
✅ https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs&utm_medium=docs#frame-format
❌ https://specs.optimism.io/protocol/derivation.html#frame-format?utm_source=op-docs&utm_medium=docs
```

## Linking source code

**Prefer floating links; badge every pin.**

* Links that track a branch (`.../blob/develop/...`) are the default: they
  follow the code and never teach a stale layout.
* A link pinned to a commit sha or release tag
  (`.../blob/v1.1.4/...`, `.../blob/op-contracts/v1.6.0/...`,
  `.../blob/62c7f3b0.../...`) is allowed **only** when the pin is the point
  — quoting behavior at a specific release — and it must carry an
  ``as of `<tag>` `` badge on, or immediately adjacent to, the same line:

  ```mdx theme={null}
  [OptimismPortal.sol](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.6.0/packages/contracts-bedrock/src/L1/OptimismPortal2.sol) (as of `op-contracts/v1.6.0`)
  ```

  The badge tells the reader the link is a snapshot, and tells the
  maintenance sweep which pins are deliberate. An unbadged pin is presumed
  to be accidental staleness and fails the linter.

## Internal links

* Internal page links are **root-relative**: `/chain-operators/...`, never
  `./sibling-page` or a bare word. The target page must exist (or be covered
  by a redirect in `docs.json`).
* Static assets are referenced by their on-disk path from the docs root,
  including the `public/` prefix: `/public/img/...`.

## The linter

`scripts/lint-link-policy.mjs` enforces all of the above plus dead-internal-link
detection. It is dependency-free and offline-deterministic; Mintlify's
`mint broken-links` serves as an advisory second opinion on internal links.

```bash theme={null}
# from docs/public-docs/
node scripts/lint-link-policy.mjs --baseline scripts/lint-link-policy.baseline.json

# with specs anchor resolution
git clone --depth 1 https://github.com/ethereum-optimism/specs.git /tmp/specs
node scripts/lint-link-policy.mjs --specs-src /tmp/specs --baseline scripts/lint-link-policy.baseline.json

# verify the linter itself against its embedded self-test fixtures
node scripts/lint-link-policy.mjs --self-test
```

Violations that predate the linter are recorded in
`scripts/lint-link-policy.baseline.json`, so a run flags only **new**
violations. The baseline is a burn-down list, not an allowlist: remediation
batches shrink it with `--update-baseline`, and pull requests must never grow
it. If the linter flags a link you believe is a deliberate exception, raise it
in review — do not rebaseline silently.

Enforcement runs as a scheduled, review-gated docs automation plus the local
runs above; the linter, its baseline, and its embedded self-test fixtures all
live under `docs/public-docs/`.


# Content type: notice
Source: https://docs.optimism.io/op-stack/contribute/notice

The published contract for time-bound network notices, including required persona impacts, actions, timing, and a copy-paste template.

A **notice** tells affected readers about an upcoming network upgrade,
deprecation, or operational change and gives them the actions required to
stay compatible. Notices are time-bound: they remain active while readers
need to prepare, then move to the notice archive after the change is
complete.

This page is the contract for the type. Review a new notice against it and
cite the relevant section instead of re-arguing the structure in each pull
request.

## Composition

A notice is `diataxis: reference`: it gives readers authoritative facts
about one change, including its scope, compatibility, timing, and affected
versions. Put the executable migration procedure in a how-to guide or
runbook and link it from the notice.

The additional `content_type: notice` metadata key (with an underscore)
marks the page's operational purpose and lifecycle. It is not a fifth
Diátaxis quadrant or one of the composed documentation types. The similarly
named `content-type:` key (with a hyphen) remains reserved for the four
compositions in
[Choose a content type](/op-stack/contribute/choose-a-content-type).

## Purpose

* Name the change, why it is happening, and when it takes effect.
* Identify every affected persona and state the breaking changes or
  explicit no-action outcome for each one.
* Give readers an action checklist with versions, configuration, contract,
  or application changes they can verify before the cutover.
* Preserve the transition behavior readers need to know, such as what
  happens to in-flight withdrawals, disputes, or transactions.

Do not use a notice as the permanent explanation of a feature or the only
record of an upgrade. Link canonical guides and reference pages for durable
details.

## Required frontmatter

Every notice carries the metadata used by the notice index and site search:

```yaml theme={null}
---
title: <Change or action>
description: <One sentence naming the change and affected readers.>
diataxis: reference
lang: en-US
content_type: notice
topic: <unique-kebab-case-topic>
personas:
  - <persona from keywords.config.yaml>
categories:
  - <category from keywords.config.yaml>
is_imported_content: 'false'
---
```

Use every applicable persona from `keywords.config.yaml`; do not reduce the
list to the primary audience. Add `audit-source:` when source files or
generated artifacts were checked to substantiate the notice.

Add `date:` (an ISO `YYYY-MM-DD` value) when the notice is archived. It
records the date the change took effect — the mainnet hardfork activation,
the end-of-support date, the mainnet execution date of a contract upgrade,
or the start of a time-boxed experiment — and it must match the row for the
page in the [notice archive](/notices/archive). Omit the key rather than
guess: when no canonical in-tree source gives a date, the archive row says
"Not dated" instead.

## Required components

Every notice must include:

1. **Summary**: one or two paragraphs naming the change, its scope, and the
   primary action.
2. **Motivation** (`## Why <change>` or `## Why this is changing`): the
   user-facing reason for the change, with links to durable explanations
   when more background is useful.
3. **Change scope** (`## What's included` or `## What is changing`): the
   concrete protocol, contract, component, or product changes. State
   important exclusions explicitly.
4. **Persona impacts** (`## Breaking Changes`): one `###` subsection for
   each persona in frontmatter. State what breaks, what must change, and
   what remains compatible. If a persona has no action, say so directly.
5. **Required actions**: copy-pasteable configuration, version, contract,
   or application changes. Use a component table when several releases are
   involved.
6. **Timing**: the activation mechanism and schedule. For a network
   upgrade, say whether it has a hardfork activation. Do not invent a
   timestamp or release version; add it when the canonical source is
   available.
7. **Verification and support**: tell readers how to verify readiness and
   where to report a problem.

When a change affects state that can span the cutover, explain the
transition. Common examples include Dispute Games already in progress,
withdrawals already proved, transactions in flight, and old configuration
that must remain temporarily available.

## Writing rules

* Lead with the action and affected reader, not the internal project
  history.
* Use proper product and protocol names. Preserve command, flag, package,
  function, and component spelling in code formatting.
* Separate confirmed scope from unknown timing or release data. Do not
  weaken confirmed changes by labeling the entire notice provisional.
* Link to the canonical runbook or reference rather than duplicating its
  full procedure.
* Keep persona subsections independently scannable. A reader should not
  need to infer their action from another persona's section.

## Lifecycle

Add an active notice to both `/notices` and the matching Network Notices
navigation group in `docs.json`.

After activation and completion of the required migration window:

1. Move the page under `/notices/archive`.
2. Remove its active card from `/notices` and delete its `docs.json`
   navigation entry. Archived notices are deliberately not in the sidebar:
   add the page to `scripts/lint/nav-allowlist.json` with a reason so the
   nav validator accepts it, set the page's `date:` frontmatter, and add a
   row to the [notice archive](/notices/archive), which is how readers
   browse to it. The page keeps its URL forever — live pages link into it.
3. Record the permanent outcome in the
   [network upgrade registry](/op-stack/protocol/network-upgrades), using
   the [contract upgrades table](/op-stack/protocol/network-upgrades#contract-upgrades)
   when the change has no hardfork.
4. Update durable guides and references so they describe the post-upgrade
   state without relying on the archived notice.

## Template

Copy this template to start a notice:

```mdx theme={null}
---
title: <Change or action>
description: <One sentence naming the change and affected readers.>
diataxis: reference
lang: en-US
content_type: notice
topic: <unique-kebab-case-topic>
personas:
  - <affected-persona>
categories:
  - <approved-category>
is_imported_content: 'false'
---

<One or two paragraphs: what is changing, who must act, and the activation
mechanism or known date.>

## Why this is changing

<The user-facing motivation. Link the durable explanation or specification
for deeper context.>

## What's included

*   <Change in scope>
*   <Change in scope>

This change does not <important exclusion>.

## Breaking Changes

### <Persona>

<What breaks or changes for this persona. State "No action is required" when
that is the result, then explain why.>

### <Persona>

<Impact and compatibility details for the next persona.>

## Required actions

| Component or integration | Required change |
| --- | --- |
| `<name>` | <Version, flag, API, contract, or workflow change> |

<Add a short action checklist or link the canonical runbook.>

## Timing

<Activation date or mechanism. Say whether the change includes a hardfork.
Name the canonical source where final timestamps or releases will appear.>

## Verify readiness

*   <Observable check and expected result>
*   <Observable check and expected result>

For support, <link the issue tracker or support channel>.
```


# Content type: router/landing
Source: https://docs.optimism.io/op-stack/contribute/router-landing

The published contract for router and landing pages — purpose, tone, required components, title grammar, and a copy-paste template.

A **router/landing page** exists to send readers somewhere else, fast. The
site root routing four personas, a tab landing page, a goal-shortcut page —
all are routers: pure navigation with a one-line promise per destination and
nothing to read for its own sake.

This page is the contract for the type. A new router is reviewed against it;
cite the relevant section in review instead of re-arguing it.

## Purpose

* Get every arriving reader onto the **right path in one decision**:
  by persona (app developer, chain operator, node operator, protocol
  learner) or by goal ("deploy a chain", "bridge an asset").
* Order destinations by audience size, not internal org structure — the
  largest audience's path comes first.
* Stay small: a router that starts explaining or instructing has stopped
  being a router.

## Composition

A pure router is the one composed type that carries **no `diataxis:` key**:
it contains no documentation mode of its own to classify — it only routes
into pages that do. It carries `content-type: router-landing` instead, so it
remains machine-classifiable. The moment a page mixes routing with real
explanatory or instructional content, it is no longer a router: classify it
by what it teaches and move the routing into cards or a "next steps"
section.

See [Choose a content type](/op-stack/contribute/choose-a-content-type) for
how the composed types relate to the `diataxis:` taxonomy.

## Tone

* Second person, benefit-first: every destination is phrased as what the
  reader will accomplish, not what the section contains ("Deploy your
  first contract on an OP Stack chain", not "Documentation about
  contracts").
* One line per destination. If a destination needs two sentences to
  justify itself, the destination is wrong or the router is explaining.
* No marketing register. A router is wayfinding, not a pitch.

## Required components

Every router/landing page must have:

1. **Frontmatter**: `title`, `description`,
   `content-type: router-landing`, and `last-reviewed: YYYY-MM-DD`
   (routers are curated artifacts and enter the review sweep on merge).
   No `diataxis:` key — see Composition. `mode: wide` is allowed where the
   layout needs it.
2. **At most one short orienting paragraph** (or a hero block) before the
   routes. No concepts, no history, no feature tour.
3. **Routes as `<Card>`/`<CardGroup>` blocks** (or an equivalent visually
   scannable pattern), each with a title naming the reader or goal, an
   `href`, and a one-line benefit.
4. **Full coverage of its audience split**: a persona router routes every
   persona it claims; readers outside the split get a catch-all route
   (search, glossary, or support).
5. **Resolving links only** — a router is a chain of links and nothing
   else, so every link must resolve; dead routes are release blockers, not
   cleanup.

## Title grammar

* A **goal router** takes the goal as an imperative phrase in sentence
  case: "Deploy the OP Stack".
* A **persona/section landing page** takes the audience or section's
  plain name: "App developers".
* Never "Welcome", "Home", "Overview", "Getting started" as the full
  title — the title should say where the reader is or what they came to
  do.

## Template

Copy this template for a new router/landing page:

```mdx theme={null}
---
title: <Goal phrase or audience name>
description: <One sentence naming who this page routes and to what.>
content-type: router-landing
last-reviewed: <YYYY-MM-DD>
---

<At most one short orienting paragraph: who this page serves and how to
choose a path. Omit it entirely if the cards are self-evident.>

<CardGroup cols={2}>
  <Card title="<Persona or goal, largest audience first>" href="</path>">
    <One line: what this reader will accomplish there.>
  </Card>
  <Card title="<Persona or goal>" href="</path>">
    <One line: what this reader will accomplish there.>
  </Card>
  <Card title="<Persona or goal>" href="</path>">
    <One line: what this reader will accomplish there.>
  </Card>
  <Card title="<Catch-all: everything else>" href="</path>">
    <One line: where readers outside the split find their footing.>
  </Card>
</CardGroup>
```

## Exemplars

* The [site root](/) — today a single-persona landing page ("Deploy the
  OP Stack"); its planned rewrite into a four-persona router is the
  first page that must pass this spec.
* [The OP Stack](/op-stack/introduction/op-stack) — a hybrid worth
  studying for the boundary: it routes with cards *and* explains, which
  is why it is classified `diataxis: explanation`, not
  `content-type: router-landing`.
* Cloudflare's [documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/)
  — the published-content-type pattern this contract follows.


# Content type: solution guide
Source: https://docs.optimism.io/op-stack/contribute/solution-guide

The published contract for solution guides — purpose, tone, required components, title grammar, and a copy-paste template.

A **solution guide** takes a reader with a real goal that spans multiple
components — "tune my batcher costs", "run a fault-proof challenger" — and
sequences the existing documentation into one paved path. It is the page a
reader would otherwise have to assemble themselves from guides, reference
pages, specs, and READMEs across several properties.

This page is the contract for the type. A new solution guide is reviewed
against it; cite the relevant section in review instead of re-arguing it.

## Purpose

* Turn a traced reader journey into **one in-site page with curated
  exits**, so the goal is completable without leaving docs.optimism.io
  except through exits the guide chose on purpose.
* Add the **connective decision logic** — which option to pick when, and
  why — that no single component page can own.
* **Derive, never duplicate.** Each stop links the canonical page and
  states what to extract from it. Restating a linked page's steps or facts
  violates the
  [dual-sourcing ban](/op-stack/contribute/content-guide#link-dont-restate-the-dual-sourcing-ban).

## Composition

A solution guide is a composition of the existing taxonomy, not a fifth
quadrant: frontmatter carries `diataxis: how-to` (it is goal- and
action-oriented) plus `content-type: solution-guide`. See
[Choose a content type](/op-stack/contribute/choose-a-content-type) for how
it differs from a plain how-to guide and from a tutorial.

## Tone

* Direct and economical. The reader has a goal and a working system; no
  scene-setting beyond the one-paragraph goal statement.
* Decisions are stated as conditions: "if X, choose Y because W" — never a
  bare "we recommend Y".
* Honest about staleness: any exit into hand-maintained or version-pinned
  material carries an "as of" marker rather than implying freshness.

## Required components

Every solution guide must have, in order:

1. **Frontmatter**: `title`, `description`, `diataxis: how-to`,
   `content-type: solution-guide`, and `last-reviewed: YYYY-MM-DD` (solution
   guides are curated artifacts and enter the review sweep on merge, per
   the [curation review policy](/op-stack/contribute/curation-policy)).
2. **Goal statement**: one paragraph naming the outcome, the intended
   reader, and the components involved.
3. **Fit test** (`## Is this guide for you?`): bullet conditions for when to
   use the guide, plus where to go instead when it doesn't fit.
4. **Starting state** (`## Before you start`): the working state and access
   the guide assumes. A solution guide never contains environment setup —
   that is tutorial territory; link one if needed.
5. **Sequenced stops** (`## Step 1: …`, `## Step 2: …`): numbered `##`
   sections, each an imperative action. A stop that derives from another
   page links it and states exactly what to extract. A stop that is a
   decision states the decision logic, preferably as an
   if/choose/because table.
6. **Verification** (final step): how the reader confirms the goal is
   reached.
7. **Next steps** (`## Next steps`): the deliberate, curated ways out —
   deeper reference, the normative spec, upstream material — each with a
   one-line reason and, where the target is version-pinned or
   hand-maintained, an "as of" marker.

## Title grammar

`<Imperative verb> <object>` in sentence case, naming the reader's goal:
"Tune batcher costs", "Run a fault-proof challenger", "Choose your node
stack". No "How to" prefix, no gerunds ("Tuning…"), no component-first
titles ("op-batcher cost tuning").

## Template

Copy this template to start a new solution guide:

```mdx theme={null}
---
title: <Verb> <object>
description: <One sentence naming the outcome and who it serves.>
diataxis: how-to
content-type: solution-guide
last-reviewed: <YYYY-MM-DD>
---

<One paragraph: the goal, the intended reader, and the components involved.>

## Is this guide for you?

Use this guide if:

*   <condition on the reader's role or system>
*   <condition on the goal>

If you <adjacent need>, see [<other page>](</path/to/page>) instead.

## Before you start

You should already have:

*   <working state this guide assumes>
*   <tools or access required>

## Step 1: <Imperative action>

<What to do. When this stop derives from another page, link it and state
what to extract:>

Read [<page title>](</path/to/page>) and take away:

*   <the specific values, concepts, or commands this goal needs>

## Step 2: <Imperative decision>

<The connective decision logic this guide adds — the material that exists
nowhere else:>

| If ... | Choose ... | Because ... |
| --- | --- | --- |
| <scenario> | <option> | <rationale> |

## Step 3: Verify the outcome

<How the reader confirms the goal is reached: the metric, output, or state
to check, and what a good result looks like.>

## Next steps

*   [<Exit title>](<url>) — <what the reader gets there>. <As of `<tag or
    date>` for version-pinned or hand-maintained targets.>
*   [<Normative spec section>](https://specs.optimism.io/<path>) — <why a
    reader would need the normative definition>.
```

## Exemplars

* [Tune batcher costs](/use-cases/tune-batcher-costs): the first solution
  guide and the proof of the form, with derive-links stating explicit
  takeaways, if/choose/because tables, and badged exits.
* [Configure the batcher](/chain-operators/guides/configuration/batcher) —
  the central stop of the batcher-costs journey: the depth a solution
  guide links *into* rather than reproduces.
* [Consensus client configuration](/node-operators/guides/configuration/consensus-clients)
  — in-site precedent for stated decision criteria between options.
* Cloudflare's [documentation content strategy](https://developers.cloudflare.com/style-guide/documentation-content-strategy/)
  — the published-content-type pattern this contract follows.


# Style guide
Source: https://docs.optimism.io/op-stack/contribute/style-guide

How to write technical content for Optimism Docs with a consistent voice, tone, and style.

This guide explains how to write technical content for Optimism Docs using a consistent voice, tone, and style.

This Style Guide aims to assist Optimists in writing technical content with a consistent voice, tone, and style. See the [glossary](https://docs.optimism.io/op-stack/reference/glossary) for an alphabetical listing of commonly used words, terms, and concepts used throughout the technical docs and across Optimism.

This doc doesn't cover all questions or use-cases. Our guide is based on the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/). Please reference their guide for any use-case or situation we do not cover here.

This guide covers **how** to write (voice, tone, formatting, and structure). For **what** content belongs on docs.optimism.io — the canonical home for each content type and how to mark third-party content — see the [Content Guide](/op-stack/contribute/content-guide).

* For docs-related questions, comments, or support, create an issue in the [Optimism monorepo](https://github.com/ethereum-optimism/optimism/issues).

## Table of Contents

* [Files, Folders, and Naming Conventions](#files-folders-and-naming-conventions)
* [Writing Style](#writing-style)
* [Accessibility](#accessibility)
* [Content Organization](#content-organization)
* [Links](#links)
* [Content Types](#content-types)
* [General Formatting](#general-formatting)

## Files, folders, and naming conventions

### Folder structure

The folder structure for the [docs.optimism.io](https://github.com/ethereum-optimism/optimism/tree/develop/docs/public-docs) repository is organized into several high-level categories.

The left sidebar (side navigation) is managed in the `docs.json` file, which should be edited only for adding or deleting pages. Frequent edits may lead to merge conflicts due to ongoing content updates. Accept changes from others when committing a PR.

Don't worry if you're not sure where in the left sidebar a new topic belongs. Do your best and when you submit your PR, the Developer Relations team will edit the `docs.json` file and determine the right placement.

The right sidebar (page TOC) is created automatically for all the H2 and H3 headings on a page.

### Filenames

In general, filenames should be as short as possible (\~2 to 4 words) and all lower-case. Add a hyphen (-) between each word.

**Example:** `writing-a-guide.mdx` or `run-node.mdx`

### File paths

File paths, when mentioned **within** a docs page, should be formatted as code snippets for readability and wrapped in backticks.

**Example**: `/source/docs/assets/images/`

## Writing style

### Voice and tone

Write in a friendly, yet professional tone. We are upbeat, knowledgeable, and **optimistic** about the development of Optimism, which we try our best to convey in our technical documentation.

### Clear and concise language

* Be consistent. Use the same terminology, voice, and tone throughout the documentation.
* Be concise. Focus on providing key information and avoid including superfluous information.
* Use language the audience understands. Although it's challenging to avoid jargon in the web3 space, several strategies can enhance language comprehension, such as:
  * checking the glossary to ensure terminology is clearly defined before using it; and
  * regularly updating the glossary
* Write in an action-oriented style. Focus on helping the user complete the task at hand by writing in the active voice. An active voice is more direct and reduces ambiguity. Avoid passive voice as it is often vague and creates awkward sentences.
* Avoid gender-specific language. Use the imperative. This form of a verb lets you use the second person (you, your) rather than the third person (him, her, she, his).

### Capitalization

See below for when to use title or sentence case.

* Avoid using all caps as it slows down reading comprehension.

* Capitalize proper nouns in sentences.
  **Example**: I use Visual Studio on my local machine.

* Use title case for all headers (H1, H2, H3) and when referring to buttons, tab names, page names, and links within the documentation. Note: The actual text on buttons, links, pages, or tabs need not be in title case—only the references within the docs.

  > **Examples of Title Case:**
  >
  > * Domains For the Development Environment (header)
  > * Select **Make Owner**.
  > * Click **Clear Caches**.
  > * Select the **Settings** tab.

* Use sentence case for body content and short phrases, even when the content is a link. Sentence case means you only capitalize the first letter of the sentence.
  **Example:** If you're trying to figure out how to do something specific as a node operator, you might search our collection of tutorials or [suggest a new one](https://github.com/ethereum-optimism/optimism/issues).

* Use lowercase in code snippets by default, unless the code block uses capitalization (e.g., for the name of a function or variable) and you are referring to the function or variable elsewhere within the technical documentation.
  **Examples**: Run `git add` or Import `useState`

  > When in doubt, follow the code base because exact capitalization is necessary in order for the code to compile.

## Accessibility

When creating content, ensure it is accessible to screen-reader users, visually impaired individuals, and those using a mouse or keyboard. For more information regarding accessibility guidelines, see [W3C Web Content Accessibility Guidelines 2.0](http://www.w3.org/TR/UNDERSTANDING-WCAG20/Overview.html#contents).

### Alt-text

* Provide alt text for all images so that the screen reader can interpret the purpose of the image and convey that to the user. The alt text should include any content shown in the image so that screen reader can read it to the user.
* Provide alt text for videos by modifying the title attribute of any embedded video content or iframe. The title attribute serves as the alt text for screen readers to provide descriptive information. Video content with speaking or narration must include closed captions.

### Captions

* Provide captions for visual elements/objects whenever possible, so visuals are accessible to all users, regardless of ability. This includes images or screenshots, animated GIFs, promo and tutorial videos, tables, charts, mermaid diagrams, and code blocks.
* Ensure that captions can be translated into major languages.

### Images

* Don't use images of text, code samples, or terminal output. Use actual text.
* Use SVG instead of PNG if available. SVGs stay sharp when users zoom in on the image.

## Content organization

We aim to use consistent organization that is also user-centered and accessible. This requires intentional work and planning to group technical content into sections instead of using long, dense paragraphs. This also gives readers a visual rest from a usability perspective and improves reading comprehension.

* Use structured headings (H1, H2 or #, ##) to guide readers through the technical documentation.
* Use numbered lists for chronological steps.
* Use bulleted lists to visually separate content that does not require a specific order.
* Format text for optimal readability (bold vs. italics). Avoid using italics in web content as it decreases readability. For instance, **bold** is appropriate to use when referring to a specific button or page name in technical documentation.
* Organize technical content to cover only one major concept or task at a time.
  * **General rule of thumb**: documents with more than 3 levels of structured headings (H4 or ####) and/or more than 20 minutes estimated reading time (ERT) need revisions will typically involve editing for conciseness, splitting the document into multiple pages, or both.
  * Revisions will usually require editing for concision, breaking the document apart into multiple pages, or some combination of the two.
* Organize content based on the audience's varying needs and prior knowledge. If pre-requisite knowledge is necessary to complete a task or understand a concept, then share it with users (including links to learn more), so they can easily get up to speed.

### Meta tags

* Define the meta **title**, **language**, and **description** for each page to improve SEO ranking of the docs. Place meta tags at the top of the page before the H1 tag, with 3 dashes surrounding the block of text on either side.

* Set the meta title by reusing the H1 page title, but since meta titles are not visually displayed on the page to users, the H1 page title is also required.

  > **NOTE:** SEO guidelines suggest that meta page titles differ slightly from H1 page titles, but this is handled automatically by our site platform. So, please match H1 page titles to meta page titles for ease of documentation.

* Set the language attribute for accessibility and usability (for screen readers) but also to make it easier to enable language localization support in the future.

* Write meta descriptions as concise overviews (100-150 characters) of the most relevant content of the page.

> **Example Meta section of docs:**
>
> ```
> ---
> title: Supercharge Your App with Account Abstraction
> lang: en-US
> description: This guide explains how account abstraction enables users to utilize smart contracts to build, onboard, and scale apps.
> ---
> ```

### Page titles (H1)

* Create concise page titles and format as H1. The title should be able to fit on 1-2 lines.
* Every page must have an H1 heading, in addition to the page title being defined in the SEO meta tags.
* H1 heading is reserved for page titles, so avoid using H1 in any other place on the page.
* For tutorials and quick starts, use task-based page titles starting with gerunds (verb ending in "ing").
  **Examples**: `Creating Your Own L2 Rollup` or `Running a Node`

### Headings and TOC

* Use an imperative verb for headings or subheadings in a document, and not a gerund (a verb ending in "ing"). Headings should be shown in H2 tags, and subheadings should be shown in H3 tags.

* Outline the page content according to main topics first. Those will be your headings (tagged as H2). If there are subtopics that belong under a category, display those as subheaders (tagged as H3).

  > **Example:**
  >
  > * (H1) Supporting OP Mainnet in Your Wallet (H1 page title uses "ing" verb ending)
  > * (H2) Connect to OP Mainnet (H2 does not use "ing" verb ending)
  > * (H2) Locate Canonical Token Addresses (second H2 does not use "ing" verb ending)

* Use headings in a logical manner, and the site will automatically generate anchor links for H2 and H3 tags and place them in a Table of Contents (TOC) in the right column.

* Avoid H4 levels and above within guide and template pages. As stated elsewhere in this style guide, technical documents with more than 3 levels of structured headings (H4 or ####) usually indicates clarity, organization, or structural issues and should be revised.

* H4 headings are reserved (at this time) for glossary terms. This standardization will make it easier for us to extend glossary functionality across the docs in the future, such as tool tips.

### Listing prerequisites (before you begin)

* Add a "Before You Begin" section at the top of the document if there are tasks a user needs to complete before continuing with the current task, e.g. installing a module, downloading a software update, etc.
* Use the title "Before You Begin" and format as H2. It should follow the page overview/intro section or table of contents.
* Include all the tasks the user needs to complete, including links to aid in usability. Use a bulleted list for more than 2 prerequisite items.

  > **Example:**
  > (H2) Before You Begin
  > You'll need to enable the ApacheSolr module. Visit the [ApacheSolr](https://drupal.org/project/apachesolr) page on [Drupal.org](http://drupal.org/) for more information.

### Callouts

* Use callouts to direct users to information necessary to complete a task or information of special importance. When adding a callout to a document, use sentence case.
* Use the correct callout type based on the type of issue: a) info/general, b) warning, c) error. Our documentation platform supports 4 different callout types.
  * The default and info callouts are used to share non-sensitive, non-breaking info with users, such as suggestions or best practices that might make the installation or deployment easier.
  * Warning callouts should be used to indicate important info, such as when a product or code will be deprecated.
  * Error callouts are reserved for critical issues that cannot be undone or can result in breaking changes, such as when data might be permanently deleted or lost.
* Use callouts sparingly as too many can be confusing to readers. **As a general rule of thumb:** pages with more than 2 callouts likely needs revision and/or a discussion with an Optimism developer or product manager to ensure guide content accuracy.

### Code samples

* Use code samples as often as possible to help explain concepts. Can be used in guides or tutorials, but every tutorial should have at least one code sample to be useful to developers.
* Any bits of code should be wrapped in backticks and use built-in syntax highlighting. Most documentation platforms automatically apply syntax highlighting when properly defined inside the code block.

**Example**: This markdown or MDX file

```js theme={null}
console.log('hello, world')
```

will render this code snippet in `javascript` with proper syntax highlighting.

* To improve readability and accessibility even further, consider the following user-centered options for code blocks:
  * adding a filename or title to the code block
  * adding a caption or description (shown above)
  * adding or showing the line numbers within the code block (easily refer to a certain code lines within the documentation)
  * highlighting lines or strings in the code block to draw user's attention to specific areas

### Images, screenshots, & icons

* Images, screenshots, and icons are stored in the `public/img` directory in the root folder.
* Every image and screenshot should have descriptive alt text.
* Screenshots should clearly capture the content being discussed in the guide or tutorial.
  * Use more than one screenshot if space is an issue and/or to better coordinate screenshots with a particular location or tutorial step in the technical documentation.
  * Use arrows and callouts to help explain the elements in the image that are not already highlighted by the interface. Do not use callouts to highlight the environment and tool, as they are apparent.
* Images can be inserted two ways: embedded in the `.mdx` file or imported. Use the latter option when you need to add styling to the image, such as a specific height or width, but note that the file path changes when the image is imported.
* File paths to images will vary based on where the image is located and how the image is used (e.g., embedded vs imported into the mdx page — see below for an example).
* **Example (embedded)**: `![Deposit Flow Diagram](/public/img/op-stack/protocol/deposit-flow.png)`
* **Example (imported)**:

```jsx theme={null}
<Image
    src="/public/img/op-stack/protocol/deposit-flow.png"
    alt="Deposit Flow Diagram"
    width={400}
    height={400}
/>
```

* Icons come from [Remix](https://remixicon.com/) to maintain consistency across the docs. Use Optimism Red `FF0420` to color icons before downloading and store icons in `public/img/icons` directory.

### Videos

* Use videos sparingly and only for more complex tasks.
* Write meaningful alt text for videos and animations. Include a caption too, if possible.
* Promo videos should be as short as possible, typically no more than 30 seconds.
* Animated gifs should also be short, generally between 10-60 seconds.
* Tutorial videos are considered educational content and should not exceed 10 minutes, based on instructional design best practices.
* Tutorial videos must be hosted by a third party (YouTube, Vimeo, etc.) and include closed captions for accessibility.
* Embed videos with an iframe and add/modify the `title` attribute as needed to make more meaningful `alt-text`, which improves accessibility for screen readers.
* **Example of video with title for alt-text:**

```html theme={null}
<iframe width="560" height="315" src="https://www.youtube.com/embed/_Y6CwsYgqwI?si=7erhCEj6cz1nD0VO"
title="Optimism Getting Started Tutorial" frameborder="0" allow="accelerometer; autoplay;
clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
```

## Links

Developers trust that we will lead them to sites or pages related to their reading content. In order to maintain that trust, it's important that links are transparent, up-to-date, and lead to legitimate resources.

### Internal links

* Internal links are automatically generated based on the H2 and H3 title tags.

* When linking to a specific H2 or H3 section of a page, the anchor links are always lowercase with dashes taking the place of spaces.
  **Example**: `(H3) Test your application` is converted to `test-your-application` as an anchor link.

* Use anchor links, whenever possible, to guide users to a specific page and location in the technical documentation. This reduces cognitive load and improves overall usability.

* To link to an anchor, such as an H3 tag within a page, you need to append it to the page name preceded by `#`, like this **example**: `[any descriptive text](/app-developers/tutorials/tokens/deploy-superchain-erc20)`.

### Linking across pages

* Use absolute or relative links when linking across pages in the site. Absolute links are cleaner and easier to work with when pages are nested, so they are the recommended option.
  **Examples**: absolute link `(/op-stack/protocol/bridging/deposit-flow)` versus relative link `(../../protocol/deposit-flow)`

* Use the exact title of the page when linking to it in a sentence, whenever possible, and display it in title case. The link should use default styling with no other formatting (bold, italics, quotations).
  **Example**: Be sure to check out [The OP Stack](https://docs.optimism.io/op-stack/introduction/op-stack) to get up to speed.

* Use sentence case when linking to an article without using the exact article title. This causes minimal disruption to the flow of the sentence. The link should use default styling.
  **Example**: For something more advanced, we recommend reading through our page on [sending data between L1 and L2](https://docs.optimism.io/app-developers/bridging/messaging).

* Use `detailed instructions` link format to refer users to another article with detailed instructions that are important for completing the current task.
  **Example**: For detailed instructions, see [Article Title](https://docs.optimism.io/app-developers/bridging/standard-bridge).

* Use the `more information` link format to guide users to a suggested reading that the user may find helpful because it is related to the task/topic, but not essential for completing the current task.
  **Example**: For more information, see [Article Title](https://docs.optimism.io/app-developers/bridging/standard-bridge).

## Content types

Content types help manage technical content by defining the purpose and common structure for each file type. All content types used in these technical docs have attributes or properties, as defined below.

This section defines how each content type is structured. For which source is canonical for each content type — and whether a page belongs on docs.optimism.io at all — see the [Content Guide](/op-stack/contribute/content-guide).

| Document type           | Purpose                                                                                                            | Examples                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| Overviews or Explainers | General introduction to a product or feature, provides a happy-path for readers                                    | [Superchain Explainer](https://docs.optimism.io/superchain/superchain-explainer)                                      |
| Guides                  | Explain what things are and how they work                                                                          | [Standard Bridge Guide](https://docs.optimism.io/app-developers/bridging/standard-bridge)                             |
| Tutorials               | Provide task-oriented guidance with step-by-step "learn by doing" instructions                                     | [Bridging ERC-20 tokens with viem](https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-bridge-erc20) |
| FAQs                    | Address frequently asked questions                                                                                 | [FAQ: OP Mainnet Security Model](https://docs.optimism.io/op-stack/security/faq-sec-model)                            |
| Troubleshooting         | List common troubleshooting scenarios and solutions                                                                | [Troubleshooting: Run a Node](https://docs.optimism.io/operators/node-operators/management/troubleshooting)           |
| Reference               | Provide deep, theoretical knowledge of the internal workings of a system, such as API endpoints and specifications | [Node and RPC Providers](https://docs.optimism.io/app-developers/tools/connect/rpc-providers)                         |

### Overviews (or Explainers)

Overviews or explainers provide a general introduction to a product or service and a happy path for readers on how to navigate a particular set of docs or related features. When done well, overviews and explainers accomplish two essential tasks for users:

1. **organize** the related set of documentation pages to keep developers from getting overloaded by too much information, and
2. **establish a 'happy path'** to direct developers to the right pages in the documentation set based on their user scenario or use case.

Tables work really well for overview pages, which can both organize page content and establish the happy path for specific developer use cases. Alternatively, headings (H2) can be used, organized by use case, user scenario, or directory page titles.

To maintain consistency, overviews should include all these items:

* overview of what the page will cover
* content organized into discrete sections, by use case, user scenario, or page titles
* clear headings for each section written in parallel style
* next steps section: links to related guides, tutorials, etc.

### Guides

Guides use simple language to explain concepts or complex features, such as what things are and how they work. They are great for on-boarding beginning or novice developers. For developer-focused guides, it is best practice to include illustrations, diagrams, and code samples whenever possible to help explain concepts.

To maintain consistency, guides should include all these items:

* overview of what the guide will cover
* guide content organized into discrete sections
* clear headings for each section written in parallel style
* one or more visual elements (e.g., images, screenshots, illustrations, and/or code samples)
* next steps section: links to related tutorials, other guides, troubleshooting, etc.

### Tutorials

Tutorials are task-oriented pages or videos that include practical, step-by-step instructions for completing a task, activity, or objective. Tutorials are more interactive and hands-on than other technical documentation, often including practical examples, exercises, and demonstrations to help developers learn by doing.

To maintain consistency, tutorials should include all of these items:

* overview of what the tutorial will cover, including context for what problem is being solved
* goals of the tutorial (i.e., what the developer will learn or the finish state)
* before you begin section (also known as prerequisites)
* list of steps involved in the task
* images, screenshots, or code samples (ideally, at least one of these for each step)
* next steps section: links to other tutorials, related guides, troubleshooting, etc.

When writing tutorials or quick starts, steps should be written in parallel style, as sentences with imperative verbs and not gerunds (ending in "ing").

> **Example:**
>
> * Step 1: **Create** Your Site
> * Step 2: **Choose** Your Framework
> * Step 3: **Visit** the Dev Environment

### FAQs

Whenever possible, we should avoid using FAQs due to their lack of readability and difficulty of maintenance.

FAQs address common questions developers have/might ask about a product, feature, or service. FAQs should be written from the developer's perspective. If there are more than two steps in the answer, use a numbered list. Place FAQs onto their own separate pages, whenever possible, and link to the FAQ from within the respective guide or tutorial.

To maintain consistency, FAQs should include all of these items:

* overview of what product or service the FAQ is about
* questions (usually H2 or H3, depending on page)
* answers (not a heading, usually normal paragraph text beneath the question)

The heading level for FAQs will vary based on if it's an FAQ-only doc or if FAQs are included as part of a larger document. In either case, try not to exceed H3 level when organizing the document.

**Example of a simple FAQ**

> **Does Optimism Support ERC-721?**
> Yes. We have complete and total support for ERC-721 standard.

**Example of an instructional FAQ**

> **How do I change my Optimism password?**
>
> 1. Select **Sites & Accounts** from the user account drop-down menu.
> 2. Click the **Account** tab.
> 3. Select **Change Password**.
> 4. Enter the information, and click **Save**.

Include a category heading when you need to group related FAQ content. Category headings are optional, but helpful, for longer FAQs.

### Troubleshooting guides

Troubleshooting guides list common problems a developer might encounter while using a product or service, identifies the symptoms, and offers solutions to these problems. It is important to accurately capture symptoms produced by the system or interface (e.g., error messages, unexpected page refresh/reload, spinning wheel, etc.), so developers know if their system response aligns with one of the common problems identified in the troubleshooting guide.

A troubleshooting guide should be limited to identifying common problems for one particular product or service.

To maintain consistency, troubleshooting guides should include all of these items:

* overview of what product or service the troubleshooting guide will cover
* common problem (usually H2 or H3, depending on page)
  * cause of problem
  * symptom of problem (system response, captured as image/screenshot)
* solution (step-by-step)
* next steps section: links to related tutorials, other guides, etc.

### Technical reference

Technical references provide deep, theoretical knowledge of the internal workings of a system. These often come in the form of requirements or system specifications developers need to run the product efficiently, so lists and tables, such as API endpoints and error codes are commonplace.
A technical reference page is usually quite long, so it is best practice to embed a table of contents (TOC) at the top of the page to help organize material for developers. From a usability perspective, this practice shows developers what will be covered in the reference in advance, and allows them to jump to a specific section, if desired.

To maintain consistency, technical references should include all these items:

* overview of what the reference will cover
* table of contents
* reference content organized into discrete sections, with parallel headings
* one or more visual elements (e.g., flow diagrams, illustrations, and/or code samples)
* suggestions for further reading (links spread throughout the reference doc)

Technical references often include more links throughout the document than other content types, often linking to other technical references, guides, tutorials, glossary definitions, etc. Since the purpose of technical reference material is to educate developers on a deeper level about the topic of their choosing, this is a common and expected practice and is a good indication of a strong technical reference.

## General formatting

### Fonts

Fonts in Optimism technical documentation are setup to follow brand guidelines established by marketing (e.g., heading fonts are different than body or paragraph font). Please do not change them.

### Bullets & unordered lists

Please use `*` instead of `-` for items in a list. This maintains consistency across the docs.

### Date & numbers

* Use the full month, day, year format for dates whenever possible. Do not abbreviate the month. In a form or when space is limited, use slashes in the format of month/day/year without any leading zeros.
  **Examples**: `January 10, 2014` or `2024/01/10`

* Spell out all numbers under 10. For numbers 10 and above, use the numeral.
  **Example**: CompanyX operates five nodes and plans to add 12 more.

### Abbreviations

* Use contractions with intention. Contractions can be used to create a conversational, informal tone, such as in FAQs or Tutorials. Avoid using contractions in UI labels (i.e. button names, page headers, etc), error messages/error codes, or interactive page elements.

* Avoid abbreviating common words. It is preferable to spell it out unless there are major space limitations, such as in a table.
  **Example**: `Use account` (not acct.) and `number` (not no.)

* Spell out acronyms the first time used on any given page. Then, abbreviate in parentheses afterward. Link users to the glossary, when applicable.
  **Example**: `Externally Owned Account (EOA)`

### Punctuation

* **Ampersand (&)** Only use "&" in headings where items are grouped or in proper names. Do not use in sentences.

* **Colon (:)** Use to introduce a list or series.

* **Commas (,)** Use a serial comma in lists of three or more items and use the oxford comma preceding the "and" before the last element in a list.
  **Example**: The developer built a node, social app, and DeFi app for Optimism.

* **Em dash (—)** Use to indicate a break in thought or a parenthetical comment. Do not add spaces around the em dash.
  **Example**: The developer graduated—with honors—from Optimism Bootcamp.

* **En dash (–)** Use to indicate a range or a continuation of a series. Use spaces on each side of the en dash.
  **Example**: `Pages 11 – 19` or `Mon – Fri` or `Nov 1 – 17`

* **Exclamation point (!)** Avoid. We do not use exclamation points in user assistance content. It is more appropriate for marketing and sales content, but not in the UI or technical documentation.

* **Hyphen (-)** Use to connect two words. No spaces are needed around the hyphen.
  **Example**: `developer-focused product` or `company-wide holiday`

* **Slash (/)** Avoid using as the slash is reserved for file names (see above). Use "or," "and," or "both" instead.


# Fault proof VM: Cannon
Source: https://docs.optimism.io/op-stack/fault-proofs/cannon

Learn about Cannon and its default operation as part of Optimism's Fault Proof Virtual Machine.

<NormativeSpec title="multithreaded Cannon fault proof VM specification" href="https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html" />

Cannon is an instance of a Fault Proof Virtual Machine (FPVM) that can be used as part of the Dispute Game for any OP Stack Blockchain.
The Dispute Game itself is modular, allowing for any FPVM to be used in a dispute.
However, Cannon is Optimism's default Fault Proof Virtual Machine (FPVM). Cannon has two main components:

* Onchain [`MIPS64.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/MIPS64.sol): EVM implementation to verify execution of a single MIPS instruction.
* Offchain `mipsevm`: Go implementation to produce a proof for any MIPS instruction to verify onchain.

The program that runs inside Cannon is the fault proof program, [kona-client](/releases/kona-client), compiled to a big-endian 64-bit MIPS (MIPS64) ELF binary.

<Info>
  Earlier generations of Cannon ran the Go fault proof program `op-program`: first compiled to 32-bit MIPS32 instructions and verified onchain
  by `MIPS.sol`, later compiled to MIPS64 and run on the 64-bit Cannon described on this page. Those op-program configurations back the legacy
  `CANNON` (game type 0) and `PERMISSIONED_CANNON` (game type 1) dispute games, and `op-program` has since
  reached end-of-support (see [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation)). Current dispute games use the
  `cannon-kona` (game type 8) configuration: kona-client running on the 64-bit Cannon.
  The [MIPS.sol reference](/op-stack/fault-proofs/mips) documents the retired 32-bit onchain contract.
</Info>

Note that Cannon is just one example of an FPVM that can be used to resolve disputes.

This documentation will go into detail about the subcomponents that make up the offchain Cannon implementation as a whole.
Additionally, we will explore the differences between Cannon and the onchain `MIPS64.sol`.
Now for simplicity, when referring to Cannon in this documentation, we are referring to the offchain implementation.

## Control flow

<img alt="Fault Proof Control Flow." />

The above diagram, recreated from the [OP Fault Proof System video](https://www.youtube.com/watch?v=nIN5sNc6nQM) by Clabby, predates the move to kona:
where it says `op-program`, read `kona-client`, which fills that role today. In it, we can see
that Cannon interacts with op-challenger and the fault proof program. However, this diagram is a simplification of the relationship between
op-challenger \<> Cannon, and kona-client \<> Cannon. In general, Cannon will not be run until an active fault dispute reaches the
execution trace portion of the bisection game. This does not occur until the participants in the active fault dispute game reach a
single L2 block state transition that they disagree on.

### op-challenger \<> Cannon

Once an active fault dispute game reaches a depth below attacking / defending L2 block state transitions, [op-challenger](/op-stack/fault-proofs/challenger) will run
Cannon to begin processing MIPS instructions within the FPVM. As part of processing MIPS instructions, Cannon will generate state
witness hashes, which are the commitment to the results of the MIPS instructions' computation within the FPVM. Now, in the bisection game, op-challenger will provide the generated hashes
until a single MIPS instruction is identified as the root disagreement between participants in the active dispute. Cannon will then
generate the witness proof, which contains all the information required to run the MIPS instruction onchain. Running this single MIPS
instruction onchain in `MIPS64.sol` will be used to definitively prove the correct post state, which will then be used to resolve the fault
dispute game.

### kona-client \<> Cannon

Once the execution trace bisection begins and Cannon is run, an Executable and Linkable Format (ELF) binary will be loaded and run within Cannon.
Within Cannon is the `mipsevm` that is built to handle the big-endian 64-bit MIPS instruction set (MIPS64 Release 1), as required by the
`mips64` compiler target. The ELF file contains MIPS instructions, where the code that has been compiled into MIPS instructions is kona-client.

kona-client is Rust code that is compiled to the `mips64-unknown-none` target and run within the Cannon FPVM. kona-client, whether run natively
or in Cannon, derives the state of the L2 from the data its companion [kona-host](/releases/kona-host) fetches for it. It is built such that the
same inputs will produce not only the same outputs, but the same execution trace. This allows all participants in a fault dispute game to run
kona-client such that, given the same L2 output root state transition, they can generate the same execution traces. This in turn generates the same
witness proof for the exact same MIPS instruction that will be run onchain.

Before `op-program` reached end-of-support, it filled this same role for the legacy game types: Go code compiled to MIPS instructions
(32-bit in the earliest generation, 64-bit later) with the same determinism property. Only the kona variants are maintained today.

## Overview of offchain Cannon components

Now, we will go over each major component that makes up Cannon. Components are grouped by what functionality is being performed for
Cannon, and may be correlated to one or more Go files. For brevity, each Go file will be explained at a high level, with the
most important features / considerations highlighted.

<img alt="Cannon Components Overview." />

### `mipsevm` state and memory

As mentioned previously, the `mipsevm` is 64-bit, which means the full addressable address range is `[0, 2^64-1]`. The memory layout
uses the typical monolithic memory structure, and the VM operates as though it were interacting directly with physical memory.

For the `mipsevm`, how memory is stored isn't important, as it can hold the memory within the Go runtime.
In this way, how memory is represented is abstracted away from the VM itself. However, it is important for memory to be represented
such that only small portions are needed in order to run a MIPS instruction onchain. This is because it is infeasible to represent the
entire 64-bit memory space onchain due to cost. Therefore, memory is stored in a binary Merkle tree data structure, with the implementation
spread across [`memory.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/memory/memory.go) and
[`page.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/memory/page.go).
The tree has a fixed-depth of 59 levels, with leaf values of 32 bytes each. This spans the full 64-bit address space: `2**59 * 32 = 2**64`.
Each leaf contains the memory for that part of the tree.

`memory.go` defines the data structure, `Memory`, which tracks memory nodes and pages. A memory node holds the calculated Merkle
root of a subtree within the memory binary Merkle tree, where the 'location' of the node is determined by its generalized index.
The index calculated for a Merkle root follows the
[generalized Merkle tree index specification](https://github.com/ethereum/consensus-specs/blob/dev/ssz/merkle-proofs.md#generalized-merkle-tree-index).

`page.go`, as the name implies, defines memory pages. Each `Page` is 4096 bytes, which is also specified as the minimum page allocation
size for the program running inside the VM. A `Page` represents the lowest depths of the memory binary Merkle tree, and `page.go` performs a similar role
to `memory.go`, calculating Merkle roots for each level of the tree.

Nodes in this memory tree are combined as: `out = keccak256(left ++ right)`, where `++` is concatenation,
and `left` and `right` are the 32-byte outputs of the respective subtrees or the leaf values themselves.
Individual leaf nodes are not hashed.

In both `memory.go` and `page.go`, there are a few optimizations designed to reduce the computationally expensive Merkle root calculations.
One such optimization is that the Merkle root of zeroed-out regions of memory are calculated for each depth. This means the tree is efficiently allocated,
since the root of fully zeroed subtrees can be computed without actually creating the full-subtree:
`zero_hash[d] = hash(zero_hash[d-1], zero_hash[d-1])`, until the base-case of `zero_hash[0] == bytes32(0)`.
So, pre-calculating zeroed Merkle roots initially allows unused memory regions to be cached. Additionally, non-zero Merkle roots
are cached in both `memory.go` and `page.go`, and used so long as the memory region the Merkle root covers has not been written to.
Otherwise, the cache is invalidated, which requires the Merkle root to be calculated over its entire subtree. Another optimization
specifically in `memory.go` is caching the last two pages that have been used. Two pages are cached because the `mipsevm` typically reads
instructions from one page while performing loads and stores against another.

Another important implementation detail is that the endianness of the `mipsevm`, which is the ordering of bytes in a word, is Big-Endian.
Word-sized reads and writes go through Big-Endian byte-order helpers (see
[`arch64.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/arch/arch64.go)), so the internal `mipsevm` always
handles Big-Endian words regardless of the endianness of the machine running Cannon.
Endianness is also an important factor for the onchain `MIPS64.sol`, where the EVM itself is Big-Endian. Therefore, `MIPS64.sol` does not have to
do any endianness swapping and can assume all data uses Big-Endian ordering. This reduces complexity within the smart contract itself.

The last major component is located in [`state.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/multithreaded/state.go).
The `State` struct in `state.go` holds all the execution state that is required for the `mipsevm`.
The information stored is largely identical to the packed VM execution state that `MIPS64.sol` operates on
(see the [Cannon FPVM specification](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs#state)). The key differences are:

* Instead of storing just the memory Merkle root, there is a `Memory` struct pointer for the binary Merkle tree representation of the entire 64-bit memory space.
* There is an optional `LastHint` bytes variable, which can be used to communicate a Pre-image hint to avoid having to load in multiple prior Pre-images.

Because Cannon is multithreaded, the `State` struct also tracks the stacks of thread states and the currently active thread; the packed
onchain state commits to these thread stacks as well.
Cannon supports several [versioned state formats](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/versions/version.go),
covering both the legacy 32-bit VMs and the 64-bit multithreaded VMs; the kona-client prestate is built with the latest 64-bit
multithreaded version.

#### Generating the witness proof

Cannon handles two major components in the dispute game: generating state witness hashes for op-challenger to post during the execution trace
bisection game, and generating the witness proof once a single MIPS instruction is reached as the root of disagreement in the fault dispute game.
The witness proof, as mentioned previously, contains all the necessary information for `MIPS64.sol` to be able to run the same instruction onchain,
and derive the post state that will be used to resolve the fault dispute game. The post state of the instruction run by `MIPS64.sol` should be
exactly the same as the post state generated by the `mipsevm`.

The top-level [`witness.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/witness.go)
in `cannon/cmd` initiates the witness proof generation. The internal
[`witness.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/witness.go) in `cannon/mipsevm` defines the
struct that holds all the relevant information for the particular MIPS instruction, which is encoded as the `MIPS64.sol` calldata.

Additionally, if a Pre-image is required for the MIPS
instruction, `witness.go` will communicate the relevant Pre-image key and offset to op-challenger so that it can be posted onchain
to `PreimageOracle.sol`.

An important note about generating the witness proof: it is imperative that all relevant information about the instruction to be run
onchain is generated **before** the `mipsevm` execution state changes as a result of processing the MIPS instruction. Otherwise, if the
witness proof is generated after running the instruction offchain, the state that will be encoded will be the post state.

### Loading the ELF file

Once the execution trace portion of the bisection game begins, the ELF file containing kona-client compiled into MIPS instructions will
be run within Cannon. However, getting kona-client into Cannon so that it can be run requires
a binary loader. The binary loader is composed of [`load_elf.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/load_elf.go)
and [`load.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/program/load.go). `load_elf.go` parses
the top-level arguments and reads and loads the ELF binary such that it can be run by Cannon.

`load.go` is responsible for actually parsing the headers of the ELF file, which among other information specifies what program segments
exist within the file and where they are located in memory. The loader uses this information to instantiate the execution state
for the `mipsevm` and load each segment into memory at the expected location. As part of instantiating the execution
state, `load.go` sets the values of `PC` and the initial heap location, and
[`patch.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/program/patch.go) sets up the initial stack
frame near the top of program memory, including the arguments required by the program's runtime above the stack pointer location.

While loading the ELF file into Cannon, [`metadata.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/program/metadata.go)
is used to parse all the symbols stored in the ELF file. Understanding which ELF symbols exist and at which regions of memory
they are located is important for other functionality, such as understanding if the current `PC` is running within a specific function.

A key design decision in both the onchain and offchain `mipsevm` implementations is that neither implementation
has access to a kernel. This is primarily due to the limitations within the EVM itself, and since the offchain Cannon
implementation must match functionality exactly with its onchain counterpart, kernel access is also not available within Cannon. This means that the VMs
cannot replicate behavior that would otherwise be performed by a kernel 1:1, which primarily impacts system calls (syscalls).
The syscall instruction instead simulates a minimal subset of a Linux kernel: just enough to allocate memory, read from and write to
certain file descriptors, and exit. Beyond that, a defined set of syscalls, such as memory management and signal handling calls, are
implemented as no-ops, and any syscall outside the supported set is unsupported and halts the VM. The program run inside Cannon must be
built to tolerate this minimal environment.

### Instruction stepping

Once the MIPS binary is loaded into Cannon, we can then begin to run MIPS instructions one at a time.
[`run.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/run.go) contains the top-level
code responsible for stepping through MIPS instructions. Additionally, before each MIPS instruction, `run.go` will determine whether
separate actions need to be performed. The actions to be performed are configured by the user, and can include logging information,
stopping at a certain instruction, taking a snapshot at a certain instruction, or signaling to the VM to generate the witness proof.
The action(s) to be performed are instantiated and checked by [`matcher.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/cmd/matcher.go),
which generates a match function that triggers when the configured step pattern matches, either a specific step or a step interval.

Within `run.go`, the `StepFn` is the wrapper that initiates the MIPS instruction to be run.
[`instrumented.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/multithreaded/instrumented.go) implements `Step` as the
interface to be initiated for each MIPS instruction. Additionally, `instrumented.go` handles encoding information for the witness proof
and Pre-image information (if required for the MIPS instruction).

### `mips.go`

[`mips.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/multithreaded/mips.go), together with the shared
instruction handling in [`mipsevm/exec`](https://github.com/ethereum-optimism/optimism/tree/develop/cannon/mipsevm/exec), implements all the required MIPS
instructions, and also tracks additional memory access for the instruction currently being run.
This is important to make sure that the second memory proof is encoded correctly for instructions that use it, such as loads, stores, and
certain syscalls. The full list of instructions supported can be found in the
[`mipsevm` README](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/README.md).

#### `mips.go` vs. `MIPS64.sol`

The offchain `mips.go` and the onchain Cannon `MIPS64.sol` behave similarly when it comes to executing MIPS64 Release 1 instructions.
In fact, they must produce **exactly the same results** given the same instruction, memory, and register state.
Consequently, the witness data is essential to reproduce the same instruction onchain and offchain.
However, there are differences between the two:

1. A single instruction will be run onchain in `MIPS64.sol`, whereas the offchain `mips.go` will run all MIPS instructions for all state transitions in the disputed L2 state.
2. The `mipsevm` contains the entire 64-bit monolithic memory space, is responsible for maintaining the memory state based on the results of MIPS instructions, and generates the memory binary Merkle tree, Merkle root, and memory Merkle proofs. `MIPS64.sol` is mostly stateless, and does not maintain the full memory space. Instead, it only requires the memory Merkle root, and up to two memory Merkle proofs: 1 for the instruction and 1 for potential load, store, or certain syscall instructions.
3. Unlike `MIPS64.sol`, `mips.go` is responsible for reading Pre-images from the Pre-image server, and optionally writing hints to it.

### PreimageOracle interaction

As mentioned previously, Cannon is responsible for setting up all state that may be required to run an instruction in `MIPS64.sol`.
Cannon is also responsible for interacting with the Pre-image server, and directing op-challenger to provide Pre-images to
the onchain `PreimageOracle.sol` if necessary for the instruction that will be run in `MIPS64.sol`.

The Pre-image server is [kona-host](/releases/kona-host): `run.go` launches it as a sub-process (the host command is passed to
`cannon run` after a `--` separator) and it serves the chain data that kona-client requests during execution.
`mips.go` communicates with the Pre-image server when reading Pre-images as part of MIPS syscall instructions,
as well as hinting to the Pre-image server.

The OP Stack fault proof [Pre-image Oracle specs](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs#pre-image-oracle)
define the ABI for communicating pre-images.

This ABI is implemented by the VM by intercepting the `read`/`write` syscalls to specific file descriptors. See [Cannon VM Specs](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs#io) for more details.

Note that although the oracle provides up to 32 bytes of the pre-image,
Cannon only supports reading at most 8 bytes at a time, to unify the memory operations with 64-bit load/stores.

## Further Reading

* [cannon component hub](/op-stack/components/cannon)
* [Cannon FPVM Specification](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs)
* [Cannon overview docs in the monorepo](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/docs/README.md)
* [Merkle Proofs Specification](https://github.com/ethereum/consensus-specs/blob/dev/ssz/merkle-proofs.md)
* [Executable and Linkable Format (ELF)](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format)
* [Keys in Mordor Summit: Cannon & Fault Proofs](https://www.youtube.com/watch?v=ASLMj70V0Ao)


# OP-Challenger explainer
Source: https://docs.optimism.io/op-stack/fault-proofs/challenger

Learn about OP-Challenger and how it operates within the OP Stack's Fault Proof System.

<NormativeSpec title="honest challenger specification" href="https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html" />

The `op-challenger` operates as the *honest actor* in the fault dispute system and defends the chain by securing the `OptimismPortal` and ensuring the game always resolves to the correct state of the chain. For verifying the legitimacy of claims, `op-challenger` relies on a synced, trusted rollup node as well as a trace provider (e.g., [Cannon](/op-stack/fault-proofs/cannon)).

Specifically, `op-challenger` performs the following actions:

* monitors and interacts with dispute games
* defends valid output root proposals
* challenges invalid output root proposals
* assists `op-proposer` by resolving claims and games once chess clocks expire
* claims paid out bonds for both the challenger and proposer

## Architecture

This diagram illustrates how `op-challenger` monitors dispute games, defends valid proposals, and challenges invalid ones. It also shows its interaction with the `op-proposer` in resolving claims.

```mermaid theme={null}
graph TD;
    OP[OP-Challenger] -->|Monitors| DG[Dispute Games]
    OP -->|Defends| ORP[Valid Output Root Proposals]
    OP -->|Challenges| IORP[Invalid Output Root Proposals]
    OP -->|Assists| OPP[OP-Proposer]
    OPP -->|Resolves Claims| DG
    DG -->|Claims Paid| Bonds[Bonds for Challenger and Proposer]

    classDef default fill:#00,stroke:#FF0420,stroke-width:2px;
```

<Info>
  The `op-challenger` docker container runs the `cannon` VM with a fault-proof program as a sub-process to generate game trace data. Since the Karst upgrade, the respected game type is `cannon-kona`, which uses `kona-host`. The legacy `cannon` game type uses `op-program host`, which reached end-of-support at the Karst upgrade. See [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation).
</Info>

## Fault detection responses

`op-challenger` assesses each claim's validity, countering only those deemed invalid, following this logic:

1. If the trusted node agrees with the output, `op-challenger` takes no action. An honest challenger does nothing because there are no claims it disagrees with. It continues to monitor the game in case someone posts a counter-claim to the valid root claim, in which case the challenger will participate in the game to defend the proposal.
2. If the trusted node disagrees, `op-challenger` posts a counter-claim to challenge the proposed output. In contrast to the above scenario, an honest challenger aims to delete any output roots that its trusted node disagrees with in order to claim the bond attached to it. The honest challenger assumes that their rollup node is synced to the canonical state and that the fault proof program is correct, so it is willing to put its money on the line to counter any faults.

## Fault dispute game responses

`op-challenger` iterates through claims as stored in the contract, ensuring ancestors are processed before their descendants. For each claim, the honest challenger determines and tracks the set of honest responses to all claims, regardless of whether that response already exists in the full game state.

### Root claim

The root claim is considered to be an honest claim if and only if it has a [state witness Hash](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html?utm_source=op-docs\&utm_medium=docs#claims) that agrees with the honest challenger's state witness hash for the root claim.

### Counter claims

When a new claim is made in a dispute game, the honest challenger processes it and performs a response. The honest challenger should counter a claim if and only if:

1. The claim is a child of a claim in the set of honest responses
2. The set of honest responses contains a sibling to the claim with a trace index greater than or equal to the claim's trace index

<Info>
  This implies the honest challenger never counters its own claim, since there is at most one honest counter to each claim, so an honest claim never has an honest sibling.
</Info>

### Possible moves

The challenger monitors each game as new claims are added and reacts according to the [honest actor algorithm](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html?utm_source=op-docs\&utm_medium=docs) to defend valid proposals and invalidate invalid proposals. A **move** is a challenge against an existing claim and must include an alternate claim asserting a different trace (e.g., attack, defend, or step).

<br />

<Image alt="Challenger Moves flow" />

<Info>
  See the [specs](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html) for the full scope of the honest actor algorithm.
</Info>

## Resolution

When one side of a `FaultDisputeGame`'s chess clock runs out, the honest challenger's responsibility is to resolve each claim in the game by calling the `resolveClaim` function on the `FaultDisputeGame` contract. Once the root claim's subgame is resolved, the challenger then finally calls the `resolve` function to resolve the entire game.

The `FaultDisputeGame` does not put a time cap on resolution - because of the liveness assumption on honest challengers and the bonds attached to the claims they've countered, challengers are economically motivated to resolve the game quickly, thereby liquidating their funds and securing rewards.

## Next steps

* Ready to get started? Read our guide on how to [configure `op-challenger` on your OP Stack chain](/chain-operators/guides/configuration/op-challenger-config-guide).
* For more info about how `op-challenger` works under the hood, [check out the specs](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html?utm_source=op-docs\&utm_medium=docs).

## FAQs

### If I don't have a blob archiver with access to historical data, can I lose the game?

Most likely, yes. If nobody has access to the historical data. All the honest actors work together without needing to coordinate offense because they're all trying to play the same moves. So, if there's only one honest actor that lacks a blob archiver, and the actor gets pushed down to the bottom half of the game (\~ 32 claims deep in the game), then challenger would log errors and wouldn't be able to respond without the blob archiver. The actor would have 3.5 days on their side of the game to address the problem by switching to a beacon node that does have blobs, and could then proceed as usual.

Note: An actor would only be pushed down to the bottom half of the game if the block being disputed is older than the blob retention period (\~18 days).  If valid proposals are resolving regularly, this is not possible because each valid proposal becomes the starting point for newly created dispute games. So if there are regular valid proposals, then only \~3.5 days worth of blocks are normally being disputed, which is well within the retention period.

### How many CPUs should I run for challenger to work efficiently?

The default `--max-concurrency` setting suits most operators. Increase it if the challenger lags, or decrease it if it overloads with requests.

### How much ETH do you need to challenge in a game?

The honest challengers need to have more combined ETH than the attacker, or they may run out of funds and be unable to respond to games (requiring the security overrides to be used to protect funds). So, there's no strict amount challengers need to have, but here are some general guidelines chain operators can use to estimate:

* Generally speaking, a minimum to play 1 game = bond amount \* game max depth + gas costs for each move
* To play one game all the way down to the final step call in a single "chain" costs just over 631.2 ETH in total, so about 315.6 ETH per "side".

### What is the bond? What is the bond's role in the FP system?

Each *claim* pays a bond, including the root claim created when the game is created (thus the bond is paid when the game is created). Every time a new claim posts to the game, an additional bond must be paid based on the depth of the claim being posted. It is not necessary to prepay bonds (i.e., its not like staking). Instead, the bond amount is sent as the value of the transaction when calling `attack` or `defend` on `FaultDisputeGame` or calling `create` on `DisputeGameFactory`.

Claims that are found to be correct have their bonds refunded. Claims that are found to be incorrect have their bonds paid to the account that posted the left-most uncountered child claim of the incorrect claim. More importantly, the bond for invalid claims is paid to whoever successfully counters the claim, but its setup so that the bond is only ever paid to a single person and never shared.

* There is a delay on claiming bonds of 7 days after the claim is resolved.
* The 7-day period restarts each time a new bond from that game is paid to the same user. Typically this means that bonds are claimable 7 days after the game is resolved.

The calculation for the bond amounts are hard-coded in the [`FaultDisputeGame` contract](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/FaultDisputeGame.sol#L936-L977), and there's a `getRequiredBond` method on the contract that suggests what bond to use.

### How much ETH is required for the challenger bond?

The dispute game factory has the bond value set. To ensure correct game outcomes, the combined funding of all honest actors must be more than the funding available to an attacker. Otherwise the attacker can just post so many claims that the honest actors run out of funds and can no longer counter them. There isn't a fixed amount that guarantees this, so chain operators should have significant funds available at short notice to respond to claims.

Given the guardian can intervene and reallocate bond payments if needed, attackers who try to outspend the honest actors are guaranteed to lose their funds because the guardian will just intervene and pay all their bonds to the honest actors which is a very strong disincentive against trying to win games by outspending people.


# Fault proofs explainer
Source: https://docs.optimism.io/op-stack/fault-proofs/explainer

Learn about the OP Stack's Fault Proof System.

<NormativeSpec title="fault proof specification" href="https://specs.optimism.io/fault-proof/index.html" />

<Info>
  **Learn the OP Stack — stop 11 of 13.**
  You've proven and finalized a withdrawal yourself. This page adds why
  that process can be trusted: permissionless proposals about the state
  of the chain, and permissionless challenges to them. When you're done,
  continue to
  [OP Stack interoperability explainer](/op-stack/interop/explainer).
</Info>

Fault Proofs are an important part of an Optimistic Rollup system.
Users withdraw ETH and tokens from OP Stack chains like OP Mainnet by submitting a withdrawal proof that shows the withdrawal was actually included in the OP Stack chain.
Fault Proofs allow users to permissionlessly submit and challenge the proposals about the state of an OP Stack chain that are used to prove withdrawals.

On June 10, 2024, Fault Proofs were officially added to the OP Stack and were activated on OP Mainnet.
This Fault Proofs upgrade moves the OP Stack closer to technical decentralization by:

* allowing anyone to make proposals about the state of the L2
* allowing anyone to challenge proposals made by other users
* allowing users to send messages from L2 to L1 without the need for a trusted third party
* allowing users to trigger withdrawals from L2 to L1 without the need for a trusted third party
* introducing a modular fault proof design that can easily integrate additional proving mechanisms

Although the fault proof game is permissionless, the Optimism Security Council acting as the [Guardian](/op-stack/protocol/privileged-roles#guardian) role provides a backstop in case of a failure in the fault proof game.
The Guardian's safety hatches, including the delay period on proposals and the ability to fall back to a permissioned game, are described in the [OP Stack security model](/op-stack/security/faq-sec-model#fault-proofs).

## Permissionless proposals

"Proposals" or "State Proposals" are claims about the state of an OP Stack chain that are submitted to Ethereum through the `DisputeGameFactory` contract.
Proposals can be used for many things but are most commonly used by end-users to prove that they created a withdrawal on an OP Stack chain.
With the Fault Proofs upgrade to the OP Stack, proposals become permissionless and can be submitted by anyone.

See the permissionless fault proofs diagram below for more details:

<img alt="Permissionless Fault Proofs flow" />

## Permissionless challenges

Because anyone can submit a proposal, it's important that invalid proposals can be challenged.
In [Optimistic Rollups like OP Stack Chains](/op-stack/protocol/overview) there is a \~1 week challenge period during which users can challenge a proposal if they believe it to be incorrect.
With the Fault Proofs upgrade to the OP Stack, challenges become permissionless and can be submitted by anyone.
Any user can run a node for the OP Stack chain in question and use the `op-challenger` tool to participate in the dispute process.

## Modular design and multi-layer security

The OP Stack Fault Proof System is [modular in design](/op-stack/fault-proofs/fp-components#system-design--modularity) and lays the groundwork for achieving a "multi-proof" system. This allows the OP Stack to support multiple proof systems alongside the initial [Cannon](/op-stack/fault-proofs/cannon) proof system.
With multiple proof systems in place, the OP Stack can be more resilient to potential attacks and bugs in any one proof system.

Additionally, the following [security safeguards](/op-stack/fault-proofs/fp-security) have been built around the game, as follows:

* An off chain monitoring system has been set up to monitor all proposed roots and ensure they align with the correct state. See [`op-dispute-mon`](https://github.com/ethereum-optimism/optimism/blob/develop/op-dispute-mon/README.md?plain=1) for more details.
* After a root is finalized through a game, an additional delay called the "airgap window" has been added before withdrawals can occur. During this period, the `GUARDIAN` role can reject the root.
* A contract called `DelayedWETH` has been set up to hold the bonds and only allow payouts after a delay, so that bonds can be redirected towards the correct recipient in the case that a game resolves incorrectly.

## Next steps

* Ready to get started? Review the [FP Components](/op-stack/fault-proofs/fp-components) to learn how the different components work together to enhance decentralization in the Optimism ecosystem.
* See the [Fault Proof Security](/op-stack/fault-proofs/fp-security) to understand changes to `OptimismPortal` and `FaultDisputeGame` contracts.
* For more info about how the FP system works under the hood, [check out the specs](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs).

## FAQs

### How many steps/transactions are required to settle a dispute (worst-case scenario)?

The maximum depth of a game is 73, but there can be any number of claims and counter-claims within a dispute game.
Due to the permissionless structure where many different actors can participate in the same game, a single claim may be countered by any number of different counter-claims, effectively combining multiple disputes into a single game.

### Are there any dependencies to consider when proposing a new state root (in the event of sequencer and proposer failure)?

Users can complete the full withdrawal cycle without depending on any privileged action.
The Guardian role can override the system by pausing withdrawals, blacklisting games, or reverting to a permissioned system.
As a result, the trust assumption is reduced to requiring only that the Guardian role does not act to intervene, inline with the stage 1 requirements.

### Since the roles of proposer and challenger will be open to everyone, are guides available outlining the best practices for running them?

It's not expected that normal users run `op-proposer` to regularly propose output roots.
Users would generally just propose a single output root if they need to withdraw and the chain operator isn't proposing outputs for them via direct calls to the `DisputeGameFactory` via Etherscan.

<Info>
  The [`create-game`](https://github.com/ethereum-optimism/optimism/tree/develop/op-challenger#create-game) subcommand of `op-challenger` is **for testing purposes only** and should not be used in production environments. It is not intended as a replacement for proper `op-proposer` infrastructure.
</Info>

For detailed guidance on running `op-challenger`, see the [OP-Challenger explainer](/op-stack/fault-proofs/challenger) and [how to configure challenger for your chain](/chain-operators/guides/configuration/op-challenger-config-guide).

### How much ETH should a chain operator put aside to operate the Fault Proof System?

The nominal operating cost of running FPs (i.e., assuming no invalid proposals or malicious actors) will depend on the initial bond set for the `FaultDisputeGame` and the frequency of posting proposals.
Assuming OP Mainnet parameters, where proposals will be posted hourly, that's 0.08 ETH per hour.
Assuming a 7 day dispute window, you'll need roughly 14 ETH (including gas costs) to make proposals.
If chains are using the similar FP deploy configs as OP Mainnet, it's recommended to stick to a 0.08 ETH initial bond.

However, the capital requirements for operating a FP chain in itself are much larger than 14 ETH.
An operator that secures their chain using FPs must be willing to stake a lot of ETH to secure the chain.
One may decide the capital requirements aren't worth it, and use only a Permissioned FP system.
The capital requirements will be improved in the later stages of Fault Proofs to make it more feasible for smaller chains.

### How large are the bonds expected to be needed to sustain and win a dispute?

The bonds are sized based on the anticipated cost to post a counter-claim as well as to deter spamming invalid claims.
As an example, on OP Sepolia, the game [`0xcf8f181497DAD07277781517A76cb131C54A1BEE`](https://sepolia.etherscan.io/address/0xcf8f181497DAD07277781517A76cb131C54A1BEE) shows the escalating bond sizes.
The list-claims subcommand of op-challenger can also provide a good view of the claims in the game:

```
./op-challenger/bin/op-challenger list-claims --l1-eth-rpc <SEPOLIA_L1> --game-address 0xcf8f181497DAD07277781517A76cb131C54A1BEE
```

See the [specs](https://specs.optimism.io/fault-proof/stage-one/bond-incentives.html?utm_source=op-docs\&utm_medium=docs) for more details.


# FP system components
Source: https://docs.optimism.io/op-stack/fault-proofs/fp-components

Learn about Fault Proof System components and how they work together to enhance decentralization in the Optimism ecosystem.

<NormativeSpec title="fault proof specification" href="https://specs.optimism.io/fault-proof/index.html" />

This page explains the fault proof system components and how they work together to enhance decentralization in the Optimism ecosystem.

The Fault Proof System is comprised of three main components: a Fault Proof Program (FPP), a Fault Proof Virtual Machine (FPVM), and a dispute game protocol.
The system is designed to eventually enable secure bridging without central fallback.
The modular design of the Fault Proof System lays the foundation for a multi-proof future, inclusive of ZK proofs, and significantly increases the opportunities for ecosystem contributors to build alternative fault proof components to secure the system.

<Info>
  Visit the [Immunefi bug bounty page](https://immunefi.com/bounty/optimism/) for details on testing and helping to build a robust fault proof system.
</Info>

## System design & modularity

The Fault Proof System is comprised of three main components: a Fault Proof Program (FPP), a Fault Proof Virtual Machine (FPVM), and a dispute game protocol.
These components will work together to challenge malicious or faulty activity on the network to preserve trust and consistency within the system.
See the video below for a full technical walkthrough of the OP Stack's first fault proof system.

<iframe title="Walkthrough: OP Stack Fault Proof System Alpha Release" />

The OP Stack's unique, modular design allows the decoupling of the FPP and FPVM, resulting in the following:

* development of multiple proof systems, unique dispute games, and a variety of FPVMs in the future.
* custom-built Fault Proof Systems comprised of any combination of these isolated components—including validity proofs, attestation proofs, or ZKVM.
* dispute games in the dispute protocol backed by multiple security mechanisms.

## Fault proof program

The Fault Proof Program (FPP) is one of the modules in the OP Stack's fault proof system.
It is a combination of both the consensus and execution "parts" of the protocol in a single process. This means Engine API calls that would normally be made over HTTP are instead made as direct method calls to the execution client code.
The default for this system component is `kona-client`, a Rust implementation combining `kona-node` and `op-reth`. Its predecessor `op-program` (a combination of `op-geth` and `op-node`, written in Go) has reached end-of-support and does not support the now-active Karst hardfork. See [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation).
These both implement a fault proof program that runs through the rollup state-transition to verify an L2 output from L1 inputs. This verifiable output can then resolve a disputed output on L1.

The FPP is designed so that it can be run in a deterministic way such that two invocations with the same input data will result in not only the same output, but the same program execution trace. This allows it to be run in an onchain VM as part of the dispute resolution process.

All data is retrieved via the [Preimage Oracle API](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs#pre-image-oracle). The preimages could be provided via the FPVM when onchain or by a native "host" implementation that can download the required data from nodes via JSON-RPC requests. For `kona-client`, that native host implementation is `kona-host`, and it doesn't run as part of the onchain execution. Basically, the fault proof program has two halves: the "client" Fault Proof Program part covered in this section and the "host" part used to fetch required preimages. (The end-of-support `op-program` followed the same client/host split.)

## Fault proof virtual machine

The Fault Proof Virtual Machine (FPVM) is one of the modules in the OP Stack's fault proof system.
The FPVM is tasked with lower-level instruction execution. The FPP needs to be emulated. The VM requirements are low: the program is synchronous, and all inputs are loaded through the same pre-image oracle, but all of this still has to be proven in the L1 EVM onchain.
To do this, only one instruction is proven at a time. The bisection game will narrow down the task of proving a full execution trace to just a single instruction. Proving the instruction may look different for each FPVM, but generally it looks similar to Cannon, which proves the instruction as follows:

* To execute the instruction, the VM emulates something akin to an instruction-cycle of a thread-context: the instruction is read from memory, interpreted, and the register-file and memory may change a little.
* To support the pre-image oracle, and basic program runtime needs like memory-allocation, the execution also supports a subset of linux syscalls. Read/write syscalls allow interaction with the pre-image oracle: the program writes a hash as request for a pre-image, and then reads the value in small chunks at a time.

OP Stack's modularity decouples the Fault Proof Program (FPP) from the Fault Proof Virtual Machine (FPVM) to enable next-level composability and efficient parallelized upgrades to both components. The FPP (client-side) that runs within the FPVM is the part that expresses the L2 state-transition, and the interface between FPVM and FPP is standardized and documented in the [specs](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs).

Through this separation, the VM stays ultra-minimal: Ethereum protocol changes, like EVM op-code additions, do not affect the VM. Instead, when the protocol changes, the FPP can simply be updated to import the new state-transition components from the node software. Similar to playing a new version of a game on the same game console, the L1 proof system can be updated to prove a different program.

[Cannon](/op-stack/fault-proofs/cannon) is the default FPVM used in all disputes. [MIPS](/op-stack/fault-proofs/mips) is the onchain smart contract implementation of Cannon that can be implemented due to the modularity of the dispute game.

## Dispute game protocol

In the Dispute protocol, different types of dispute games can be created, managed, and upgraded through the [DisputeGameFactory](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/DisputeGameFactory.sol#L24).
This opens the door to innovative features, like aggregate proof systems and the ability to expand the protocol to allow for disputing things apart from the state of L2, such as a `FaultDisputeGame` geared towards onchain binary verification.

A dispute game is a core primitive to the dispute protocol. It models a simple state machine, and it is initialized with a 32 byte commitment to any piece of information of which the validity can be disputed.
They contain a function to resolve this commitment to be true or false, which is left for the implementer of the primitive to define. Dispute games themselves rely on two fundamental properties:

* Incentive Compatibility: The system penalizes false claims and rewards truthful ones to ensure fair participation.
* Resolution: Each game has a mechanism to definitively validate or invalidate the root claim.

The standard is the bisection game. This is a specific type of dispute game, and the first game built in the OP Stack's dispute protocol.
We bisect over output roots (which each correspond to single L2 blocks), until we get to a single block `n -> n+1` state transition. Then, we bisect over a single block state transition's execution trace as described before. This is an optimization to reduce the runtime of the off-chain VM.
After bisection has reached commitments to the state at individual trace instructions, the `FaultDisputeGame` executes a single instruction step on chain using a generic VM.
The VM's state transition function, which we'll call `T`, can be anything, so long as it adheres to the form `T(s, i) -> s'`, where `s` = the agreed upon prestate, `i` = the state transition inputs, and `s'` = the post state.

The first full implementation of the VM generic in the bisection game includes a single MIPS thread context on top of the EVM to execute a single instruction within an execution trace generated by `Cannon` and the fault proof program (originally `op-program`, which has since reached [end-of-support](/notices/archive/op-geth-deprecation); current games use `kona-client`).

## Next steps

* For more detail on Cannon and its default operation as part of Optimism's Fault Proof Virtual Machine, see [Cannon FPVM](/op-stack/fault-proofs/cannon).
* For a detailed walk-thru of significant changes to Fault Proof Mainnet, see [FP Security](/op-stack/fault-proofs/fp-security).
* For detailed information about the entire FP program, FP virtual machine, and dispute game, see the [specs](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs).


# Fault proofs security
Source: https://docs.optimism.io/op-stack/fault-proofs/fp-security

Learn about changes to the security model for the Fault Proofs System.

<Info>
  Source code for Fault Proof contracts approved by Optimism Governance can be found [here](https://github.com/ethereum-optimism/optimism/tree/op-contracts/v1.5.0) (as of `op-contracts/v1.5.0`).
</Info>

This page details changes to the security model of the OP Stack with the introduction of the Fault Proof upgrade.
The most significant change introduced by the Fault Proof upgrade is the modification of the `OptimismPortal` to reference the `DisputeGameFactory` instead of the permissioned `L2OutputOracle`.

* The `DisputeGameFactory` contract generates `FaultDisputeGame` contract instances that each act as a host to a proposal about the state of the OP Stack chain at a given block number.
* Unlike the `L2OutputOracle`, the `DisputeGameFactory` contract offers users the ability to permissionlessly play "fault dispute games" in which the correctness of the proposal is determined programmatically.

## Security model

Fault Proof is a large contract upgrade that introduces a number of novel components.
Given the relative complexity of these novel components, the approach to security for FPM has been to limit the blast radius of potential bugs to very specific contracts and fallback mechanisms that can be easily audited.

### Handling invalid game results

All of the security mechanisms put in place generally revolve around the possibility that a `FaultDisputeGame` contract may incorrectly finalize an invalid game result.
There are two variations of this:

1. Resolving that an invalid proposal is valid potentially leading to stolen funds, and
2. Resolving that a valid proposal is invalid causing liveness delays or failures.

Both cases would cause honest challengers to lose bonds (unless the `Guardian` stepped in). Potential impact is managed through the introduction of a number of safeguards within the `OptimismPortal` and `FaultDisputeGame` contracts.

### Safeguards within `OptimismPortal`

The `OptimismPortal` contract includes various security mechanisms that allow the `Guardian` and `SystemOwner` roles to collaborate to prevent invalid proposals from impacting withdrawals.

* The `SystemOwner` can replace the `Guardian` address.
* The `Guardian` can trigger the global pause mechanism found in the original system.
* The `Guardian` can "blacklist" specific `FaultDisputeGame` contracts that resolve incorrectly.
* The `Guardian` can change the respected type of `FaultDisputeGame` contract in the case that an entire class of `FaultDisputeGame` contracts is found to have critical bugs. If desired, the `Guardian` can also choose to revert to a `PermissionedDisputeGame` contract that only allows specific roles to submit and challenge proposals.

### Safeguards within `FaultDisputeGame`

The `FaultDisputeGame` contracts store bonds within a `DelayedWETH` contract that is managed by the `SystemOwner`. Withdrawals from the `DelayedWETH` contract are delayed which gives the `SystemOwner` the ability to manually recover from situations in which bonds would be incorrectly distributed. This delay is set to 7 days on OP Mainnet to give the `SystemOwner` or `Guardian` sufficient time to respond to potential security concerns.

### Safeguards within `DelayedWETH`

* The `SystemOwner` can replace the `Guardian` address.
* The `SystemOwner` can hold funds from any specific `DisputeGame` contract.
* The `SystemOwner` can remove funds from the `DelayedWETH` contract if the issue extends to so many `DisputeGame` contracts that holding funds from specific contracts is not viable.
* The `Guardian` can trigger the global pause mechanism to halt WETH withdrawals.

### Cumulative security impact

As with the original system, the cumulative effect of these security capabilities is that the `Guardian` role provides fast response capabilities while the `SystemOwner` can always step in to resolve all classes of bugs that could result in a loss of funds.
With the introduction of Fault Proofs, The most significant change in the security model is that `SystemOwner` can take a more passive role. Invalid proposals will generally be rejected by the Fault Proof System, while the `Guardian` can act as a backstop only in case of a failure in the fault proof game.

## Next steps

* See the [FP Components](/op-stack/fault-proofs/fp-components) for an overview of FP system components and how they work together to enhance decentralization in the Optimism ecosystem.
* See the [specs](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs) for detailed information about the entire FP program, FP virtual machine, and dispute game.


# Fault proofs
Source: https://docs.optimism.io/op-stack/fault-proofs/index

One place to learn the OP Stack fault proof system, from the gentle introduction through the components, hands-on guides, bond economics, and the normative spec.

Fault proofs are how OP Stack chains secure withdrawals without a trusted
third party: anyone can propose the state of the chain on Ethereum, and
anyone can challenge a proposal they believe is wrong. A dispute is
narrowed down, through a bisection game, to a single instruction of
execution, and that one instruction is proven on Ethereum inside an onchain
virtual machine.

This page is the recommended reading order for the whole topic. Start with
the explainer for the mental model, work through the component pages to see
how the pieces fit, then use the hands-on guides if you operate a chain or
want to run a challenger. The bond economics and the normative spec close
the loop for readers who need full depth. Every stop is an existing page;
nothing here replaces them.

## Start here

* [Fault proofs explainer](/op-stack/fault-proofs/explainer): read this
  first for the mental model, covering permissionless proposals,
  permissionless challenges, and the Guardian backstop behind both.

## Go deeper

* [FP system components](/op-stack/fault-proofs/fp-components): the three
  modules of the system (fault proof program, fault proof virtual machine,
  dispute game protocol), why they are decoupled, and why `kona-client` is
  the default fault proof program today.
* [Fault proof VM: Cannon](/op-stack/fault-proofs/cannon): the default
  fault proof virtual machine, split between the onchain `MIPS64.sol`
  contract and the offchain `mipsevm` Go implementation.
* [Fault proof VM: MIPS64.sol](/op-stack/fault-proofs/mips): the onchain
  half at instruction level, an EVM implementation of the multithreaded
  64-bit MIPS instruction set.
* [OP-Challenger explainer](/op-stack/fault-proofs/challenger): how the
  honest actor detects faults, and how it defends valid proposals and
  counters invalid claims move by move.

## Get hands-on

* [Run a fault-proof challenger](/use-cases/run-a-fault-proof-challenger):
  the end-to-end path to a challenger that defends a chain, from bond
  budgeting and prestate selection through infrastructure, configuration,
  and monitoring.
* [How to configure challenger for your chain](/chain-operators/guides/configuration/op-challenger-config-guide):
  the per-flag configuration walkthrough behind that path.
* [Challenger configuration reference](/chain-operators/reference/challenger-configuration):
  the full catalogue of `op-challenger` flags, environment variables, and
  defaults to keep open while you configure.
* [Generating absolute prestate and preimage files](/chain-operators/tutorials/absolute-prestate):
  build and verify the `kona-client` absolute prestate that anchors every
  dispute for your chain.
* [Migrating to permissionless fault proofs](/chain-operators/tutorials/migrating-permissionless):
  move a chain from the permissioned dispute game to permissionless fault
  proofs in four phases.
* [Chain monitoring options](/chain-operators/tools/chain-monitoring#dispute-mon):
  run `op-dispute-mon`, the security monitoring service that tracks the
  status of every game over the last 28 days.

## Economics and incentives

* [Fault proofs explainer FAQs](/op-stack/fault-proofs/explainer#faqs):
  what proposals cost a chain operator to run and how bonds are sized to
  deter invalid claims.
* [OP-Challenger explainer FAQs](/op-stack/fault-proofs/challenger#faqs):
  what the bond does, how much ETH a full-depth game can require, and the
  infrastructure questions (like blob retention) that decide whether you
  can win.

## The normative spec

The definitive definition of fault proof behavior lives in the OP Stack
specifications:

* [Fault proof](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs):
  the fault proof program and the pre-image oracle it reads from.
* [Fault dispute game](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html?utm_source=op-docs\&utm_medium=docs):
  the game itself, including bisection, clocks, and resolution.
* [Honest challenger](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html?utm_source=op-docs\&utm_medium=docs):
  the behavior an honest challenger must implement, which `op-challenger`
  follows.
* [Bond incentives](https://specs.optimism.io/fault-proof/stage-one/bond-incentives.html?utm_source=op-docs\&utm_medium=docs):
  the normative bond economics behind the FAQ answers above.
* [Multithreaded Cannon fault proof VM](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs):
  the specification of the FPVM that Cannon implements.

## Audits and security

* [Fault proofs security](/op-stack/fault-proofs/fp-security): the
  security model and its safeguards, including the Guardian role, game
  blacklisting, the global pause, and delayed bond payouts through
  `DelayedWETH`.
* [Audit reports](/op-stack/security/audit-reports): the standing index of
  OP Stack security reviews, which routes to the full list in the
  monorepo.


# Environment
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/fpp-dev/env



Before kicking off the development of your own [Fault Proof Program](https://specs.optimism.io/fault-proof/index.html#fault-proof-program),
it's important to understand the environment that your program will be running in.

The FPP runs on top of a custom FPVM target, which is typically a VM with a modified subset of an existing reduced instruction set architecture and a subset of Linux syscalls. The FPVM is designed to
execute verifiable programs, and commonly modifies the instruction set it is derived from as well as the internal representation of memory to support verifiable memory access, `client` (program)
communication with the `host` (the FPVM), and other implementation-specific features.

## Host and Client Communication

While the program is running on top of the FPVM, it is considered to be in the `client` role, while the VM is in the `host` role. The only way for the `client` and `host`
to communicate with one another is synchronously through the [Preimage ABI](https://specs.optimism.io/fault-proof/index.html#pre-image-oracle) ([specification][preimage-specs]).

In order for the `client` to read from the `host`, the `read` and `write` syscalls are modified within the FPVM to allow the `client` to request preparation of and read foreign data.

### Reading

When the `client` wants to read data from the `host`, it must first send a "hint" to the `host` through the hint file descriptor, which signals a request for the `host` to prepare the data for reading. The `host` will then
prepare the data, and send a hint acknowledgement back to the `client`. The `client` can then read the data from the host through the designated file descriptor.

The preparation step ("hinting") is an optimization that allows the `host` to know ahead of time the intents of the `client` and the data it requires for execution. This can allow
for lazy loading of data, and also prevent the need for unnecessary allocations within the `host`'s memory. This step is a no-op on-chain, and is only ran locally
when the `host` is the native implementation of the FPVM.

<center>
  ```mermaid theme={null}
  sequenceDiagram
      Client->>+Host: Hint preimage (no-op on-chain / read-only mode)
      Host-->>-Client: Hint acknowledgement
      Client-->>+Host: Preimage Request
      Host-->>Host: Prepare Preimage
      Host-->>-Client: Preimage Data
  ```
</center>

## Full Example

Below, we have a full architecture diagram of [`op-program`](https://github.com/ethereum-optimism/optimism/tree/op-program/v1.9.0/op-program) (as of `op-program/v1.9.0`; source: [fault proof specs][fp-specs]), the original Go implementation of the OP Stack's Fault Proof Program,
which has the objective of verifying claims about the state of an [OP Stack][op-stack] layer two. `op-program` has reached end-of-support and `kona-client` is the maintained Fault Proof Program (see [End of Support for op-geth and op-program](/notices/archive/op-geth-deprecation)), but the architecture shown here applies to both.

<img alt="op-program-architecture" />

In this program, execution and derivation of the L2 chain is performed within it, and ultimately the claimed state of the L2 chain is verified in the [prologue](/op-stack/fault-proofs/kona/fpp-dev/prologue) stage.

It communicates with the `host` for two reasons:

1. To request preparation of L1 and L2 state data preimages.
2. To read the L1 and L2 state data preimages that were prepared after the above requests.

The `host` is responsible for:

1. Preparing and maintaining a store of the L1 and L2 state data preimages, as well as localized bootstrap k/v pairs.
2. Providing the L1 and L2 state data preimages to the `client` for reading.

Other programs (`clients`) may have different requirements for communication with the `host`, but the above is a common pattern for programs built on top of a FPVMs. In general:

1. The `client` program is a state machine that is responsible for bootstrapping itself from the inputs, executing the program logic, and verifying the outcome.
2. The `host` is responsible for providing the `client` with data it wasn't bootstrapped with, and for executing the program itself.

[op-stack]: https://github.com/ethereum-optimism/optimism

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# Epilogue
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/fpp-dev/epilogue



The epilogue stage of the program is intended to perform the final validation on the outputs from the
[execution phase](/op-stack/fault-proofs/kona/fpp-dev/execution). In most programs, this entails comparing the outputs of the execution phase
to portions of the bootstrap data made available during the [prologue phase](/op-stack/fault-proofs/kona/fpp-dev/prologue).

Generally, this phase should consist almost entirely of validation steps.

## Example

In the `kona-client` program, the epilogue phase only contains two directives:

1. Validate that the L2 safe chain could be produced at the claimed L2 block height.
2. The constructed output root is equivalent to the claimed [L2 output root][l2-output-root].

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction


# Execution
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/fpp-dev/execution



The execution phase of the program is commonly the heaviest portion of the fault proof program, where the computation
that is being verified is performed.

This phase consumes the outputs of the [prologue phase](/op-stack/fault-proofs/kona/fpp-dev/prologue), and performs the bulk of the verifiable
computation. After execution has concluded, the outputs are passed along to the [epilogue phase](/op-stack/fault-proofs/kona/fpp-dev/epilogue) for
final verification.

## Example

At a high-level, in the `kona-client` program, the execution phase:

1. Derives the inputs to the L2 derivation pipeline by unrolling the L1 head hash fetched in the prologue.
2. Passes the inputs to the L2 derivation pipeline, producing the L2 execution payloads required to reproduce
   the L2 safe chain at the claimed height.
3. Executes the payloads produced by the L2 derivation pipeline, producing the [L2 output root][l2-output-root] at the
   L2 claim height.

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction


# Fault Proof Program Development
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/fpp-dev/intro



This chapter provides an overview of [Fault Proof Program](https://specs.optimism.io/fault-proof/index.html#fault-proof-program) development
on top of the custom FPVM targets supported by [Kona][kona].

At a high level, a Fault Proof Program is not much different from a regular `no_std` Rust program. A custom entrypoint is provided, and the program
is compiled down to a custom target, which is then executed on the FPVM.

Fault Proof Programs are structured with 3 stages:

1. **Prologue**: The bootstrapping stage, where the program is loaded into memory and the initial state is set up. During this phase, the program's initial
   state is written to the FPVM's memory, and the program's entrypoint is set.
2. **Execution**: The main execution stage, where the program is executed on the FPVM. During this phase, the program's entrypoint is called, and the
   program is executed until it exits.
3. **Epilogue**: The finalization stage, where the program's final state is read from the FPVM's memory. During this phase, the program's final state is
   inspected and properties of the state transition are verified.

The following sections will provide a more in-depth overview of each of these stages, as well as the tools and abstractions provided by Kona for
developing your own Fault Proof Programs.

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona


# Prologue
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/fpp-dev/prologue



The prologue stage of the program is commonly responsible for bootstrapping the program with inputs from an external
source, pulled in through the [Host-Client communication](/op-stack/fault-proofs/kona/fpp-dev/env#host-and-client-communication) implementation.

As a rule of thumb, the prologue implementation should be kept minimal, and should not do much more than establish
the inputs for the [execution phase](/op-stack/fault-proofs/kona/fpp-dev/execution).

## Example

As an example, the prologue stage of the `kona-client` program runs through several steps:

1. Pull in the boot information over the [Preimage Oracle ABI][preimage-specs], containing:
   * The L1 head hash containing all data required to reproduce the L2 safe chain at the claimed block height.
   * The agreed upon safe [L2 output root][l2-output-root].
   * The [L2 output root][l2-output-root] claim.
   * The block number of the [L2 output root][l2-output-root] claim.
   * The L2 chain ID.
2. Pull in the `RollupConfig` and `L1ChainConfig` corresponding to the passed L2 chain ID.
3. Validate these values.
4. Pass the boot information to the execution phase.

[op-stack]: https://github.com/ethereum-optimism/optimism

[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# Supported Targets
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/fpp-dev/targets



Kona seeks to support all FPVM targets that LLVM and `rustc` can offer introductory support for. Below is a matrix of features that Kona offers
for each FPVM target:

| Target     | IO | malloc |
| ---------- | -- | ------ |
| `cannon`   | ✅  | ✅      |
| `asterisc` | ✅  | ✅      |

The `kona-std-fpvm` crate provides IO and allocator support for both the `mips64` (cannon) and `riscv64` (asterisc) architectures. The maintained, reproducible prestate build pipeline in the monorepo (the kona `justfile`'s `build-cannon-client` recipe and the fault proof release process) targets cannon only; building for asterisc requires assembling your own build pipeline.

If there is a feature that you would like to see supported, please [open an issue][new-issue] or [consider contributing][contributing]!

## Asterisc (RISC-V)

Asterisc is based off of the `rv64gc` target architecture, which defines the following extensions:

* `RV32I` support - 32 bit base instruction set
  * `FENCE`, `ECALL`, `EBREAK` are hardwired to implement a minimal subset of systemcalls of the linux kernel
    * Work in progress. All syscalls used by the Golang `risc64` runtime.
* `RV64I` support
* `RV32M`+`RV64M`: Multiplication support
* `RV32A`+`RV64A`: Atomics support
* `RV{32,64}{D,F,Q}`: no-op: No floating points support (since no IEEE754 determinism with rounding modes etc., nor worth the complexity)
* `Zifencei`: `FENCE.I` no-op: No need for `FENCE.I`
* `Zicsr`: no-op: some support for Control-and-status registers may come later though.
* `Ztso`: no-op: no need for Total Store Ordering
* other: revert with error code on unrecognized instructions

`asterisc` supports a plethora of syscalls, documented [in the repository][asterisc-syscalls]. `kona` offers an interface for
programs to directly invoke a select few syscalls:

1. `EXIT` - Terminate the process with the provided exit code.
2. `WRITE` - Write the passed buffer to the passed file descriptor.
3. `READ` - Read the specified number of bytes from the passed file descriptor.

[asterisc-syscalls]: https://github.com/ethereum-optimism/asterisc/blob/master/docs/golang.md#linux-syscalls-used-by-go

## Cannon (MIPS64r2)

Cannon is based off of the `mips64r2` target architecture, specified in [MIPS® Architecture For Programmers Volume II-A: The MIPS64® Instruction Set Reference Manual](https://s3-eu-west-1.amazonaws.com/downloads-mips/documents/MIPS_Architecture_MIPS64_InstructionSet_%20AFP_P_MD00087_06.05.pdf)

### Syscalls

Syscalls supported by `cannon` can be found within the `cannon` specification [here][cannon-syscalls].

[cannon-syscalls]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html#syscalls

[op-stack]: https://github.com/ethereum-optimism/optimism

[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# Custom Backends
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/proof/custom-backend

Implement kona-derive and kona-executor data source traits to run the OP Stack STF on a custom verifiable backend such as a zkVM or TEE.

This guide walks through implementing the data source traits that let you run `kona-client`, or a variation of it, on a verifiable backend of your choosing. Before starting, make sure you're familiar with the two components being composed - the derivation pipeline and the execution engine - covered in [understanding the OP Stack STF](/op-stack/fault-proofs/kona/proof/stf).

## Backend Traits

Covered in the [FPVM Backend](/op-stack/fault-proofs/kona/proof/fpvm-backend) section of the book, `kona-client` ships with an implementation of
`kona-derive` and `kona-executor`'s data source traits which pull in data over the [PreimageOracle ABI][preimage-specs].

However, running `kona-client` on top of a different verifiable environment, i.e. a zkVM or TEE, is also possible
through custom implementations of these data source traits.

[`op-succinct`](https://github.com/succinctlabs/op-succinct) is an excellent example of both a custom backend and a custom
program, implementing both `kona-derive` and `kona-executor`'s data source traits backed by [sp1\_lib::io](https://docs.rs/sp1-lib/latest/sp1_lib/io/index.html)
in order to:

1. Execute `kona-client` verbatim, proving a single block's derivation and execution on SP-1.
2. Derive and execute an entire [Span Batch](https://specs.optimism.io/protocol/delta/span-batches.html#span-batches)
   worth of L2 blocks, using `kona-derive` and `kona-executor`.

This section of the book outlines how you can do the same for a different platform.

### Custom `kona-derive` sources

Before getting started, we need to create custom implementations of the following traits:

| Trait                                                                                          | Description                                                                                                                         |
| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [`ChainProvider`](https://docs.rs/kona-derive/latest/kona_derive/trait.ChainProvider.html)     | The `ChainProvider` trait describes the minimal interface for fetching data from L1 during L2 chain derivation.                     |
| [`L2ChainProvider`](https://docs.rs/kona-derive/latest/kona_derive/trait.L2ChainProvider.html) | The `ChainProvider` trait describes the minimal interface for fetching data from the safe L2 chain during L2 chain derivation.      |
| [`BlobProvider`](https://docs.rs/kona-derive/latest/kona_derive/trait.BlobProvider.html)       | The `BlobProvider` trait describes an interface for fetching EIP-4844 blobs from the L1 consensus layer during L2 chain derivation. |

Once these are implemented, constructing the pipeline is as simple as passing in the data sources to the `PipelineBuilder`. Keep in mind the requirements for validation of incoming data, depending on your platform. For example, programs
targeting zkVMs must constrain that the incoming data is indeed valid, whereas fault proof programs can offload this validation to the on-chain implementation of the host.

```rust theme={null}
let chain_provider = ...;
let l2_chain_provider = ...;
let blob_provider = ...;

let cfg = Arc::new(RollupConfig::default());
let l1_cfg = Arc::new(L1ChainConfig::default());
let attributes = StatefulAttributesBuilder::new(
   cfg.clone(),
   l1_cfg,
   l2_chain_provider.clone(),
   chain_provider.clone(),
   None, // interop dependency set; required when interop is scheduled
);
let dap = EthereumDataSource::new_from_parts(
   chain_provider.clone(),
   blob_provider,
   cfg.as_ref()
);

// Construct a new derivation pipeline. `build_indexed` selects the
// indexed traversal stage; `build_polled` selects polling traversal.
let pipeline = PipelineBuilder::new()
   .rollup_config(cfg)
   .dap_source(dap)
   .l2_chain_provider(l2_chain_provider)
   .chain_provider(chain_provider)
   .builder(attributes)
   .build_polled();
```

From here, a custom derivation driver is needed to produce the desired execution payload(s). An example of this for
`kona-client` can be found in the [single proof implementation](https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/bin/client/src/single.rs).

### `kona-mpt` / `kona-executor` sources

Before getting started, we need to create custom implementations of the following traits:

| Trait                                                                              | Description                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`TrieProvider`](https://docs.rs/kona-mpt/latest/kona_mpt/trait.TrieProvider.html) | The `TrieProvider` trait describes the interface for fetching trie node preimages and chain information while executing a payload on the L2 chain.                                                                                                                                                                             |
| [`TrieDBHinter`](https://docs.rs/kona-mpt/latest/kona_mpt/trait.TrieHinter.html)   | The `TrieDBHinter` trait describes the interface for requesting the host program to prepare trie proof preimages for the client's consumption. For targets with upfront witness generation, i.e. zkVMs, a no-op hinter is exported as [`NoopTrieHinter`](https://docs.rs/kona-mpt/latest/kona_mpt/struct.NoopTrieHinter.html). |

Once we have those, the `StatelessL2Builder` can be constructed like so:

```rust theme={null}
let cfg = RollupConfig::default();
let provider = ...;
let hinter = ...;
let evm_factory = ...;       // e.g. an alloy-evm EvmFactory implementation
let receipt_builder = ...;   // OP Stack callers pass OpAlloyReceiptBuilder
let parent_header = ...;     // Sealed<Header> of the parent block

let mut executor = StatelessL2Builder::new(
   &cfg,
   evm_factory,
   receipt_builder,
   provider,
   hinter,
   parent_header,
);

let outcome = executor.build_block(...).expect("Failed execution");
```

### Bringing it Together

Once your custom backend traits for both `kona-derive` and `kona-executor` have been implemented,
your final binary may look something like [that of `kona-client`'s](https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/bin/client/src/kona.rs).
Alternatively, if you're looking to prove a wider range of blocks, [`op-succinct`'s `range` program](https://github.com/succinctlabs/op-succinct/tree/main/programs/range)
offers a good example of running the pipeline and executor across a string of contiguous blocks.

[op-stack]: https://github.com/ethereum-optimism/optimism

[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# `kona-executor` Extensions
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/proof/exec-ext



The `kona-executor` crate offers a to-spec, stateless implementation of the OP Stack STF. However, due to the
power of [`alloy-evm`][alloy-evm]'s factory abstractions, the logic of the STF can be easily customized.

To customize the EVM behavior, for example to add a custom precompile, modify the behavior of an EVM opcode,
or change the fee handling, you can implement a custom [`EvmFactory`][evm-factory]. The factory is responsible
for creating EVM instances with your desired customizations.

## Example - Custom Precompile

```rust theme={null}
use alloy_evm::{Database, EvmEnv, EvmFactory};
use alloy_op_evm::OpEvm;
use alloy_primitives::{Address, Bytes, u64_to_address};
use kona_executor::StatelessL2Builder;
use kona_genesis::RollupConfig;
use op_revm::{
    DefaultOp, OpContext, OpEvm as RevmOpEvm, OpHaltReason, OpSpecId, OpTransaction,
    OpTransactionError,
};
use revm::{
    Context, Inspector,
    context::{Evm as RevmEvm, FrameStack, TxEnv, result::EVMError},
    handler::instructions::EthInstructions,
    inspector::NoOpInspector,
    precompile::{PrecompileResult, PrecompileOutput, Precompiles},
};

const MY_PRECOMPILE_ADDRESS: Address = u64_to_address(0xFF);

fn my_precompile(input: &Bytes, gas_limit: u64) -> PrecompileResult {
   Ok(PrecompileOutput::new(50, "hello, world!".as_bytes().into()))
}

#[derive(Debug, Clone)]
pub struct CustomEvmFactory;

impl EvmFactory for CustomEvmFactory {
    type Evm<DB: Database, I: Inspector<OpContext<DB>>> = OpEvm<DB, I, CustomPrecompiles>;
    type Context<DB: Database> = OpContext<DB>;
    type Tx = OpTransaction<TxEnv>;
    type Error<DBError: core::error::Error + Send + Sync + 'static> =
        EVMError<DBError, OpTransactionError>;
    type HaltReason = OpHaltReason;
    type Spec = OpSpecId;
    type Precompiles = CustomPrecompiles;

    fn create_evm<DB: Database>(
        &self,
        db: DB,
        input: EvmEnv<OpSpecId>,
    ) -> Self::Evm<DB, NoOpInspector> {
        let spec_id = *input.spec_id();
        let ctx = Context::op().with_db(db).with_block(input.block_env).with_cfg(input.cfg_env);
        
        // Create custom precompiles with our added precompile
        let mut precompiles = op_revm::precompiles::granite();
        precompiles.insert(MY_PRECOMPILE_ADDRESS, my_precompile);
        let custom_precompiles = CustomPrecompiles { precompiles };

        let revm_evm = RevmOpEvm(RevmEvm {
            ctx,
            inspector: NoOpInspector {},
            instruction: EthInstructions::new_mainnet(),
            precompiles: custom_precompiles,
            frame_stack: FrameStack::new(),
        });

        OpEvm::new(revm_evm, false)
    }

    fn create_evm_with_inspector<DB: Database, I: Inspector<Self::Context<DB>>>(
        &self,
        db: DB,
        input: EvmEnv<OpSpecId>,
        inspector: I,
    ) -> Self::Evm<DB, I> {
        let spec_id = *input.spec_id();
        let ctx = Context::op().with_db(db).with_block(input.block_env).with_cfg(input.cfg_env);
        
        // Create custom precompiles with our added precompile
        let mut precompiles = op_revm::precompiles::granite();
        precompiles.insert(MY_PRECOMPILE_ADDRESS, my_precompile);
        let custom_precompiles = CustomPrecompiles { precompiles };

        let revm_evm = RevmOpEvm(RevmEvm {
            ctx,
            inspector,
            instruction: EthInstructions::new_mainnet(),
            precompiles: custom_precompiles,
            frame_stack: FrameStack::new(),
        });

        OpEvm::new(revm_evm, true)
    }
}

// Custom precompiles wrapper
#[derive(Debug)]
pub struct CustomPrecompiles {
    precompiles: Precompiles,
}

impl<CTX> revm::handler::PrecompileProvider<CTX> for CustomPrecompiles
where
    CTX: revm::context::ContextTr<Cfg: revm::context::Cfg<Spec = OpSpecId>>,
{
    type Output = revm::interpreter::InterpreterResult;

    fn set_spec(&mut self, spec: OpSpecId) -> bool {
        // Update precompiles based on spec if needed
        false
    }

    fn run(
        &mut self,
        _context: &mut CTX,
        address: &Address,
        inputs: &revm::interpreter::InputsImpl,
        _is_static: bool,
        gas_limit: u64,
    ) -> Result<Option<Self::Output>, String> {
        use revm::interpreter::{Gas, InstructionResult, InterpreterResult};
        
        let input = match &inputs.input {
            revm::interpreter::CallInput::Bytes(bytes) => bytes.clone(),
            revm::interpreter::CallInput::SharedBuffer(range) => {
                // Handle shared buffer case - simplified for example
                Bytes::new()
            }
        };

        if let Some(precompile) = self.precompiles.get(address) {
            let result = (*precompile)(&input, gas_limit);
            match result {
                Ok(output) => Ok(Some(InterpreterResult {
                    result: InstructionResult::Return,
                    gas: Gas::new(gas_limit - output.gas_used),
                    output: output.bytes,
                })),
                Err(_) => Ok(Some(InterpreterResult {
                    result: InstructionResult::PrecompileError,
                    gas: Gas::new(0),
                    output: Bytes::new(),
                })),
            }
        } else {
            Ok(None)
        }
    }
}

// - snip -

let cfg = RollupConfig::default();
let provider = ...;
let hinter = ...;
let parent_header = ...;
let receipt_builder = alloy_op_evm::block::OpAlloyReceiptBuilder::default();

let executor = StatelessL2Builder::new(
    &cfg,
    CustomEvmFactory,
    receipt_builder,
    provider,
    hinter,
    parent_header,
);
```

## Migration from the old API

Prior to the integration of `alloy-evm`, `kona-executor` used a builder pattern with `StatelessL2BlockExecutorBuilder::with_handle_register` for EVM customization. The new approach using `EvmFactory` provides better composability and aligns with the broader Alloy ecosystem.

### Key Changes:

1. **Direct construction**: Use `StatelessL2Builder::new()` instead of a builder pattern
2. **Factory-based customization**: Implement `EvmFactory` instead of registering handlers
3. **Type safety**: The factory approach provides better compile-time guarantees
4. **Ecosystem alignment**: Leverages the standard `alloy-evm` interfaces

### Benefits:

* **Composability**: Custom EVM factories can be easily shared and reused
* **Flexibility**: Full control over EVM creation and configuration
* **Performance**: Reduced indirection compared to the handler approach
* **Maintainability**: Cleaner separation of concerns between execution and customization

For more complex customizations involving multiple precompiles, custom opcodes, or specialized execution logic, refer to the [`FpvmOpEvmFactory`](https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/bin/client/src/fpvm_evm/factory.rs) implementation in the `kona-client` for a comprehensive example.

[op-stack]: https://github.com/ethereum-optimism/optimism

[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[alloy-evm]: https://github.com/alloy-rs/evm

[evm-factory]: https://docs.rs/alloy-evm/latest/alloy_evm/eth/struct.EthEvmFactory.html

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# FPVM Backend
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/proof/fpvm-backend



<Note>
  Before reading this section of the book, it is advised to read the [Fault Proof Program Environment](/op-stack/fault-proofs/kona/fpp-dev/env)
  section to familiarize yourself with the PreimageOracle IO pattern.
</Note>

Kona is effectively split into three parts:

* OP Stack state transition logic (`kona-derive`, `kona-executor`, `kona-mpt`)
* OP Stack state transition proof SDK (`kona-preimage`, `kona-proof`)
* [Fault Proof VM](https://specs.optimism.io/fault-proof/index.html#fault-proof-vm) IO and utilities
  (`kona-std-fpvm`, `kona-std-fpvm-proc`)

This section of the book focuses on the usage of `kona-std-fpvm` and `kona-preimage` to facilitate communication between host and client
for programs running on top of the [FPVM targets](/op-stack/fault-proofs/kona/fpp-dev/env).

## Host and Client Communication API

The FPVM system API is built on several layers. In this document, we'll cover these layers, from lowest-level to
highest-level API.

### `kona-std-fpvm`

`kona-std-fpvm` implements raw syscall dispatch, a default global memory allocator, and a blocking async runtime.
`kona-std-fpvm` relies on a minimal linux backend to function, supporting only the syscalls required to implement the
[PreimageOracle ABI][preimage-specs] (`read`, `write`, `exit_group`).

These syscalls are exposed to the user through the `io` module directly, with each supported platform implementing the
[`BasicKernelInterface`](https://docs.rs/kona-std-fpvm/latest/kona_std_fpvm/trait.BasicKernelInterface.html) trait.

To directly dispatch these syscalls, the [`io`](https://docs.rs/kona-std-fpvm/latest/kona_std_fpvm/io/index.html) module
exposes a safe API:

```rust theme={null}
use kona_std_fpvm::{io, FileDescriptor};

// Print to `stdout`. Infallible, will panic if dispatch fails.
io::print("Hello, world!");

// Print to `stderr`. Infallible, will panic if dispatch fails.
io::print_err("Goodbye, world!");

// Read from or write to a specified file descriptor. Returns a result with the
// return value or syscall errno.
let _ = io::write(FileDescriptor::StdOut, "Hello, world!".as_bytes());
let mut buf = Vec::with_capacity(8);
let _ = io::read(FileDescriptor::StdIn, buf.as_mut_slice());

// Exit the program with a specified exit code.
io::exit(0);
```

With this library, you can implement a custom communication protocol between the host and client, or extend the existing
[PreimageOracle ABI][preimage-specs]. However, for most developers, we recommend sticking with `kona-preimage`
when developing programs that target the [FPVMs](/op-stack/fault-proofs/kona/fpp-dev/env), barring needs like printing directly to
`stdout`.

### `kona-preimage`

`kona-preimage` is an implementation of the [PreimageOracle ABI][preimage-specs]. This crate enables synchronous
communication between the host and client program, described in
[Host - Client Communication](/op-stack/fault-proofs/kona/fpp-dev/env#host-and-client-communication) in the FPP Dev environment section of the
book.

The crate is built around the [`Channel`](https://docs.rs/kona-preimage/latest/kona_preimage/trait.Channel.html) trait,
which serves as a single end of a bidirectional pipe (see: [`pipe` manpage](https://man7.org/linux/man-pages/man2/pipe.2.html)).

Through this handle, the higher-level constructs can read and write data to the counterparty holding on to the other end
of the channel, following the protocol below:

<center>
  ```mermaid theme={null}
  sequenceDiagram
      Client->>+Host: Hint preimage (no-op on-chain / read-only mode)
      Host-->>-Client: Hint acknowledgement
      Client-->>+Host: Preimage Request
      Host-->>Host: Prepare Preimage
      Host-->>-Client: Preimage Data
  ```
</center>

The interfaces of each part of the above protocol are described by the following traits:

* [`PreimageOracleClient`](https://docs.rs/kona-preimage/latest/kona_preimage/trait.PreimageOracleClient.html)
  * To-spec implementation: [`OracleReader`](https://docs.rs/kona-preimage/latest/kona_preimage/struct.OracleReader.html)
* [`HintWriterClient`](https://docs.rs/kona-preimage/latest/kona_preimage/trait.HintWriterClient.html)
  * To-spec implementation: [`HintWriter`](https://docs.rs/kona-preimage/latest/kona_preimage/struct.HintWriter.html)
* [`PreimageOracleServer`](https://docs.rs/kona-preimage/latest/kona_preimage/trait.PreimageOracleServer.html)
  * To-spec implementation: [`OracleServer`](https://docs.rs/kona-preimage/latest/kona_preimage/struct.OracleServer.html)
* [`HintReaderServer`](https://docs.rs/kona-preimage/latest/kona_preimage/trait.HintReaderServer.html)
  * To-spec implementation: [`HintReader`](https://docs.rs/kona-preimage/latest/kona_preimage/struct.HintReader.html)

Each of these traits, however, can be re-implemented to redefine the communication protocol between the host and client if the needs
of the consumer are not covered by the to-[spec][preimage-specs] implementations.

### `kona-proof` - Oracle-backed sources (example)

Finally, in `kona-proof`, implementations of data source traits from `kona-derive` and `kona-executor` are provided
to pull in untyped data from the host by `PreimageKey`. These data source traits are covered in more detail within
the [Custom Backend](/op-stack/fault-proofs/kona/proof/custom-backend) section, but we'll quickly gloss over them here to build intuition.

Let's take, for example, [`OracleL1ChainProvider`](https://github.com/ethereum-optimism/optimism/blob/develop/rust/kona/crates/proof/proof/src/l1/chain_provider.rs).
The [`ChainProvider`](https://docs.rs/kona-derive/latest/kona_derive/trait.ChainProvider.html) trait in `kona-derive`
defines a simple interface for fetching information about the L1 chain. In the `OracleL1ChainProvider`, this information
is pulled in over the [PreimageOracle ABI][preimage-specs]. There are many other examples of these data source traits,
namely the `L2ChainProvider`, `BlobProvider`, `TrieProvider`, and `TrieHinter`, which enable the creation of different
data-source backends.

As an example, let's look at `OracleL1ChainProvider::header_by_hash`, built on top of the `CommsClient` trait, which
is a composition trait of the `PreimageOracleClient + HintWriterClient` traits outlined above.

```rust theme={null}
#[async_trait]
impl<T: CommsClient + Sync + Send> ChainProvider for OracleL1ChainProvider<T> {
    type Error = OracleProviderError;

    async fn header_by_hash(&mut self, hash: B256) -> Result<Header, Self::Error> {
        // Fetch the header RLP from the oracle.
        HintType::L1BlockHeader.with_data(&[hash.as_ref()]).send(self.oracle.as_ref()).await?;
        let header_rlp = self.oracle.get(PreimageKey::new_keccak256(*hash)).await?;

        // Decode the header RLP into a Header.
        Header::decode(&mut header_rlp.as_slice()).map_err(OracleProviderError::Rlp)
    }

    // - snip -
}
```

The hint send and the preimage fetch are both visible here: `HintType::L1BlockHeader.with_data(...).send(...)` writes the hint through the `HintWriterClient`, and `self.oracle.get(...)` reads the prepared preimage through the `PreimageOracleClient`.

In `header_by_hash`, we use the inner `HintWriter` to send a hint to the host to prepare the block hash preimage.
Then, once we've received an acknowledgement from the host that the preimage has been prepared, we reach out for
the RLP (which is the preimage of the hash). After the RLP is received, we decode the `Header` type, and return
it to the user.

[op-stack]: https://github.com/ethereum-optimism/optimism

[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# Kona Proof SDK
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/proof/intro



Welcome to the Kona Proof SDK, a powerful set of libraries designed
from first principles to build proofs with the OP Stack STF on top
of the OP Stack's FPVMs and other verifiable backends like [SP-1][sp-1],
[Risc0][rzero], [Intel TDX][tdx], and [AMD SEV-SNP][sev-snp]. At its
core, Kona is built on the principles of modularity, extensibility,
and developer empowerment.

## A Foundation of Flexibility

The kona repository is more than a fault proof program for the OP Stack
— it's an ecosystem of interoperable components, each crafted with
reusability and extensibility as primary goals. While we provide
[Fault Proof VM](https://specs.optimism.io/fault-proof/index.html#fault-proof-vm) and "online" backends
for key components like `kona-derive` and `kona-executor`, the true
power of `kona` lies in its adaptability.

## Extend Without Forking

One of Kona's standout features is its ability to support custom
features and data sources without requiring you to fork the entire
project. Through careful use of Rust's powerful trait system and
abstract interfaces, we've created a framework that allows you to
plug in your own features and ideas seamlessly.

## What You'll Learn

In this section of the developer book, we'll dive deep into the Kona SDK, covering:

* **Building on the FPVM Backend**: Learn how to leverage the Fault Proof VM tooling to create your own fault proof programs.
* **Creating Custom Backends**: Discover the process of designing and implementing your own backend to run `kona-client` or a variation of it on different targets.
* **Extending Core Components**: Explore techniques for creating new constructs that integrate smoothly with crates like `kona-derive` and `kona-executor`.

Whether you're looking to use Kona as-is, extend its functionality, or create entirely new programs based on its libraries,
this guide is intended to provide you with the knowledge and tools you need to succeed.

[sp-1]: https://github.com/succinctlabs/sp1

[rzero]: https://github.com/risc0/risc0

[tdx]: https://www.intel.com/content/www/us/en/developer/tools/trust-domain-extensions/documentation.html

[sev-snp]: https://www.amd.com/en/developer/sev.html

[op-stack]: https://github.com/ethereum-optimism/optimism

[op-program]: https://github.com/ethereum-optimism/optimism/tree/develop/op-program

[cannon]: https://github.com/ethereum-optimism/optimism/tree/develop/cannon

[cannon-rs]: https://github.com/op-rs/cannon-rs

[asterisc]: https://github.com/ethereum-optimism/asterisc

[fp-specs]: https://specs.optimism.io/fault-proof/index.html

[fpp-specs]: https://specs.optimism.io/fault-proof/index.html#fault-proof-program

[preimage-specs]: https://specs.optimism.io/fault-proof/index.html#pre-image-oracle

[cannon-specs]: https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html

[l2-output-root]: https://specs.optimism.io/protocol/proposals.html#l2-output-commitment-construction

[op-succinct]: https://github.com/succinctlabs/op-succinct

[revm]: https://github.com/bluealloy/revm

[kona]: https://github.com/ethereum-optimism/optimism/tree/develop/rust/kona

[issues]: https://github.com/ethereum-optimism/optimism/issues

[new-issue]: https://github.com/ethereum-optimism/optimism/issues/new

[contributing]: https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md

[op-labs]: https://github.com/ethereum-optimism

[bad-boi-labs]: https://github.com/BadBoiLabs


# Understanding the OP Stack STF
Source: https://docs.optimism.io/op-stack/fault-proofs/kona/proof/stf

How Kona composes the derivation pipeline and execution engine into a verifiable OP Stack state transition, and why kona-client proves a single block by default.

The OP Stack state transition is comprised of two primary components:

* **The [derivation pipeline](https://specs.optimism.io/protocol/derivation.html)** (`kona-derive`)
  * Responsible for deriving L2 chain state from the DA layer.
* **The [execution engine](https://specs.optimism.io/protocol/exec-engine.html#l2-execution-engine)** (`kona-executor`)
  * Responsible for the execution of transactions and state commitments.
  * Ensures correct application of derived L2 state.

To prove the correctness of the state transition, Kona composes these two components:

* It combines the derivation of the L2 chain with its execution in the same process.
* It pulls in necessary data from sources to complete the STF, verifiably unrolling the input commitments along the way.

`kona-client` serves as an implementation of this process, capable of deriving and executing a single L2 block in a
verifiable manner.

<Note>
  **Why just a single block by default?**

  On the OP Stack, we employ an interactive bisection game that narrows in on the disagreed upon block -> block state
  transition before requiring a fault proof to be ran. Because of this, the default implementation only serves
  to derive and execute the single block that the participants of the bisection game landed on.
</Note>

## Where the STF Runs

`kona-client` executes this state transition on top of a verifiable backend. Two paths are documented in this section of the book:

* The [FPVM backend](/op-stack/fault-proofs/kona/proof/fpvm-backend), which Kona ships out of the box, runs the STF on the OP Stack's Fault Proof VMs and sources its data over the PreimageOracle ABI.
* [Custom backends](/op-stack/fault-proofs/kona/proof/custom-backend) run the same STF on other verifiable environments, such as zkVMs or TEEs, by swapping out the data source traits.


# Fault proof VM: MIPS64.sol
Source: https://docs.optimism.io/op-stack/fault-proofs/mips

Learn about the `MIPS64.sol` smart contract that works as part of Optimism's Fault Proof Virtual Machine.

<NormativeSpec title="multithreaded Cannon fault proof VM specification" href="https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html" />

The [`MIPS64.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/MIPS64.sol) smart contract is an onchain implementation of a big-endian virtual machine (VM) that encompasses the 64-bit MIPS64 Release 1 (MIPS64r1) Instruction Set Architecture (ISA), extended with multithreading support.
It is the counterpart to the off-chain `mipsevm` Go implementation of the same ISA, and together the onchain and off-chain VM implementations make up [Cannon](/op-stack/fault-proofs/cannon),
Optimism's Fault Proof Virtual Machine (FPVM). Cannon is an instance of an FPVM that can be used as part of the Dispute Game for any OP Stack blockchain.
The Dispute Game itself is modular, allowing for any FPVM to be used in a dispute; however, Cannon is Optimism's default FPVM, and `MIPS64.sol` is its onchain component.
The multithreaded 64-bit generation of Cannon is also referred to as MTCannon, and its behavior is specified in the [Cannon FPVM specification](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs).

## From 32 bits to 64 bits

Cannon's onchain FPVM contract was originally `MIPS.sol`, a single-threaded implementation of the 32-bit MIPS32 ISA
(see the version at the [`op-contracts/v1.6.0`](https://github.com/ethereum-optimism/optimism/blob/op-contracts/v1.6.0/packages/contracts-bedrock/src/cannon/MIPS.sol) tag, as of `op-contracts/v1.6.0`).
Multithreading was first added to Cannon on the 32-bit architecture: the `multithreaded` state version in
[`version.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/versions/version.go) precedes the 64-bit `multithreaded64` versions, and it had a matching `MIPS2.sol` contract.
That 32-bit multithreaded generation never became the production onchain FPVM, though: the
[standard versions](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml) in the superchain-registry
move directly from the single-threaded 32-bit `MIPS.sol` (last shipped as contract version `1.3.0`, through the `op-contracts/v2.x` releases)
to the multithreaded 64-bit `MIPS64.sol` (contract version `1.0.0` in `op-contracts/v3.0.0`, where the registry notes that the MIPS semver was reset because "MIPS is now MIPS64").
For the deployed onchain contract, the move from 32 bits to 64 bits therefore came with the transition to multithreaded Cannon.
`MIPS.sol` and `MIPS2.sol` have since been removed from the Optimism monorepo, and `MIPS64.sol` is the maintained onchain FPVM contract.
The rest of this page describes `MIPS64.sol`.

## Control flow

The `FaultDisputeGame.sol` contract interacts with `MIPS64.sol`, and `MIPS64.sol` in turn calls into `PreimageOracle.sol`. `MIPS64.sol` is only called at the max depth of the game when someone needs to call [`step`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/dispute/FaultDisputeGame.sol#L362) (as of `2783f688`); the dispute game reaches the VM through the generic `IBigStepper` interface, so any FPVM implementing that interface can back a dispute game.
`FaultDisputeGame.sol` is the deployed instance of a Fault Dispute Game for an active dispute, and `PreimageOracle.sol` stores Pre-images.

* Pre-images contain data from both L1 and L2, which includes information such as block headers, transactions, receipts, world state nodes, and more. Pre-images are used as the inputs to the derivation process used to calculate the true L2 state, and subsequently the true L2 state is used to resolve a dispute game.
* A Fault Dispute Game, at a high-level, will effectively determine what L2 state is currently agreed-upon, and move through L2 state until the first disagreed-upon state is found. How the Pre-images are determined and populated into the `PreimageOracle.sol` contract is out-of-scope for this reference document on the `MIPS64.sol` contract, as that contract only consumes Pre-images that have already been populated by the off-chain Cannon implementation.

The `MIPS64.sol` contract is called by a running instance of a dispute game (i.e. by a `FaultDisputeGame.sol` contract), and is only called once a dispute game reaches a leaf node in the state transition tree that is currently being disputed.
A leaf node represents a single MIPS instruction (in the case that we're using Cannon as the FPVM) that can then be run onchain. Given a Pre-image, which is the previously agreed-upon L2 state up until this instruction, and the instruction
state to run in the `MIPS64.sol` contract, the fault dispute game can determine the true post state (or Post-image). This true post state will then be used to determine the outcome of the fault dispute game by comparing the disputed post-state
at the leaf node with the post-state proposed by the disputer.

## Contract state

The `MIPS64.sol` contract contains only two immutable variables: the address of the `PreimageOracle.sol` contract, and the Cannon state version it implements.
The [constructor](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L94) (as of `2783f688`) accepts only state version `8`, the `multithreaded64-5` version defined in
[`version.go`](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/mipsevm/versions/version.go), which is the current default state version of the off-chain Cannon implementation.
Otherwise, the contract is stateless, meaning that all state related to playing a MIPS instruction onchain comes from either the `FaultDisputeGame.sol` instance, or the `PreimageOracle.sol`.
Having a stateless `MIPS64.sol` contract means that it can be used by any fault dispute game that is using the Cannon FPVM; the `MIPS64.sol` contract does not need to be re-deployed per fault dispute game instance.
Subsequently, any fault dispute game that is using the same `MIPS64.sol` contract will also share the same `PreimageOracle.sol` contract.
Note that the `PreimageOracle.sol` contract is stateful, but how state is stored in the contract and differentiated between different fault dispute game instances is out-of-scope for this document.

While the `MIPS64.sol` contract is stateless, meaning it does not store state in the contract directly, the contract does require up to 4 different types of witness data in order to perform a single MIPS instruction onchain:

* Packed VM execution state
* A thread state witness
* Memory proofs
* Pre-images

The Pre-images have already been discussed above, so we will discuss the packed VM execution state, the thread state witness, and the memory proofs.
As a final note on Pre-images during onchain execution, it is entirely possible that the `MIPS64.sol` contract never runs a MIPS instruction onchain that requires the contract to read from `PreimageOracle.sol`.
There is no requirement to read from the `PreimageOracle.sol` during instruction execution, but that doesn't mean the `PreimageOracle.sol` contract is not being used.
The Pre-image information that has been read in previous off-chain instructions leading up to the execution of a single instruction onchain may still reside in the constructed VM memory.
Thus, even when the instruction run onchain does not explicitly read from `PreimageOracle.sol`, Pre-image data may still influence the merkle root that represents the VM's memory.

### Packed VM execution state

In order to execute a MIPS instruction onchain, the `MIPS64.sol` contract needs to know important state information such as the memory root, the Pre-image read position, and the multithreading bookkeeping described below.
More specifically, a tightly-packed 188-byte `State` struct contains all the relevant global VM state. This struct is passed to the contract from the `FaultDisputeGame.sol` contract when it invokes the `step` function in `MIPS64.sol` (which in-turn executes a single MIPS instruction onchain).
The following information is stored in the `State` struct. See the [code reference](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L50) (as of `2783f688`) and the [Cannon FPVM specification](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs#state) for details:

1. `memRoot` - The merkle root hash of the binary merkle tree that represents the MIPS VM's monolithic 64-bit memory space.
2. `preimageKey` - Key that uniquely identifies the Pre-image data to be read (if applicable) from the `PreimageOracle.sol` contract.
3. `preimageOffset` - Each Pre-image read from the oracle returns up to 32 bytes, however the word size for 64-bit MIPS is 8 bytes. Therefore, at most 8 bytes from a Pre-image will be read during a read syscall. The `preimageOffset` serves as the offset into the Pre-image being read, so that an instruction can continue reading a Pre-image up to 8 bytes at a time.
4. `heap` - Pointer to the most recent memory allocation returned via the `mmap` syscall.
5. `llReservationStatus` - Status of the current Load Linked / Store Conditional memory reservation: `0` when there is no reservation, `1` for a 32-bit (`ll`/`sc`) reservation, and `2` for a 64-bit (`lld`/`scd`) reservation.
6. `llAddress` - The virtual address reserved by the last `ll` or `lld` instruction, or `0` when there is no active reservation.
7. `llOwnerThread` - The id of the thread that owns the current memory reservation, or `0` when there is no active reservation.
8. `exitCode` - `uint8` value that represents the UNIX exit status code of the VM.
9. `exited` - Boolean that indicates whether the VM has exited or not.
10. `step` - Counts the total number of instructions that have been executed.
11. `stepsSinceLastContextSwitch` - Counts the instructions executed on the current thread since the last context switch, used to force thread preemption after the scheduling quantum.
12. `traverseRight` - Boolean that indicates whether the VM is currently traversing the right thread stack (see below).
13. `leftThreadStack` - Hash commitment to the contents of the left thread stack.
14. `rightThreadStack` - Hash commitment to the contents of the right thread stack.
15. `nextThreadID` - The id to assign to the next thread created via the `clone` syscall.

Note that the per-thread execution state (`pc`, `nextPC`, `lo`, `hi`, and the 32 general purpose registers) is no longer part of the top-level `State` struct: it lives in the thread state, described next.

### Thread state and thread stacks

`MIPS64.sol` supports multithreading, so the VM tracks a set of threads and executes one instruction at a time on the currently active thread.
Each thread is described by a packed 298-byte [`ThreadState`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L28) (as of `2783f688`) struct containing:

1. `threadID` - A unique thread identifier.
2. `exitCode` - The thread's exit status code.
3. `exited` - Boolean that indicates whether the thread has exited.
4. `pc` - The program counter, which points to the memory location that contains the MIPS instruction to execute onchain.
5. `nextPC` - The next program counter. Note that the next instruction may not be `pc + 4` in the event of a branch or jump instruction; `nextPC` effectively implements the [branch delay slot](https://en.wikipedia.org/wiki/MIPS_architecture#cpu_instructions) of the MIPS ISA.
6. `lo` - Special purpose register that stores the low-order bits from certain multiplication and division instructions (or special move instructions that store into this register).
7. `hi` - Special purpose register that stores the high-order bits from certain multiplication and division instructions (or special move instructions that store into this register).
8. `registers` - Array of 32, 64-bit values that represent the general purpose registers of the MIPS ISA.

Rather than storing every thread in the packed VM state, the VM commits to its threads using two stacks of thread states (a left stack and a right stack), each represented by a single `bytes32` "hash onion" commitment: an empty stack is `keccak256(bytes32(0) ++ bytes32(0))`, and pushing a thread hashes the current commitment together with the thread's hash.
The VM traverses the two stacks left-to-right and then right-to-left to visit every thread, as described in the [thread stack hashing](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs#thread-stack-hashing) and [multithreading](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs#multithreading) sections of the specification.
Because of this construction, a `step` call only needs a witness for the currently active thread: the packed `ThreadState` plus the inner commitment of the rest of the active stack.
Threads are scheduled cooperatively (via syscalls such as `sched_yield`, `nanosleep`, and `futex` waits) and preemptively: once `stepsSinceLastContextSwitch` reaches the scheduling quantum of 100,000 steps ([`SCHED_QUANTUM`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Syscalls.sol#L126), as of `2783f688`), the VM forces a context switch instead of executing another instruction on the same thread.

### State hash

The state hash is the `bytes32` value returned to the active Fault Dispute Game upon the completion of a single MIPS instruction in the `MIPS64.sol` contract.
The hash is derived by taking the `keccak256` of the packed 188-byte VM execution `State` struct, then replacing the first byte of the hash with a value that represents the status of the VM.
This value is derived from the `exitCode` and `exited` values, and can be:

* Valid (0)
* Invalid (1)
* Panic (2) or
* Unfinished (3)

The reason for adding the VM status to the state hash is to communicate to the dispute game whether the VM determined the proposed output root was valid or not.
This in turn prevents a user from disputing an output root during a dispute game, while providing the state hash from a cannon trace that actually proves the output root is valid.

### Memory proofs

Using a 64-bit ISA means that the total size of the address space (assuming no virtual address space) is `2^64` bytes. Additionally, the `MIPS64.sol` contract is stateless, so it does not store the MIPS memory in contract storage. The primary reason for this is because having to load the entire memory into the `MIPS64.sol` contract in order to execute a single instruction onchain is prohibitively expensive. Additionally, the entire memory would need to be loaded per fault proof game, requiring multiple instances of the `MIPS64.sol` contract. Therefore, in order to optimize the amount of data that needs to be provided per onchain instruction execution while still maintaining integrity over the entire 64-bit address space, Optimism has converted the memory into a binary merkle tree.

The binary merkle tree (i.e. hash tree) used to store the memory of the MIPS VM has leaf values that are 32 bytes and has a fixed depth of 59 levels. This in turn allows the binary merkle tree to span the full 64-bit address space: `2^59 * 32 = 2^64` (See [memory proofs](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/docs/README.md#memory-proofs) in the Cannon overview for more details). In order to ensure the integrity of the entire address space each time memory is read or written to, one or more memory proofs are provided by the `FaultDisputeGame.sol` contract each time a MIPS instruction is executed onchain in `MIPS64.sol`. A memory proof consists of the current leaf value and 59 sibling nodes (60, 32-byte values in total, per [`MEM_PROOF_LEAF_COUNT`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Memory.sol#L9), as of `2783f688`), where the sibling nodes are the `keccak256` hash of its own child nodes. Using the leaf value, its 59 sibling nodes, and the memory address converted to its binary representation as a guide (0 or 1 tells the order to concatenate left and right values), we can calculate a merkle root. This merkle root should be exactly the same as the merkle root stored in the VM execution `State` struct.

Reading to memory and writing to memory work similarly, both involve calculating the merkle root. In the case of a memory write, `MIPS64.sol` must take care to verify that the provided proof for the memory location to write to is correct. Additionally, writing to memory will change the merkle root stored in the VM execution `State` struct.

### State calculation

While the `MIPS64.sol` contract may only execute a single instruction onchain, the off-chain Cannon implementation executes all prerequisite MIPS instructions for all state transitions in the disputed L2 state. These transitions are required to reach the disputed instruction that will be executed onchain. This ensures that the MIPS instruction executed onchain has the correct VM state and necessary Pre-images stored in the `PreimageOracle.sol` contract to generate the true post-state that can be used to resolve the dispute game.

## Functions

The single-instruction interpreter is split between the `MIPS64.sol` contract, which owns the state and thread handling, and a set of libraries under
[`src/cannon/libraries`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/src/cannon/libraries): `MIPS64Memory.sol` (memory proofs), `MIPS64Instructions.sol` (the core instruction interpreter), `MIPS64Syscalls.sol` (syscall handling), `MIPS64State.sol`, and `MIPS64Arch.sol`.

### oracle

The external view [`oracle`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L105) (as of `2783f688`) function is a getter function that returns the PreimageOracle address cast as a `IPreimageOracle` interface.

### stateVersion

The external view [`stateVersion`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L111) (as of `2783f688`) function returns the Cannon state version implemented by the deployed contract, which identifies the specific state transition rules it applies.

### step

The public [`step`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L126) (as of `2783f688`) function is the top-level call that executes a single MIPS instruction. This function will be called by an active dispute game in order to determine the true post state given a pre state and a MIPS instruction to run. It takes three arguments: the packed `State` witness (`_stateData`), the proof data (`_proof`, containing the thread witness followed by one or more memory proofs), and a `_localContext` value used to localize Pre-image keys per dispute game. At a high-level, the function (via the internal [`doStep`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L150) function, as of `2783f688`) performs the following steps:

1. Verifies and unpacks the `stateData` variable into the VM execution `State` struct (in memory), and unpacks and validates the thread witness against the active thread stack commitment.
2. If the active thread has exited, pops it from the thread stack; if the scheduling quantum has been exceeded, preempts the thread. In either case this consumes the step without executing an instruction.
3. Otherwise, reads the instruction located at the active thread's program counter (`pc`) using the first memory proof.
4. Interprets and executes the MIPS instruction according to the MIPS specification, dispatching syscalls and Load Linked / Store Conditional instructions to their dedicated handlers.
5. Writes results to registers or memory (if applicable), updates the active thread's commitment on the thread stack, and returns the new state hash.

The contract also asserts a post-state invariant: the active thread stack must never end up empty after a step.

### handleSyscall

The internal [`handleSyscall`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L399) (as of `2783f688`) function handles the syscall MIPS instruction, with the heavy lifting implemented in [`MIPS64Syscalls.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/libraries/MIPS64Syscalls.sol). Syscall numbers follow the Linux MIPS64 n64 ABI (e.g. `read` is `5000` and `write` is `5001`). Only a subset of syscalls is implemented with real behavior, mimicking the Linux manual pages where applicable:

* Pre-image communication: `read` and `write` (discussed below).
* Memory management: `mmap` (bump allocation from the `heap` pointer with a fixed heap limit) and `brk` (returns a fixed program break).
* Thread management: `clone` (creates a new thread sharing memory but with its own stack pointer and registers), `exit` (exits the current thread; exits the VM when it is the last thread), `exit_group` (exits the VM), `gettid`, `sched_yield` and `nanosleep` (yield the current thread), and `futex` wait/wake operations used for thread synchronization.
* Miscellaneous: `fcntl` (file descriptor flags only), `clock_gettime` (derives a deterministic clock from the step counter), `getpid`, `getrandom` (fills memory with deterministic pseudorandom bytes derived from the step counter), and `eventfd2` (non-blocking mode only).

A further list of known but irrelevant syscalls (e.g. `munmap`, `mprotect`, signal and timer related calls) is treated as a no-op, returning 0 without any side effects; see the [noop syscalls](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs#noop-syscalls) list in the specification.
Unlike the original 32-bit `MIPS.sol`, which silently returned 0 for anything it did not recognize, `MIPS64.sol` reverts on unrecognized syscall numbers so that unexpected program behavior cannot go unnoticed.

#### syscall read

When given file descriptor 5 as the target of the read syscall, [`handleSysRead`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Syscalls.sol#L251) (as of `2783f688`) will call the `PreimageOracle.sol` contract to read up to 32 bytes of Pre-image data at the current location determined by the `preimageKey` stored in the VM execution `State` struct (localizing the key with the `_localContext` when it is a local key). Once the Pre-image fragment has been read, the function will then determine the number of bytes to read (up to 8 bytes) and the location in memory to store the bytes. The number of bytes read may be any value between 1 and 8, depending on the alignment of the offset in the returned Pre-image and the alignment of the memory position to write the data to.

#### syscall write

When given the file descriptor 6 as the target of the write syscall, [`handleSysWrite`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Syscalls.sol#L339) (as of `2783f688`) will not call the `PreimageOracle.sol` contract to write a new Pre-image. Only the off-chain Cannon implementation writes to the `PreimageOracle.sol` contract. Instead, the function computes the new value of the `preimageKey` given the bytes (up to 8) that would be written to the `PreimageOracle.sol` contract. Additionally, the function resets the `preimageOffset` to 0. It is expected that the off-chain Cannon implementation has already written the data to the `PreimageOracle.sol` contract at the location of the newly-derived `preimageKey`.

### handleRMWOps

The internal [`handleRMWOps`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L304) (as of `2783f688`) function handles the atomic read-modify-write instruction pairs: Load Linked / Store Conditional Word (`ll`/`sc`) and their doubleword variants (`lld`/`scd`). A load linked instruction records a reservation (`llReservationStatus`, `llAddress`, `llOwnerThread`) in the VM state; the matching store conditional succeeds only if that reservation is still intact for the calling thread, which is how the VM emulates atomic memory operations across threads. Any write to the reserved address clears the reservation.

### Thread stack management

A group of internal functions maintains the two thread stack commitments as threads are created, preempted, and exited:
[`preemptThread`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L810) moves the active thread to the other stack (flipping the traversal direction when a stack empties), [`pushThread`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L837) and [`popThread`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L847) add and remove threads, and [`validateCalldataThreadWitness`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L921) verifies that the thread witness provided in calldata matches the active stack commitment (all as of `2783f688`).

### outputState

The internal [`outputState`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/MIPS64.sol#L727) (as of `2783f688`) function computes the `keccak256` hash of all values in the VM execution `State` struct, and then masks the first byte of the hash with the current status of the VM as derived from the `exitCode` and `exited` values. Despite the complexity of the function (due to the use of assembly), the implementation is effectively tightly packing all the variables in the `State` struct together, then taking the `keccak256` of the packed bytes.

### Instruction execution: MIPS64Instructions.sol

The core interpreter lives in [`MIPS64Instructions.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol):

* [`getInstructionDetails`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L60) (as of `2783f688`) reads the 32-bit instruction at `pc` (instructions remain 4 bytes wide on MIPS64) using the first memory proof and splits out the opcode and function fields.
* [`execMipsCoreStepLogic`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L86) (as of `2783f688`) fetches register operands, dispatches jumps, branches, and HI/LO instructions, executes the instruction, and stores the result.
* [`executeMipsInstruction`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L239) (as of `2783f688`) computes ALU results and memory load/store values. Invalid or unsupported instructions cause a revert.
* [`handleBranch`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L641) (as of `2783f688`) handles the branch opcodes and conforms to the MIPS specification for the instructions.
* [`handleHiLo`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L718) (as of `2783f688`) handles the multiplication, division, and move opcodes that interact with the `hi` and `lo` registers, including the doubleword variants (`dmult`, `dmultu`, `ddiv`, `ddivu`) and doubleword variable shifts.
* [`handleJump`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L838) (as of `2783f688`) handles J-type opcodes and conforms to the MIPS specification for the instructions.
* [`handleRd`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L862) (as of `2783f688`) handles storing a value into a specified register, with a conditional flag that determines whether the value is stored or not.
* [`signExtend`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol#L625) (as of `2783f688`) performs sign-extension on a `uint64` value given the number of bits that currently represents the value, following the typical procedure for [sign-extension of signed values](https://en.wikipedia.org/wiki/Two%27s_complement#Sign_extension) represented using two's complement. On MIPS64, 32-bit arithmetic results are sign-extended to 64 bits, so this helper is used pervasively.

### Memory access: MIPS64Memory.sol

* The internal pure [`readMem`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Memory.sol#L17) (as of `2783f688`) function is a helper function that, given an 8-byte-aligned 64-bit address and the offset of a memory proof in calldata, validates the leaf node using the memory proof and then returns the specific 8-byte value to read. Note that a leaf node is 32 bytes, so at most `readMem` will only read 8 bytes due to the 64-bit MIPS architecture. The validation given a leaf node and its 59 sibling nodes follows the standard logic for verifying inclusion in a merkle tree. The address is used as the path in order to determine the order for hashing two nodes together. Once the top of the tree has been reached, and the merkle root calculated, the calculated root is checked against the merkle root stored in the VM execution `State` struct. It is up to subsequent logic (see `selectSubWord` in `MIPS64Instructions.sol`) to pick the correct sub-word position within an 8-byte word for unaligned or sub-word reads.
* The internal pure [`writeMem`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Memory.sol#L93) (as of `2783f688`) function is a helper function that, given an 8-byte-aligned 64-bit address, the offset of a memory proof in calldata, and a 64-bit value to write, calculates the new merkle root of the VM's memory. Calculating the new merkle root follows the same logic as in the `readMem` function, except that the new value replaces the leaf's targeted 8 bytes. Note that `writeMem` does not verify the proof used to calculate the new merkle root.

<Info>
  It is **critically important** that the memory proof being used is verified beforehand, by calling the `readMem` function or the [`isValidProof`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Memory.sol#L144) (as of `2783f688`) helper, against the same address.
</Info>

### Step calldata layout

The [`memoryProofOffset`](https://github.com/ethereum-optimism/optimism/blob/2783f688c503f1b10fc2e08056818ab5185044a0/packages/contracts-bedrock/src/cannon/libraries/MIPS64Memory.sol#L153) (as of `2783f688`) function handles calculating the offset in calldata to the start of a memory proof given an index, and `doStep` hardcodes and asserts the expected offsets of the `step` arguments. The `step` calldata is encoded using the [Solidity ABI encoding specification](https://docs.soliditylang.org/en/develop/abi-spec.html) and laid out as follows:

| Offset (bytes) | Num. Bytes      | Contents                                                                                                                                                    |
| -------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 0              | 4               | Function selector                                                                                                                                           |
| 4              | 32              | Offset to the first dynamic bytes argument, `_stateData`                                                                                                    |
| 36             | 32              | Offset to the second dynamic bytes argument, `_proof`                                                                                                       |
| 68             | 32              | `_localContext`, the local key context for the Pre-image oracle                                                                                             |
| 100            | 32              | Length of `_stateData`                                                                                                                                      |
| 132            | 192             | The packed 188-byte VM execution `State` struct, padded to a multiple of 32 bytes                                                                           |
| 324            | 32              | Length of `_proof`                                                                                                                                          |
| 356            | 298             | The packed `ThreadState` of the active thread (the thread witness)                                                                                          |
| 654            | 32              | The inner commitment of the rest of the active thread stack                                                                                                 |
| 686            | 60 \* 32 = 1920 | The first memory proof (required), used to read the instruction at `pc`: the leaf value followed by 59 sibling nodes                                        |
| 2606           | 60 \* 32 = 1920 | Further memory proofs as needed: one for a load/store or syscall memory access, and a second one for the two-word memory write performed by `clock_gettime` |

## Common bitwise operation use cases

1. Isolating certain bits from a number can be done using the & operator (and(x,y) in Yul), this is also known as generating a bitmask.
2. Combining bits from two numbers together can be done using the | operator (or(x, y) in Yul).
3. Modulo arithmetic can be expressed using the following bitwise operation: `x % y = x & (y - 1), ex. x % 4 = x & 3.` Note this is only equivalent for unsigned integers.
4. Multiplication using a value with a base of 2 can be expressed using the following bitwise operation: `x * y = x << z, where y = 2^z`
   Ex. `x * 8 = x << 3, where 8 = 2^3`

## Table of supported MIPS instructions

`MIPS64.sol` supports the MIPS32 instruction set previously covered by `MIPS.sol` (arithmetic, logical, shift, branch, jump, load/store, conditional move, HI/LO, `syscall`, and `sync` instructions), executed with 64-bit registers where 32-bit word operations sign-extend their results, plus the MIPS64 doubleword instructions. The authoritative decode logic is [`MIPS64Instructions.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/libraries/MIPS64Instructions.sol). The doubleword instructions added relative to the 32-bit VM are:

| Instruction Name                                   | Opcode Num. | Funct Num. |
| -------------------------------------------------- | ----------- | ---------- |
| DADD (Doubleword Add)                              | 0x00        | 0x2C       |
| DADDU (Doubleword Add Unsigned)                    | 0x00        | 0x2D       |
| DADDI (Doubleword Add Immediate)                   | 0x18        | -          |
| DADDIU (Doubleword Add Immediate Unsigned)         | 0x19        | -          |
| DSUB (Doubleword Subtract)                         | 0x00        | 0x2E       |
| DSUBU (Doubleword Subtract Unsigned)               | 0x00        | 0x2F       |
| DMULT (Doubleword Multiply)                        | 0x00        | 0x1C       |
| DMULTU (Doubleword Multiply Unsigned)              | 0x00        | 0x1D       |
| DDIV (Doubleword Divide)                           | 0x00        | 0x1E       |
| DDIVU (Doubleword Divide Unsigned)                 | 0x00        | 0x1F       |
| DSLL (Doubleword Shift Left Logical)               | 0x00        | 0x38       |
| DSRL (Doubleword Shift Right Logical)              | 0x00        | 0x3A       |
| DSRA (Doubleword Shift Right Arithmetic)           | 0x00        | 0x3B       |
| DSLL32 (Doubleword Shift Left Logical Plus 32)     | 0x00        | 0x3C       |
| DSRL32 (Doubleword Shift Right Logical Plus 32)    | 0x00        | 0x3E       |
| DSRA32 (Doubleword Shift Right Arithmetic Plus 32) | 0x00        | 0x3F       |
| DSLLV (Doubleword Shift Left Logical Variable)     | 0x00        | 0x14       |
| DSRLV (Doubleword Shift Right Logical Variable)    | 0x00        | 0x16       |
| DSRAV (Doubleword Shift Right Arithmetic Variable) | 0x00        | 0x17       |
| DCLZ (Count Leading Zeros in Doubleword)           | 0x1C        | 0x24       |
| DCLO (Count Leading Ones in Doubleword)            | 0x1C        | 0x25       |
| LD (Load Doubleword)                               | 0x37        | -          |
| SD (Store Doubleword)                              | 0x3F        | -          |
| LDL (Load Doubleword Left)                         | 0x1A        | -          |
| LDR (Load Doubleword Right)                        | 0x1B        | -          |
| SDL (Store Doubleword Left)                        | 0x2C        | -          |
| SDR (Store Doubleword Right)                       | 0x2D        | -          |
| LWU (Load Word Unsigned)                           | 0x27        | -          |
| LLD (Load Linked Doubleword)                       | 0x34        | -          |
| SCD (Store Conditional Doubleword)                 | 0x3C        | -          |

## Further reading

* [Cannon Overview](https://github.com/ethereum-optimism/optimism/blob/develop/cannon/docs/README.md)
* [Cannon FPVM Specification](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs)
* [MIPS IV ISA Specification](https://www.cs.cmu.edu/afs/cs/academic/class/15740-f97/public/doc/mips-isa.pdf)
* [MIPS Assembly Wiki Book](https://en.wikibooks.org/wiki/MIPS_Assembly)
* [Linux MIPS n64 syscall numbers](https://github.com/torvalds/linux/blob/master/arch/mips/kernel/syscalls/syscall_n64.tbl)
* [Yul Instructions](https://docs.soliditylang.org/en/latest/yul.html#evm-dialect)
* [Solidity ABI Encoding Specification](https://docs.soliditylang.org/en/develop/abi-spec.html)


# Fault proofs reference
Source: https://docs.optimism.io/op-stack/fault-proofs/reference

Reference for OP Stack dispute game types, core fault proof contracts, and standard game parameters.

This page catalogues the dispute game types, core contracts, and parameters of the OP Stack's fault proof system.
For how the system works, see the [Fault proofs explainer](/op-stack/fault-proofs/explainer) and [FP system components](/op-stack/fault-proofs/fp-components).

<Info>
  Contract addresses and several parameter values are set per chain.
  Look up the values for a specific chain in the [Superchain Registry](/op-stack/protocol/superchain-registry) or by querying the deployed contracts directly.
  The standard values on this page are the defaults `op-deployer` applies to new standard chains, as defined in [`op-deployer/pkg/deployer/standard/standard.go`](https://github.com/ethereum-optimism/optimism/blob/develop/op-deployer/pkg/deployer/standard/standard.go).
</Info>

## Dispute game types

Every dispute game is created through the `DisputeGameFactory` with a `GameType`, a `uint32` that selects which registered game implementation the factory clones.
The canonical list lives in the [`GameTypes` library](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/lib/Types.sol).

| Value | Name                  | Description                                                                                                          |
| ----- | --------------------- | -------------------------------------------------------------------------------------------------------------------- |
| 0     | `CANNON`              | Fault dispute game using the Cannon VM                                                                               |
| 1     | `PERMISSIONED_CANNON` | Permissioned dispute game using the Cannon VM; only the designated `PROPOSER` and `CHALLENGER` roles can participate |
| 2     | `ASTERISC`            | Dispute game using the Asterisc VM                                                                                   |
| 3     | `ASTERISC_KONA`       | Dispute game using the Asterisc VM with Kona                                                                         |
| 4     | `SUPER_CANNON`        | Dispute game using the Cannon VM over Super Roots (interop)                                                          |
| 5     | `SUPER_PERMISSIONED`  | Permissioned dispute game for Super Roots                                                                            |
| 6     | `OP_SUCCINCT`         | Dispute game using OP Succinct                                                                                       |
| 7     | `SUPER_ASTERISC_KONA` | Dispute game using the Asterisc VM with Kona over Super Roots                                                        |
| 8     | `CANNON_KONA`         | Dispute game using the Cannon VM with Kona                                                                           |
| 9     | `SUPER_CANNON_KONA`   | Dispute game using the Cannon VM with Kona over Super Roots                                                          |
| 10    | `ZK_DISPUTE_GAME`     | Dispute game using optimistic + ZK proofs for dispute resolution (Super Roots)                                       |
| 254   | `FAST`                | Short-duration game for testing withdrawals; not intended for production use                                         |
| 255   | `ALPHABET`            | Test game using an alphabet VM; not intended for production use                                                      |
| 1337  | `KAILUA`              | Dispute game using RISC Zero's Kailua                                                                                |

Notes:

* A game type is only playable on a chain after the `DisputeGameFactory` owner registers an implementation for it (`setImplementation`); the owner also sets the bond required to create games of that type (`setInitBond`).
* The **respected game type** (the game type whose results the system accepts for withdrawals and anchor state updates) is stored in the `AnchorStateRegistry` and can be changed by the Guardian via `setRespectedGameType`.
* `op-deployer` deploys new standard chains with the permissioned game (type `1`) as the initial game type.

## Core contracts

All fault proof contracts live in the monorepo under [`packages/contracts-bedrock/src`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock/src).
Per-chain deployment addresses are listed in the [Superchain Registry](/op-stack/protocol/superchain-registry).

| Contract                                                                                                                                                             | Purpose                                                                                                                                        |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| [`DisputeGameFactory`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/DisputeGameFactory.sol)                     | Creates dispute games as clones of registered implementations and stores them in a lookup mapping and an append-only list                      |
| [`FaultDisputeGame`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/FaultDisputeGame.sol)                         | The bisection dispute game: claims, moves, chess clocks, bonds, and onchain single-instruction steps                                           |
| [`PermissionedDisputeGame`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/PermissionedDisputeGame.sol)           | `FaultDisputeGame` variant where only the `PROPOSER` role can create games, and only the `PROPOSER` and `CHALLENGER` roles can make moves      |
| [`SuperFaultDisputeGame`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/SuperFaultDisputeGame.sol)               | Fault dispute game implementation for interop (disputes Super Roots)                                                                           |
| [`SuperPermissionedDisputeGame`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/SuperPermissionedDisputeGame.sol) | Simplified permissioned super-root game; invalid proposals are invalidated through the `AnchorStateRegistry` blacklist before finalization     |
| [`AnchorStateRegistry`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/AnchorStateRegistry.sol)                   | Stores the anchor state (the starting point for new games), the respected game type, the game blacklist, and the retirement timestamp          |
| [`DelayedWETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/DelayedWETH.sol)                                   | WETH9 extension that holds game bonds and enforces an unlock-then-delay period before withdrawal, giving the owner time to recover from errors |
| [`MIPS64`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/MIPS64.sol)                                              | Onchain fault proof VM that emulates a single MIPS instruction (the onchain half of [Cannon](/op-stack/fault-proofs/cannon))                   |
| [`PreimageOracle`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/cannon/PreimageOracle.sol)                              | Stores preimages that the fault proof VM reads during onchain execution, including the large-preimage proposal path                            |
| [`OptimismPortal2`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol)                                | Entry point for deposits and withdrawals; withdrawals are proven against dispute game results and finalized after the maturity delay           |

### Common lookup functions

| Function                                      | Contract              | Returns                                                                  |
| --------------------------------------------- | --------------------- | ------------------------------------------------------------------------ |
| `gameCount()`                                 | `DisputeGameFactory`  | Total number of games created by the factory                             |
| `gameAtIndex(uint256)`                        | `DisputeGameFactory`  | Game type, creation timestamp, and proxy address at an index             |
| `games(GameType, Claim, bytes)`               | `DisputeGameFactory`  | The game proxy (if any) matching a game type, root claim, and extra data |
| `findLatestGames(GameType, uint256, uint256)` | `DisputeGameFactory`  | The `n` most recent games of a type, starting from an index              |
| `gameImpls(GameType)`                         | `DisputeGameFactory`  | The implementation registered for a game type                            |
| `initBonds(GameType)`                         | `DisputeGameFactory`  | The bond (in wei) required to create a game of that type                 |
| `respectedGameType()`                         | `AnchorStateRegistry` | The game type currently accepted by the system                           |
| `getAnchorRoot()`                             | `AnchorStateRegistry` | The current anchor root and its L2 sequence number                       |
| `isGameBlacklisted(IDisputeGame)`             | `AnchorStateRegistry` | Whether the Guardian has blacklisted a specific game                     |
| `status()`                                    | dispute game          | The game's current `GameStatus`                                          |
| `getRequiredBond(Position)`                   | `FaultDisputeGame`    | The ETH bond (in wei) required for a move at a position                  |

## Standard parameters

Values below are the `op-deployer` standard-chain defaults.
Individual chains can deviate; always confirm against the chain's deployed configuration.

### Bisection game

| Parameter          | Standard value             | Description                                                                                                |
| ------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `maxGameDepth`     | 73                         | Maximum depth of the claim tree; at this depth a claim is resolved by an onchain VM `step`                 |
| `splitDepth`       | 30                         | Depth at which the game switches from bisecting output roots to bisecting a single block's execution trace |
| `maxClockDuration` | 302,400 seconds (3.5 days) | Maximum total time each side's chess clock may accumulate                                                  |
| `clockExtension`   | 10,800 seconds (3 hours)   | Minimum time guaranteed to respond to a claim when the clock is nearly exhausted                           |

### Timing and finality

| Parameter                         | Standard value             | Contract              | Description                                                                               |
| --------------------------------- | -------------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
| `proofMaturityDelaySeconds`       | 604,800 seconds (7 days)   | `OptimismPortal2`     | Delay between proving a withdrawal and being able to finalize it                          |
| `disputeGameFinalityDelaySeconds` | 302,400 seconds (3.5 days) | `AnchorStateRegistry` | Delay after a game resolves before its result is considered finalized                     |
| `withdrawalDelaySeconds`          | 302,400 seconds (3.5 days) | `DelayedWETH`         | Delay between unlocking a bond withdrawal and being able to execute it                    |
| `challengePeriodSeconds`          | 86,400 seconds (24 hours)  | `PreimageOracle`      | Challenge window for large-preimage proposals                                             |
| `minProposalSizeBytes`            | 126,000 bytes              | `PreimageOracle`      | Minimum size of a preimage that can be submitted through the large-preimage proposal path |

## Clocks

Each side of a fault dispute game plays against a chess clock:

* A claim inherits its clock from its grandparent claim (claims at alternating depths belong to alternating teams).
* A move can no longer be made against a claim once that claim's clock has accumulated `maxClockDuration` seconds.
* When a move would leave the responder with less than the clock extension remaining, the clock is topped up so the responder gets at least the extension time. The extension is `clockExtension` in the general case, `clockExtension * 2` for the move that starts execution-trace bisection (depth `splitDepth - 1`, to allow time to generate the instruction trace), and `clockExtension + challengePeriodSeconds` for the move before a VM step (depth `maxGameDepth - 1`, to allow for large-preimage proposals).

## Bonds

* **Creating a game** requires the initialization bond for that game type: `DisputeGameFactory.initBonds(gameType)`, set per chain by the factory owner.
* **Every move** (attack or defend) requires a bond of exactly `getRequiredBond(position)`. Bonds grow exponentially with depth: the formula in `FaultDisputeGame.getRequiredBond` charges an assumed 200 gwei base fee on a gas amount that scales from 400,000 gas at depth 0 to 300,000,000 gas at `maxGameDepth`, so each depth costs roughly 9.5% more than the one above it. A single move costs 0.08 ETH at depth 0 and 60 ETH at depth 73.
* **Playing a game to maximum depth** costs far more than the deepest single bond, because a bond is posted for every move along the path. Summing `getRequiredBond` over depths 1 through 73 gives roughly 691 ETH in total bonds (about 361 ETH for the side moving at odd depths and 330 ETH for the side at even depths), and the total is dominated by the deepest moves: depths 70 through 73 alone account for roughly 210 ETH. `FaultDisputeGame.getRequiredBond` is the source of truth for exact values.
* Bonds are held in the game's `DelayedWETH` contract and paid out only after the game resolves and is finalized, and after the `DelayedWETH` unlock delay passes.
* **Distribution mode:** when a game closes it selects a `BondDistributionMode`. A proper game (created by the `DisputeGameFactory`, not blacklisted, and not retired) distributes bonds normally: the bond of every successfully countered claim is paid to the countering party, and uncontested claims are refunded. An improper game enters refund mode and returns every bond to its original depositor.

## Game statuses

The `GameStatus` enum in [`Types.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/lib/Types.sol):

| Status            | Meaning                                                           |
| ----------------- | ----------------------------------------------------------------- |
| `IN_PROGRESS`     | The game has not been resolved                                    |
| `CHALLENGER_WINS` | The game concluded and the root claim was successfully challenged |
| `DEFENDER_WINS`   | The game concluded and the root claim could not be contested      |

## Next steps

* For the concepts behind these values, read the [Fault proofs explainer](/op-stack/fault-proofs/explainer) and [FP system components](/op-stack/fault-proofs/fp-components).
* For the honest actor that plays these games, see [OP-Challenger](/op-stack/fault-proofs/challenger).
* For the normative definitions, see the [fault dispute game specs](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html?utm_source=op-docs\&utm_medium=docs) and the [bond incentives specs](https://specs.optimism.io/fault-proof/stage-one/bond-incentives.html?utm_source=op-docs\&utm_medium=docs).


# Bridged USDC Standard on OP Stack
Source: https://docs.optimism.io/op-stack/features/bridged-usdc-standard

Overview of the Bridged USDC Standard and how chain operators can deploy it.

## Bridged USDC Standard

USDC is one of the most bridged assets across the crypto ecosystem, and USDC is often bridged to new chains prior to any action from Circle. This can create a challenge when bridged USDC achieves substantial market share, but native USDC (issued by Circle) is preferred by the ecosystem, leading to fragmentation between multiple versions of USDC. Circle introduced the [Bridged USDC Standard](https://www.circle.com/en/bridged-usdc) to ensure that chain operators can easily deploy a form of bridged USDC that is capable of being upgraded in-place by Circle to native USDC, if and when appropriate, and prevent the fragmentation problem.

Bridged USDC Standard for the OP Stack allows for an efficient and modular solution for expanding the Bridged USDC Standard across the OP Stack ecosystem.

Chain operators can use the Bridged USDC Standard for the OP Stack to get bridged USDC on their OP Stack chain while also providing the optionality for Circle to seamlessly upgrade bridged USDC to native USDC and retain existing supply, holders, and app integrations.

<Info>
  Chain operators can deploy the Bridged USDC Standard for the OP Stack, providing immediate USDC availability for their users.
  Importantly, the Bridged USDC Standard allows for a seamless, in-place upgrade to native USDC if an agreement is later reached between the chain operator and Circle.
</Info>

## Security

The referenced implementation for the OP Stack has undergone [audits from Spearbit](https://github.com/defi-wonderland/opUSDC/blob/main/audits/spearbit.pdf) and is recommended for production use.

## Next steps

* Ready to get started? Read the setup guide for the [Bridged USDC Standard for the OP Stack](https://github.com/defi-wonderland/opUSDC#setup).
* If you experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions).

## Bridged USDC Standard Factory Disclaimer

This software is provided "as is," without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

Please review [Circle's disclaimer](https://github.com/circlefin/stablecoin-evm/blob/master/doc/bridged_USDC_standard.md#for-more-information) for the limitations around Circle obtaining ownership of the Bridged USDC Standard token contract.


# Custom Gas Token
Source: https://docs.optimism.io/op-stack/features/custom-gas-token

Learn how utilize a Custom Gas Token for OP Stack chains.

Custom Gas Token (CGT) enables OP Stack chains to use any asset as their native fee currency instead of ETH.
This opens up new possibilities for chain operators to align their economic model with their specific use case, whether that's using a stablecoin for predictable fees, a governance token for ecosystem alignment, or creating an entirely new native asset.

This iteration of CGT is a redesign that prioritizes flexibility, minimal core protocol changes, and future-proof standardization by decoupling native asset management from core bridging infrastructure.

## Key features

* **Token flexibility**: Use any token as the native gas token - existing L1 ERC-20s, L2-native tokens, or entirely new assets
* **Application-layer bridging**: No bridge or token is enshrined in the protocol; bridges and converters live entirely at the application layer
* **Flexible supply management**: Chain governors have complete control over token supply, emission schedules, and distribution mechanisms
* **Future-proof design**: Built to support cross-chain interoperability

## How it works

CGT is configured at genesis and comes with two new predeploy contracts to manage native assets independently from ETH bridging:

### The `isCustomGasToken()` flag

When enabled:

* **On L1**: Placed in `SystemConfig`, instructs `OptimismPortal`, `L1CrossDomainMessenger`, and `L1StandardBridge` to reject transactions containing ETH value (`msg.value`)
* **On L2**: Located in `L1Block`, prevents ETH-related operations in `L2ToL1MessagePasser`, `L2CrossDomainMessenger`, `L2StandardBridge`, and `FeeVaults`

This enables native asset mints and burns to be decoupled from deposits and moved to the application layer.

### Two new predeploy contracts

**NativeAssetLiquidity**

Holds pre-minted native assets created at genesis with two core functions:

* `deposit()`: Receives native assets (callable only by LiquidityController)
* `withdraw()`: Releases native assets to the controller

**LiquidityController**

Governance-controlled contract that manages asset supply through:

* `authorizeMinter()` / `deauthorizeMinter()`: Grants or revokes minting permissions
* `mint()`: Unlocks assets from liquidity reserves for authorized parties
* `burn()`: Accepts native assets and locks them in the liquidity contract
* Stores token metadata for wrapped asset compatibility

## Use cases

* **Stablecoin fees**: Use USDC or other stablecoins for predictable transaction costs
* **Governance alignment**: Use your chain's governance token as the gas token to align incentives
* **L2-native economies**: Create entirely new native assets with custom supply mechanics
* **Simplified UX**: Reduce the number of tokens users need to hold for interacting with your chain

## Comparison with previous design

Custom Gas Token v2 was introduced in Upgrade 18 and is available in `op-contracts/v6.0.0`.

| Aspect             | Legacy CGT                            | CGT v2                              |
| ------------------ | ------------------------------------- | ----------------------------------- |
| **Token basis**    | Anchored to L1 ERC-20                 | Independent native asset at genesis |
| **Flexibility**    | Restricted to specific configurations | Supports any release mechanism      |
| **Bridging**       | Built into core contracts             | Application-layer responsibility    |
| **Supply control** | System transaction minting            | Minter authorization model          |
| **Adaptability**   | Limited post-deployment changes       | Upgradeable and flexible            |

<Warning>
  **Migration from legacy CGT**: There is currently no migration path from legacy CGT to CGT v2. A migration path is planned to be put together. Chains using the previous CGT design will need to coordinate a hard fork to adopt the new architecture.
</Warning>

## Developer impact

* **Decoupled from core components**: Since native asset management is decoupled from core components, obtaining native assets might vary chain-by-chain. That means that bridging, conversions, and features utilized would be different. It's suggested to create some library or templates that cover basic uses cases (e.g., L2-native, bridging from L1) to standardize most implementations.
  * Chain Governors are encouraged to audit their implementations.
  * Developers would need to look at the chain's docs to understand how to obtain native assets.
  * Ideally CGT Chain Operators can work together to formalize a common set of CGT patterns that don't come out of the box.
* **No unified API**: The flexibility of this implementation means each CGT chain may have different methods for obtaining native assets
* **ETH bridging**: ETH bridging routes through L1-WETH as an ERC-20 wrapper
* **Documentation**: Clear documentation becomes critical for users to understand how to acquire native assets

## Risks and considerations

### Supply management

* **Minter security**: Any address granted minter permissions requires thorough security review and auditing
* **Access control**: Misconfigurations in bridges or controllers could lead to unintended minting or burning
* **Rate limiting**: Consider implementing rate limits on minting velocity to reduce risk

### Configuration accuracy

* **Flag alignment**: `isCustomGasToken` must match between L1 and L2 to prevent protocol violations
* **Fee parameters**: `minBaseFee` and `operatorFee` must accurately account for execution and data availability costs in the native token's denomination
* **Decimal support**: CGT currently supports only 18-decimal tokens.
  ERC20s with different decimals require custom logic to handle rounding when converting between the token and the native asset.

## Next steps

* **For chain operators**: See [Deploy a Custom Gas Token chain](/chain-operators/guides/features/custom-gas-token-guide) for detailed deployment instructions


# Alt-DA Mode Explainer
Source: https://docs.optimism.io/op-stack/features/experimental/alt-da-mode

Learn the basic process, benefits, and considerations for running an Alt-DA mode chain.

<Warning>This is an experimental feature. Use with caution.</Warning>
Alt-DA Mode enables seamless integration of various Data Availability (DA) Layers, regardless of their commitment type, into the OP Stack. This allows any chain operator to launch an OP Stack chain using their favorite DA Layer for sustainably low costs.

## Sustainably low costs

In order to function securely, OP Stack chains need to ensure that L2 transaction data is available to all node operators. EIP-4844 has massively reduced Ethereum L1 data costs for OP Stack rollups, but blobspace is on the path to congestion, which will lead to higher blob fees and increased chain operator costs.
Over the past few years, alternative DA Layers have been built as an alternative place for L2s to post L2 data that is cheap, with more throughput, but remains stable and minimizes security and decentralization tradeoffs.

## How it works

Alt-DA Mode introduces a standard interface for reading and writing data to Alt-DA Layers and allows any DA Layer team to build and maintain their own [DA Server](https://specs.optimism.io/experimental/alt-da.html?utm_source=op-docs\&utm_medium=docs#da-server) to enable the OP Stack to communicate with their DA Layer. The DA Server handles any of the custom DA Layer logic, such as key management, interfacing with a DA Layer node, etc.

This abstraction ensures that new features and improvements to Alt-DA Mode will come to all chains using Alt-DA Mode, regardless of the DA Layer they choose to use.
Although the Data Availability Challenge (DA Challenge) will be disabled at launch, this integration provides a solution compatible with upcoming OP Stack features.

## Future improvements

Just like with the Rollup configuration of the OP Stack, core contributors are continuously improving the decentralization, security, and cost-effectiveness of Alt-DA Mode. Some of the future features that core contributors are looking to build are:

* Integration with Fault Proofs
* Alt-DA Challenges support for more DA Layers (currently only supports DA Layers with a `keccak256` commitment type)
* DA Bridge integrations (like Celestia Blobstream and Eigen DA Cert Verification)
* Increasing the amount of data that can be committed to in a single commitment (potentially with merklization)

## Tradeoffs of Alt-DA Mode

Alt-DA Mode will always have more trust assumptions than simply posting data to L1 Ethereum. In its current initial iteration, Alt-DA Mode with generic commitments fully trusts the chain operator to make data available by both posting all data to the DA Layer and posting corresponding commitments to L1 Ethereum. If a chain operator posts incorrect commitments or does not post data to the DA Layer, it will not be accessible by node operators. The future improvements mentioned above are intended to address this trust assumption. After DA Bridges are integrated, then as long as the DA Layer and its DA Bridge are decentralized and functioning as intended, then once data is posted to the DA Layer, the L1 commitments would be bridged without relying on a single trusted party. It is important to remember that, even after integrating the DA Bridges and Fault Proofs, there will still be an added trust assumption that the DA Layer and DA Bridge are secure and functioning as intended.

## Next steps

* Ready to get started? Read our guide on how to [deploy your Alt-DA Mode chain](/chain-operators/guides/features/alt-da-mode-guide).
* For more info about how Alt-DA Mode works under the hood, [check out the specs](https://specs.optimism.io/experimental/alt-da.html?utm_source=op-docs\&utm_medium=docs).

## FAQs

### Can I deploy a chain using Ethereum L1 DA and later switch to Alt-DA?

While it is a future goal to spec out a migration path from Ethereum L1 DA to Alt-DA Mode, the migration path has not been scoped out yet.

### Can I deploy a chain using Alt-DA and then later switch to Ethereum L1 DA?

Same as above, it is a future goal to spec out this migration path, but the migration path has not been scoped out yet.

### Can I switch between Alt-DA layers when using Alt-DA Mode?

This is technically possible today. A chain operator can start posting data to two DA Layers simultaneously during a transition period and coordinates their node operators to switch the DA Server they operate during that time.
If assistance is needed here, please reach out [via Github](https://github.com/ethereum-optimism/developers/discussions)


# L2 Contract Manager
Source: https://docs.optimism.io/op-stack/features/l2-contract-manager

Learn how the L2 Contract Manager (L2CM) enables governance-approved L2 smart contract upgrades through the consensus layer.

The L2 Contract Manager (L2CM) is a new mechanism that enables governance-approved upgrades to L2 smart contracts (predeploys) as part of a network upgrade. L2CM executes predeploy upgrades atomically and in a structured, auditable way — eliminating the need for individual multisig transactions per contract and reducing upgrade complexity for the entire OP Stack ecosystem.

## Overview

Before L2CM, upgrading L2 predeploy contracts required individual multisig transactions for each contract, coordinated outside the normal upgrade process. L2CM replaces this with a single atomic upgrade triggered automatically by the consensus layer at the start of a hard fork block, using a Network Upgrade Transaction (NUT).

L2CM is a prerequisite for interoperability and future protocol upgrades that need to modify L2 contracts.

## How it works

L2CM is implemented as the `L2ContractsManager` contract, which holds the new implementation addresses for all predeploys as immutables. During a network upgrade activation:

1. The consensus layer (`op-node`) emits a Network Upgrade Transaction (NUT) targeting the `L2ProxyAdmin` predeploy.
2. The `L2ProxyAdmin` executes a `DELEGATECALL` to the `L2ContractsManager.upgrade()` function.
3. `upgrade()` reads chain-specific configuration from the current state — `L1Block` (for `isCustomGasToken`, `isInterop`), fee vault recipients, bridge addresses, and other per-chain parameters.
4. Using this configuration, `L2ContractsManager` upgrades and re-initializes every predeploy in a single atomic transaction.

Because `upgrade()` is called via `DELEGATECALL` from `L2ProxyAdmin`, no multisig approval is needed for individual contracts — the upgrade is entirely encoded in the `L2ContractsManager` deployment and activated by governance through the normal network upgrade process.

## What gets upgraded

Each `L2ContractsManager` deployment ships new implementations for all core L2 predeploys, including:

* `L2CrossDomainMessenger`
* `L2StandardBridge`
* `L2ERC721Bridge`
* `L1Block`
* `L2ToL1MessagePasser`
* `GasPriceOracle`
* `OptimismMintableERC20Factory`
* `OptimismMintableERC721Factory`
* Fee vaults (`SequencerFeeWallet`, `BaseFeeVault`, `L1FeeVault`, `OperatorFeeVault`)
* `ProxyAdmin`
* Interop contracts (`CrossL2Inbox`, `L2ToL2CrossDomainMessenger`, `SuperchainETHBridge`, `ETHLiquidity`) when interop is enabled
* Custom Gas Token contracts (`NativeAssetLiquidity`, `LiquidityController`) when CGT is enabled

The exact set of upgraded contracts and their new versions is documented in the changelog for each network upgrade.

## Why it matters

* **Atomic upgrades:** All predeploys are upgraded in a single transaction, eliminating partial upgrade states.
* **Reduced multisig overhead:** No per-contract signing required; the upgrade is encoded at deployment time and activated through the governance-approved hard fork.
* **Auditable:** The full set of implementation changes is visible in the `L2ContractsManager` source code before the upgrade activates.
* **Interop prerequisite:** Interop requires coordinated changes across multiple predeploys; L2CM makes this feasible.
* **Stage 1 decentralization:** By routing L2 predeploy upgrades through the Security Council-owned `L2ProxyAdmin`, L2CM satisfies the Stage 1 requirement that the Security Council has a blocking vote on L2 upgrades.

## For app developers

If your application interacts directly with predeploy contracts (for example, calling methods on `L2CrossDomainMessenger`, `L2StandardBridge`, or `L1Block`), be aware that:

* Predeploy behavior may change with each network upgrade. Review the changelog for the specific upgrade to understand new functions, removed functions, or behavior changes.
* Proxy addresses remain stable — only implementations change.
* Existing ABIs remain backward-compatible unless a breaking change is explicitly noted in the upgrade changelog.

## References

* [L2CM design document](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/l2-contract-upgrades.md)
* [L2CM FMA](https://github.com/ethereum-optimism/design-docs/blob/main/security/fma-l2cm.md)
* [Upgrade 19 notice](/notices/archive/upgrade-19)
* [L2ContractsManager source](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ContractsManager.sol)


# Osaka on L2
Source: https://docs.optimism.io/op-stack/features/osaka-on-l2

Learn about the Osaka EIP activations on L2, including the EIP-7825 per-transaction gas limit and precompile gas changes.

Upgrade 19 activates a subset of the Osaka EIPs on L2 — specifically the changes that are applicable to OP Stack chains. Not every Osaka EIP is relevant to L2 execution; only those that affect L2 transaction processing or precompile behavior are included.

The activated changes introduce a per-transaction gas limit and updated gas costs for two precompiles.

## EIP-7825: Per-transaction gas limit

[EIP-7825](https://eips.ethereum.org/EIPS/eip-7825) introduces a maximum gas limit that any single L2 transaction can request. After Upgrade 19, transactions whose gas limit exceeds this threshold are rejected as invalid by the execution layer.

The EIP-7825 limit is 2^24 = **16,777,216 gas**.
It is enforced by the execution client (`op-reth`).

### Deposit transactions are exempt

Deposit transactions (L1-to-L2 messages) are **not** subject to the EIP-7825 limit. Deposits are already capped at 20M gas total per L1 block, and rejecting a deposit on L2 that was accepted on L1 would cause permanent ETH loss. System deposit transactions (e.g., network upgrade transactions) are also exempt.

### Impact on app developers

Most transactions will not be affected. The limit is designed to be well above gas requirements for typical application interactions. If your application submits transactions with very high gas limits, verify they remain within the new threshold.

If your application constructs raw transactions programmatically and sets a gas limit above the threshold, those transactions will fail. Update your gas limit logic or rely on standard `eth_estimateGas` responses — estimates will not return a value above the limit.

## MODEXP gas cost and input size changes

[EIP-7883](https://eips.ethereum.org/EIPS/eip-7883) raises the `MODEXP` precompile (`0x05`) gas cost floor from 200 to 500 gas.
[EIP-7823](https://eips.ethereum.org/EIPS/eip-7823) caps the modulus size at 1024 bytes — calls with a larger declared modulus fail.

* **For contracts using `MODEXP`:** re-run gas benchmarks and update any hardcoded gas values. Verify that your modulus inputs are within the 1024-byte limit.
* **For contracts not using `MODEXP`:** no action required.

## P256VERIFY gas cost change

[EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) raises the `P256VERIFY` precompile (`0x100`) gas cost from 3,450 (RIP-7212) to **6,900 gas**.

* **For contracts using `P256VERIFY`:** re-run gas benchmarks and update any hardcoded gas values.
* **For contracts not using `P256VERIFY`:** no action required.

## CLZ opcode

[EIP-7939](https://eips.ethereum.org/EIPS/eip-7939) introduces the Count Leading Zeros opcode (`CLZ`, `0x1e`).
Given a `uint256`, it returns the number of leading zero bits (0–255).

* **For contract developers:** the opcode is now available for use. Existing contracts are not affected.
* **For toolchain authors:** assemblers and decompilers that treat unknown opcodes as invalid should add `CLZ` support.

## Summary of changes

| Change                                             | EIP                                                 | OPCODE        | Impact                                                     |
| -------------------------------------------------- | --------------------------------------------------- | ------------- | ---------------------------------------------------------- |
| Per-transaction gas limit (16,777,216 gas)         | [EIP-7825](https://eips.ethereum.org/EIPS/eip-7825) | n/a           | Transactions above the limit are invalid (deposits exempt) |
| `MODEXP` gas floor increase (200 → 500 gas)        | [EIP-7883](https://eips.ethereum.org/EIPS/eip-7883) | `0x05`        | Gas cost changes                                           |
| `MODEXP` modulus size cap (1024 bytes)             | [EIP-7823](https://eips.ethereum.org/EIPS/eip-7823) | `0x05`        | Inputs over 1024-byte modulus fail                         |
| `P256VERIFY` gas cost increase (3,450 → 6,900 gas) | [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) | `0x100`       | Gas cost changes                                           |
| CLZ (Count Leading Zeros) opcode                   | [EIP-7939](https://eips.ethereum.org/EIPS/eip-7939) | opcode `0x1e` | New opcode available                                       |

## References

* [Karst spec overview](https://specs.optimism.io/protocol/karst/overview.html)
* [Karst exec-engine spec](https://specs.optimism.io/protocol/karst/exec-engine.html)
* [Osaka on L2 design document](https://github.com/ethereum-optimism/design-docs/blob/main/protocol/osaka-on-l2.md)
* [EIP-7825](https://eips.ethereum.org/EIPS/eip-7825)
* [EIP-7883](https://eips.ethereum.org/EIPS/eip-7883)
* [EIP-7823](https://eips.ethereum.org/EIPS/eip-7823)
* [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951)
* [EIP-7939](https://eips.ethereum.org/EIPS/eip-7939)
* [Upgrade 19 notice](/notices/archive/upgrade-19)


# OP Stack preinstalls
Source: https://docs.optimism.io/op-stack/features/preinstalls

Learn how to use preinstalls on your chain.

This guide explains OP Stack preinstalls and what they bring to developers.
To go to production on a new chain, developers need their core contracts: Gnosis Safes, the 4337 entrypoint, create2deployer, etc. On a blank EVM, these contracts can take weeks to be deployed. Now, core contracts come *preinstalled* on the OP Stack -- no third party deployment necessary.
Whether hacking alone or starting the next big rollup, developers can start using their favorite contracts as soon as they spin up their chain.

Preinstalls place these core smart contracts at their usual addresses in the L2 genesis state, to ensure that they're usable as soon as a chain is initialized.
With these contracts preinstalled at set addresses, developers can also expect all these contracts to be present at set addresses on OP Stack chains.

<Info>
  Preinstalls are automatically enabled for all new OP chains after Ecotone.
</Info>

## Contracts and deployed addresses

This table lists the specific contracts to be pre/deployed for new OP Chains.

| Contract                                                                                                                            | Deployed Address for New OP Chains                                                                                                                                                    |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`Safe`](https://github.com/safe-global/safe-smart-account/blob/v1.3.0/contracts/GnosisSafe.sol)                                    | referencing the [artifacts file](https://github.com/ethereum-optimism/optimism/blob/v1.1.4/op-bindings/artifacts.json) (as of `v1.1.4`): `0x69f4D1788e39c87893C980c06EdF4b7f686e2938` |
| [`SafeL2`](https://github.com/safe-global/safe-smart-account/blob/v1.3.0/contracts/GnosisSafeL2.sol)                                | `0xfb1bffC9d739B8D520DaF37dF666da4C687191EA`                                                                                                                                          |
| [`MultiSend`](https://github.com/safe-global/safe-smart-account/blob/v1.3.0/contracts/libraries/MultiSend.sol)                      | `0x998739BFdAAdde7C933B942a68053933098f9EDa`                                                                                                                                          |
| [`MultiSendCallOnly`](https://github.com/safe-global/safe-smart-account/blob/v1.3.0/contracts/libraries/MultiSendCallOnly.sol)      | `0xA1dabEF33b3B82c7814B6D82A79e50F4AC44102B`                                                                                                                                          |
| [Safe Singleton Factory](https://github.com/safe-global/safe-singleton-factory/blob/main/source/deterministic-deployment-proxy.yul) | `0x914d7Fec6aaC8cd542e72Bca78B30650d45643d7`                                                                                                                                          |
| [`Multicall3`](https://github.com/mds1/multicall/tree/main)                                                                         | `0xcA11bde05977b3631167028862bE2a173976CA11`                                                                                                                                          |
| [`create2Deployer`](https://github.com/pcaversaccio/create2deployer)                                                                | `0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2`                                                                                                                                          |
| [`CreateX`](https://github.com/pcaversaccio/createx)                                                                                | `0xba5Ed099633D3B313e4D5F7bdc1305d3c28ba5Ed`                                                                                                                                          |
| [Arachnid's Deterministic Deployment Proxy](https://github.com/Arachnid/deterministic-deployment-proxy)                             | `0x4e59b44847b379578588920cA78FbF26c0B4956C`                                                                                                                                          |
| [`Permit2`](https://github.com/Uniswap/permit2)                                                                                     | `0x000000000022D473030F116dDEE9F6B43aC78BA3`                                                                                                                                          |
| [ERC-4337 v0.6.0 `EntryPoint`](https://github.com/eth-infinitism/account-abstraction/tree/v0.6.0)                                   | `0x5FF137D4b0FDCD49DcA30c7CF57E578a026d2789`   <br /> `SenderCreator` dependency @ `0x7fc98430eAEdbb6070B35B39D798725049088348` on ETH mainnet                                        |
| [ERC-4337 v0.6.0 `SenderCreator`](https://github.com/eth-infinitism/account-abstraction/tree/v0.6.0)                                | `0x7fc98430eAEdbb6070B35B39D798725049088348`                                                                                                                                          |
| [ERC-4337 v0.7.0 `EntryPoint`](https://github.com/eth-infinitism/account-abstraction/tree/v0.7.0)                                   | `0x0000000071727De22E5E9d8BAf0edAc6f37da032`   <br /> `SenderCreator` dependency @ `0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C` on ETH mainnet                                        |
| [ERC-4337 v0.7.0 `SenderCreator`](https://github.com/eth-infinitism/account-abstraction/tree/v0.7.0)                                | `0xEFC2c1444eBCC4Db75e7613d20C6a62fF67A167C`                                                                                                                                          |


# SendRawTransactionConditional explainer
Source: https://docs.optimism.io/op-stack/features/send-raw-transaction-conditional

Learn about the eth_sendRawTransactionConditional RPC method for conditional transaction inclusion on the OP Stack.

A sequencer RPC method, `eth_sendRawTransactionConditional`, allows callers to conditionally include a transaction based on a set of provided options.

This feature is meant to unblock use cases that require atomic inclusion, otherwise possible on Ethereum through specialized block builders like Flashbots. Some examples:

* 4337 Bundlers utilizing a shared mempool of UserOperations. Reverted transactions due to conflicting UserOperations would make it too costly for bundlers to operate on L2, forcing the use of private mempools.

## Specification

This endpoint is an extension of `eth_sendRawTransaction`, with an extra parameter of "options" with the following structure:

```
{
    "knownAccounts": [optional] A map of accounts with expected storage. The key is account address
                                If the value is hex string, it is the known storage root hash of that account.
                                If the value is an object, then each member is in the format of "slot": "value", which are explicit slot values within that account storage.
    "blockNumberMin": [optional] minimal block number for inclusion
    "blockNumberMax": [optional] maximum block number for inclusion
    "timestampMin": [optional] minimum block timestamp for inclusion
    "timestampMax": [optional] maximum block timestamp for inclusion
}
```

The "cost" of a given conditional is *approximately* determined by the number of storage lookups that would be incurred by validating this conditional. There's a predefined max of `1000` that is allowed to prevent DoS.

<Info>
  Since the sequencer is not compensated for the additional state checks, otherwise through the GAS of the transaction, a configured rate limit is applied to this cost.

  To also discourage the use of this endpoint for MEV in comparison to `eth_sendRawTransaction`, the conditional is checked against the parent of the latest block.
</Info>

This conditional is checked once at the RPC layer prior to mempool submission. If rejected against chain state, the RPC will return an error with the following spec

* error code `-32003` (transaction rejected) with a reason string as to the specific failed check
* error code `-32005` (conditional cost) with a reason string if the conditional cost exceeded the maximum OR the cost was rate limited due to network conditions.

Successful submission does **NOT** guarantee inclusion! The caller must observe the chain for a receipt with some timeout to determine non-inclusion. The conditional is also re-checked in the block building phase to handle intra-block conflicts.

<Info>
  Conditional transactions are tied to the block builder they are submitted to. This means that these transactions **are not gossiped between configured peers!!!**

  If you are running an active/passive setup with replicas that gossip txs to an active sequencer, this endpoint should be fronted by a proxy that can broadcast the request to all replicas.
</Info>

## How to enable

This feature can be enabled with the addition of a flag to op-geth.

* `--rollup.sequencertxconditionalenabled` (default: false) a boolean flag which enables the rpc.
* `--rollup.sequencertxconditionalcostratelimit` (default: 5000) an integer flag that sets the rate limit for cost observable per second.

<Info>
  It is not advised to publicly expose this sequencer endpoint due to DoS concerns. This supplemental proxy, [op-txproxy](/chain-operators/tools/op-txproxy), should be used to apply additional constraints on this endpoint prior to passing through to the sequencer.
</Info>


# Span Batches
Source: https://docs.optimism.io/op-stack/features/span-batches

Learn what span batches are and how they reduce the batch submission overhead of OP Stack chains.

Span batches are a batch format, introduced in the Delta network upgrade, that encodes a span of consecutive L2 blocks in a single batch.
They reduce the overhead of posting L2 data to L1, which lowers data availability costs — especially for sparse, low-throughput chains where fixed per-block overhead dominates the submitted data.

## Why span batches exist

Before Delta, the only batch format was the singular batch: one batch per L2 block.
Every block — including empty blocks on a quiet chain — carried its own batch overhead to L1.

A span batch instead represents a whole span of consecutive L2 blocks in a more efficient encoding, while preserving the same consistency checks as singular batch data.
That makes the marginal cost of including an additional (especially empty) block in the submitted data small.
The full format is defined in the [span batches specification](https://specs.optimism.io/protocol/delta/span-batches.html?utm_source=op-docs\&utm_medium=docs).

## How span batches are used

Span batches are opt-in for the chain operator: the `op-batcher` selects the batch format with its `--batch-type` flag (`0` for singular batches, the default; `1` for span batches).
On the verification side, the `op-node` derivation pipeline accepts span batches only once Delta is active on the chain — it drops any span batch whose L1 origin predates Delta activation.
Singular batches remain valid after Delta, so a chain can switch between the two formats at any time.

To turn span batches on for your chain, follow the how-to guide: [Enable span batches](/chain-operators/guides/features/enable-span-batches).

## Links to related pages

* [Enable span batches](/chain-operators/guides/features/enable-span-batches)
* [Configure the batcher](/chain-operators/guides/configuration/batcher)
* [Span Batches Specification](https://specs.optimism.io/protocol/delta/span-batches.html?utm_source=op-docs\&utm_medium=docs)
* [Span Batch Design Docs](https://op-tip.notion.site/Span-Batch-Design-Docs-b85e599a47774dcdb8171cc84cab2476)


# Subblocks
Source: https://docs.optimism.io/op-stack/features/subblocks

Understand how Subblocks deliver 200 ms pre-confirmations on OP Stack chains, what a subblock payload contains, and which guarantees they preserve.

*Subblocks* (formerly Flashblocks) are partial blocks that an OP Stack sequencer streams while it is still building the full block.
A subblock arrives every 200 ms, so an application can act on a transaction's outcome well before the block containing it is sealed — roughly ten times sooner on a chain with a 2-second block time.

This page explains what a subblock is, what its payload does and does not carry, and how production is arranged.
To read pre-confirmed state from an application, follow the [app integration guide](/app-developers/guides/transactions/integrating-subblocks).
For the current interval and payload changes on OP Sepolia and OP Mainnet, see the [Subblocks notice](/notices/subblocks).

## How it works

A sequencer normally executes an entire block and publishes it once, at the end of the block time.
Subblocks split that window: the sequencer publishes what it has executed so far every 200 ms, and each subblock extends the previous one.

Two properties follow from that, and both matter to anyone consuming the stream.

* **A subblock sequence is append-only.** The final sealed block is the concatenation of every subblock in the sequence, in order.
  Transactions already emitted in a subblock are never reordered or dropped from the block that seals them.
* **A subblock is a projection, not a commitment.** It reports the transactions executed so far. It does not prove the resulting state.

The first subblock in a sequence carries the block's deposit transactions, because those execute before any transaction from the mempool is considered.
Subsequent subblocks each add a batch of mempool transactions.

The 200 ms interval is a target rather than a guarantee.
Heavy execution in one interval leaves less time for the ones after it, so the number of subblocks in a block varies.

## What a subblock payload carries

The payload is wire compatible with the Flashblocks format that preceded it, and the type is still named `ExecutionPayloadFlashblockDeltaV1`.
No field was added or removed. Four fields are present but set to their zero value:

| Field              | Value on the stream |
| ------------------ | ------------------- |
| `state_root`       | `0x0000...0000`     |
| `block_hash`       | `0x0000...0000`     |
| `withdrawals_root` | `0x0000...0000`     |
| `withdrawals`      | `[]`                |

Every other field carries a real value, including `transactions`, `gas_used`, `receipts_root`, and `logs_bloom`.

The state root is the root cause.
It is computed while execution continues and is only exact once the block is sealed, so a subblock cannot carry it.
A block hash commits to the state root, so it cannot be final either.

<Warning>
  Because the payload stayed wire compatible, reading a zeroed field returns a zero value rather than raising an error.
  An integration that treats the stream's `state_root` or `block_hash` as authoritative will fail silently.
  Treat both as absent, and derive state by executing the transactions the subblock carries.
</Warning>

A node that consumes the stream does not need the zeroed fields.
It executes the subblock's transactions against its own view of the chain and serves the result under the `pending` block tag, so `eth_call` and `eth_getBalance` answer correctly without any root on the wire.

## Architecture

Subblocks are produced by the sequencer's execution client as it builds the block, and published over a WebSocket stream.
Nothing sits between the consensus layer and the execution layer.

```mermaid theme={null}
flowchart LR
    classDef chain fill:#FFE

    subgraph sequencer[Sequencer]
        ON[OP Node]
        EL[Execution Client]
    end

    subgraph network[Network]
        WSP[WebSocket Proxy]
    end

    subgraph clients[Clients]
        RPC[RPC Providers]
        Apps[Applications]
    end

    ON --> EL
    EL --> WSP
    WSP --> RPC
    RPC --> Apps

    class sequencer chain
```

* **`op-node`** drives block building through the engine API, exactly as it does on a chain without subblocks.
* **The execution client** executes the block and publishes a subblock every 200 ms while it does so.
* **`flashblocks-websocket-proxy`** relays the stream from the active sequencer to RPC providers.
* **`op-conductor`** *(optional)* manages a multi-sequencer setup so only the healthy leader's stream reaches the proxy.

Producing subblocks is available to OP Enterprise customers.
Consuming them is not restricted: any node can follow the stream, and any application can read pre-confirmed state from a provider that does.

### The Flashblocks stack

Before subblocks, pre-confirmations were produced by the Flashblocks stack: `rollup-boost` coordinating between the consensus layer and two execution clients, with `op-rbuilder` building blocks and `op-reth` standing by as a fallback builder.

<Warning>
  The Flashblocks stack may still run, but OP Labs offers **no support** for it.
  It may stop working at a future fork.
  Chains running `rollup-boost` and `op-rbuilder` should plan a migration.
</Warning>

For availability information, see [Enabling Subblocks](/chain-operators/guides/features/subblocks-guide).

## Subblocks FAQ

### Block building and availability

<Expandable title="How often are subblocks produced?">
  Every 200ms, but configurable to lower values.
  OP Sepolia and OP Mainnet both move to 200 ms; see the [Subblocks notice](/notices/subblocks) for the rollout dates.
</Expandable>

<Expandable title="Will a block always contain the maximum number of subblocks?">
  No. Heavy execution in one interval reduces the time available for the ones after it, so the count varies between blocks.
</Expandable>

<Expandable title="Do large transactions get delayed?">
  A large transaction can land in any subblock with enough gas capacity left, so in practice it lands later in the block.
  See [Subblocks and gas usage](/app-developers/guides/transactions/subblocks-and-gas-usage) for a worked example.
</Expandable>

### Safety and continuity

<Expandable title="What happens if the sequencer fails mid-block?">
  The subblocks already published for the abandoned block do not seal.
  In a multi-sequencer setup, `op-conductor` transfers leadership to a healthy sequencer, and the stream continues from the new leader through the same endpoint.
  For details, see the [op-conductor documentation](/chain-operators/tools/op-conductor).
</Expandable>

<Expandable title="Do subblocks change the safety model of the chain?">
  No. Every transaction in a subblock is executed by the same engine, under the same rules, as it would be in a block. Subblocks change when the sequencer tells you the outcome, not what the outcome is.
</Expandable>

<Expandable title="Can a pre-confirmation be revoked?">
  Yes, under the same conditions that let the sequencer reorg an unsafe block. A pre-confirmation carries the sequencer's trust assumption, not the protocol's. See [Transaction finality](/op-stack/transactions/transaction-finality) for what each stage guarantees.
</Expandable>

<Expandable title="What does a pre-confirmation response contain?">
  The transactions executed so far in the block, their receipts, and the cumulative `gas_used`, `receipts_root`, and `logs_bloom`.
  It does not contain a usable `state_root` or `block_hash` — both are zeroed, as described in [what a subblock payload carries](#what-a-subblock-payload-carries).
</Expandable>

## Next steps

* Read pre-confirmed state from your app with the [Subblocks integration guide](/app-developers/guides/transactions/integrating-subblocks).
* Check the [Subblocks notice](/notices/subblocks) for rollout dates and the payload fields to audit.
* Learn how subblocks change [gas availability within a block](/app-developers/guides/transactions/subblocks-and-gas-usage).


# OP Stack interoperability explainer
Source: https://docs.optimism.io/op-stack/interop/explainer

Learn the basics of OP Stack interoperability.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

<Info>
  **Learn the OP Stack — stop 12 of 13.**
  You understand how a single chain stays secure. This page adds where
  the stack is going: interoperability that makes a network of chains
  feel like a single blockchain. When you're done, continue to the
  capstone, [Running a node with Docker](/node-operators/tutorials/node-from-docker).
</Info>

# OP Stack interoperability

It is easy for a blockchain to be certain about information it generates itself.
Information that comes from other sources is harder to provide in a safe, decentralized, and uncensorable manner (this is called [The Oracle Problem](https://chain.link/education-hub/oracle-problem)).
The next major scalability improvement to the OP Stack is to enable a network of chains to feel like a single blockchain.
This goal requires low-latency, seamless message passing and asset bridging.

*OP Stack interoperability* is a set of protocols that lets OP Stack blockchains read each other's state.
OP Stack interoperability provides the following benefits:

* ETH and ERC-20 tokens move securely between chains via native minting and burning. Asset interoperability solves the issues of liquidity fragmentation and poor user experiences caused by asset wrapping or liquidity pools.
* Apps can compose with data that exists on other chains.
* Horizontal scalability for applications that need it.

## Interoperability architecture

A pre-interop OP Stack node consists of two pieces of software: a consensus client (e.g. op-node) that drives derivation, and an execution client that processes user transactions and constructs blocks (e.g. op-geth).

OP Stack interop adds cross-chain message verification on top of that pipeline. Before any chain advances past a block that contains an executing message, the matching initiating message has to be reproduced from the source chain. Tracking every chain in the dependency set is on the critical path: a local block whose dependencies cannot be proved stays unsafe.

That verification work is performed by [op-supernode](/op-stack/interop/supernode), a component that hosts the consensus layer of every chain in a dependency set together and runs the cross-chain checks above the per-chain layer. Each chain's CL stays the single source of truth for safety on its own chain; the supernode signals "advance" or "invalidate" through a narrow authority interface that the CL defers to.

```mermaid theme={null}

graph TB
  classDef supernode fill:#FFE,stroke:#aa8
  classDef execution fill:#EFE
  classDef l1 fill:#FEE,stroke:#a88

  l1[L1 consensus layer]

  subgraph SN["op-supernode"]
    direction LR
    cla["Chain A CL"]
    clb["Chain B CL"]
    clc["Chain C CL"]
    iv["Cross-chain<br/>verification"]
  end

  ela["Chain A<br/>execution client"]
  elb["Chain B<br/>execution client"]
  elc["Chain C<br/>execution client"]

  l1-->|block data + status|SN
  cla<-->ela
  clb<-->elb
  clc<-->elc

  class SN supernode
  class ela,elb,elc execution
  class l1 l1
```

A participant in interop indexes the log events of every chain in its dependency set, because any of those events can serve as an initiating message. It also reads from L1's consensus layer to determine the safety of L2 blocks.

Following every chain in a dependency set is expensive: each one needs derivation, an execution engine, and the cross-chain bookkeeping that interop introduces. op-supernode collapses that cost by running every chain together in a single process, with a shared L1 client and beacon client serving all of them. For a fully-connected cluster like the [Superchain interop cluster](#superchain-interop-cluster), this is the topology the cross-chain verification is designed to run on. See the [op-supernode explainer](/op-stack/interop/supernode) for the architecture.

## How messages get from one chain to the other

A cross-chain message takes two transactions: one on the source chain and one on the destination.

```mermaid theme={null}

sequenceDiagram
    participant app as Application
    participant src as Source Chain
    participant dst as Destination Chain Node
    app->>src: Transaction
    src->>dst: Log event
    note over src,dst: Log event = initiating message
    app->>dst: Transaction with access list
    dst->>dst: Verify the initiating message exists on source.
    dst->>dst: CrossL2Inbox.validateMessage emits ExecutingMessage.
    note over dst: Executing message
```

The first transaction creates an *initiating message* on the source chain. The initiating message is just a log event — any log event on any chain in the destination's dependency set can initiate a cross-domain message.

The second transaction creates an *executing message* on the destination chain. It calls the [`CrossL2Inbox`](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#crossl2inbox) predeploy to claim that a specific log event happened on a specific source chain. The call to `CrossL2Inbox` can come from an externally owned account or, more commonly, from a smart contract such as the [`L2ToL2CrossDomainMessenger`](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs#l2tol2crossdomainmessenger).

Each executing message [identifies the initiating message uniquely](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L13-L19) by its source chain ID, the source contract address (`origin`), the source block number, the log index within the block, and the source block timestamp. If everything checks out, `CrossL2Inbox` emits an `ExecutingMessage` event recording the cross-chain reference.

### Validating messages with access lists

`CrossL2Inbox` itself never reads other chains' state. It just verifies that the executing transaction has *pre-declared* every cross-chain message it intends to use, so that the destination chain's node can check those declarations against its index of source-chain logs *before* the transaction is allowed into a block.

The declarations live in the transaction's [EIP-2930 access list](https://eips.ethereum.org/EIPS/eip-2930), targeting the `CrossL2Inbox` predeploy address. For each executing message, the [interop access-list spec](https://specs.optimism.io/interop/predeploys.html#access-list) defines up to three typed storage-key entries:

1. A **lookup-identity** entry that packs the source chain ID, block number, log timestamp, and log index. This is the hint the node uses to find the referenced log in its index.
2. An optional **chain-ID extension** entry, only present when the source chain ID does not fit in 64 bits.
3. A **checksum** entry: a versioned hash that commits to the message's full `Identifier` and message hash. This is the only entry the EVM itself touches.

Before block inclusion, the node iterates over each access-list entry that targets `CrossL2Inbox`, reconstructs the message it points at, and confirms that an initiating log with that identifier and hash really exists on the source chain at the required safety level. Any unrecognized entry, or any entry that points at a message the node cannot prove, fails the check and the transaction is dropped.

Inside the EVM, [`CrossL2Inbox.validateMessage`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L76-L82) recomputes the checksum from the `Identifier` and `msgHash` it was called with, and uses gas-cost measurement to confirm the matching storage slot is "warm" — meaning the checksum entry really was in the access list. A missing or wrong entry reverts with `NotInAccessList`, so a transaction that bypassed (or contradicts) the node's pre-check can never succeed at runtime. Because deposit transactions cannot carry access lists, calls to `CrossL2Inbox.validateMessage` from inside a deposit always revert.

The access-list mechanism gives sequencers, builders, and verifiers a uniform, EVM-free way to drop transactions whose referenced messages do not exist — including under reorgs and equivocation — before they are ever included in a block.

## Block safety levels

OP Stack interop preserves the same three safety levels app developers and node operators are already used to:

```mermaid theme={null}

flowchart LR
    classDef safe fill:#8F8
    classDef unsafe fill:#F89

    subgraph A ["Chain A"]
      A100["A<sub>100</sub>"]-->A101["A<sub>101</sub>"]-->A102["A<sub>102</sub>"]-->A103["A<sub>103</sub>"]
    end
    subgraph B ["Chain B"]
      B300["B<sub>300</sub>"]-->B301["B<sub>301</sub>"]-->B302["B<sub>302</sub>"]-->B303["B<sub>303</sub>"]
    end
    A101-.->B302
    B300-.->A100
    class A100,B300,B301 safe
    class A101,A102,A103,B302,B303 unsafe
```

* **Unsafe**. The block has been produced and shared over the gossip protocol, but its source data has not yet been written to L1. The sequencer that produced it could still equivocate.
* **Safe**. The block has been derived from data on L1 *and* every initiating message it references has itself reached at least the same safety level. Once a block is safe, no participant — including the sequencer — can roll it back without an L1 reorg.
* **Finalized**. The L1 data the block was derived from is finalized on L1 and is no longer subject to L1 reorgs.

The crucial property of interop is the second bullet: a block is only treated as safe once everything it depends on is also safe. In the diagram above, blocks B<sub>302</sub> and B<sub>303</sub> on chain B both reference initiating messages from chain A. They cannot become safe until A<sub>101</sub> (and every block leading up to it) has also been written to L1.

This dependency check is what protects users against a [double-spend across chains](/op-stack/interop/reorg). When a sequencer chooses to accept executing messages that reference unsafe initiating messages, it gets the lowest possible cross-chain latency, but it takes on the trust assumption that every sequencer in its [transitive dependency set](#what-is-the-transitive-dependency-set) will eventually post the data it gossiped. If any of them equivocates, the executing-message blocks are reorged out and replaced with deposit-only blocks. For a deeper discussion of the latency / security trade-off and how a chain operator can configure the minimum safety level it will accept for an inbound message, see [Cross-chain security measures](/op-stack/security/interop-security).

<Expandable title="What is the transitive dependency set?">
  The dependency set of a chain is the set of chains it directly accepts initiating messages from. The *transitive* dependency set also includes the dependencies of those chains, and so on.

  ```mermaid theme={null}

  flowchart LR
      A[Chain A] <--> B[Chain B]
      B <--> C[Chain C]
      B <--> D[Chain D]
      D <--> E[Chain E]
      F[Chain F] <--> G[Chain G]
  ```

  In the picture above, chain A's direct dependency set is `{B}`, but its transitive dependency set is `{B, C, D, E}`. A block on chain D that depends on an unsafe initiating message from chain E remains unsafe until that chain E block is on L1 — and so does every chain B and chain A block that depends on the chain D block.

  Verifying transitively is what lets a chain accept low-latency messages without inheriting unbounded trust from chains it has never heard of: chain A only needs to accept the trust assumptions of chains in its own transitive dependency set.
</Expandable>

## Interop clusters

Each chain configures a *dependency set* — the set of chains it is willing to accept initiating messages from. Together, a group of chains whose dependency sets reach each other forms an interop cluster.

```mermaid theme={null}

flowchart LR
    A[Chain A] <--> B[Chain B]
    A[Chain A] <--> C[Chain C]
    A[Chain A] <--> D[Chain D]
    A[Chain A] <--> E[Chain E]
    B <--> C
    D <--> E

```

Dependency sets do not have to be symmetric or fully connected. In the example above, chain B's dependency set is `{A, C}`, so a message from chain E to chain B has to be relayed through chain A: send from E to A, then from A to B.

### Superchain interop cluster

The OP Stack builds on top of the underlying interop protocol with a single, fully-connected mesh: every chain in the Superchain interop cluster has every other chain in its dependency set, so any chain can send a message directly to any other.

```mermaid theme={null}

flowchart LR
    A[Chain A] <--> B[Chain B] <--> C[Chain C] <--> D[Chain D] <--> E[Chain E] <--> A
    A <--> C <--> E <--> B <--> D <--> A
```

Every chain in the Superchain interop cluster shares the same security model to mitigate the weakest-link risk of cross-chain messaging. As outlined in the [Standard Rollup Charter](/op-stack/protocol/blockspace-charter), these chains share the same L1 `ProxyAdmin` Owner, and any change to the cluster goes through the standard Protocol Upgrade vote — the established governance process for OP Stack modifications.

Operationally, the fully-connected cluster is the workload [op-supernode](/op-stack/interop/supernode) is built to run: one supernode (or a small high-availability pool) derives every chain in the cluster and verifies cross-chain messages, while the rest of an operator's fleet follows along in a lighter mode.

The Superchain interop cluster is being rolled out iteratively. To see which chains are eligible to join, visit the [Superchain Index](https://www.superchain.eco/superchain-index) and look for chains with a `Standard` charter.

## Next steps

* Learn [how messages get from one chain to another chain](/app-developers/guides/interoperability/message-passing).
* Learn how [interop handles reorgs and avoids double-spends](/op-stack/interop/reorg).
* Read about [op-supernode](/op-stack/interop/supernode), the component that derives every chain in the dependency set together and enforces cross-chain safety.
* Read the [cross-chain security measures](/op-stack/security/interop-security) for safe interoperability.


# Interoperability
Source: https://docs.optimism.io/op-stack/interop/index

One place to learn OP Stack interoperability, from the gentle introduction through message passing, safety, hands-on tutorials, and the normative spec.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

OP Stack interoperability is a set of protocols that lets OP Stack chains
read each other's state, so a network of chains can feel like a single
blockchain: ETH and ERC-20 tokens move between chains by native minting and
burning, contracts can compose with events from other chains at low
latency, and applications that need it can scale horizontally across
multiple chains.

Interop is in active development and is being rolled out iteratively, so
read these materials as a picture of where the stack is going and what you
can already build against, not as a finished production system. Start with
the explainer, then work through the mechanism pages in order: they build
from the message-passing model up to reorg safety and the runtime that
enforces it. The tutorials let you try everything on local or devnet
chains, and the spec is the normative definition throughout.

## Start here

* [OP Stack interoperability explainer](/op-stack/interop/explainer): read
  this first for what interop enables (native asset transfers, cross-chain
  composability, horizontal scalability) and the architecture end to end,
  covering initiating and executing messages, access-list validation,
  block safety levels, and dependency sets and clusters.

## Go deeper

* [Interop message passing overview](/app-developers/guides/interoperability/message-passing):
  the messaging lifecycle at contract level, from the low-level
  `CrossL2Inbox` to the `L2ToL2CrossDomainMessenger` most apps use.
* [Reading logs with OP Stack interop](/app-developers/guides/interoperability/reading-logs):
  the pull model, where a contract validates a log from another chain
  directly instead of receiving a message.
* [Message expiration](/app-developers/guides/interoperability/message-expiration):
  why an unrelayed message eventually expires and how to reemit one that
  did.
* [Superchain ETH Bridge](/op-stack/interop/superchain-eth-bridge): how
  native ETH moves between chains through `SuperchainETHBridge` and the
  `ETHLiquidity` contract.
* [Interop reorg awareness](/op-stack/interop/reorg): how interop delivers
  low-latency messages without opening the door to cross-chain
  double-spends.
* [OP Supernode](/op-stack/interop/supernode): the runtime that hosts
  every chain in a dependency set in one process and performs the
  cross-chain verification work.

## Get hands-on

* [Build interoperable apps on OP Stack devnet](/app-developers/guides/interoperability/get-started):
  pick a development environment (local Supersim or the interop devnet)
  and start deploying.
* [Supersim](/app-developers/tools-sdks/supersim): the local development
  environment that simulates a multi-chain OP Stack setup for building
  and testing cross-chain applications.
* [Interop message passing tutorial](/app-developers/tutorials/interoperability/message-passing):
  build a cross-chain message passing system with the
  `L2ToL2CrossDomainMessenger` contract.
* [Relay transactions manually](/app-developers/tutorials/interoperability/manual-relay):
  construct and send an executing message yourself when no autorelayer
  does it for you.

## The normative spec

The definitive definition of interop behavior lives in the OP Stack
specifications:

* [Interop](https://specs.optimism.io/interop/overview.html?utm_source=op-docs\&utm_medium=docs):
  the root of the interop specs and the map of everything below it.
* [Messaging](https://specs.optimism.io/interop/messaging.html?utm_source=op-docs\&utm_medium=docs):
  the normative definitions of initiating and executing messages and
  their safety rules.
* [Predeploys](https://specs.optimism.io/interop/predeploys.html?utm_source=op-docs\&utm_medium=docs):
  the `CrossL2Inbox`, `L2ToL2CrossDomainMessenger`, and the other interop
  predeploy contracts.
* [SuperchainETHBridge](https://specs.optimism.io/interop/superchain-eth-bridge.html?utm_source=op-docs\&utm_medium=docs):
  the specification of native ETH bridging between interop chains.

## Audits and security

* [Crosschain security measures](/op-stack/security/interop-security):
  the trust model, what happens under sequencer equivocation, and the
  latency versus security tradeoff each chain configures.
* [Audit reports](/op-stack/security/audit-reports): the standing index of
  OP Stack security reviews, which routes to the full list in the
  monorepo.


# Interop reorg awareness
Source: https://docs.optimism.io/op-stack/interop/reorg

How OP Stack interop enables low-latency interop and avoids the double-spend problem.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

[A chain reorganization, or "reorg",](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge) happens when validators disagree on the most accurate version of the blockchain.
If not handled correctly, reorgs in a cross-chain context could result in a [double-spend problem](https://en.wikipedia.org/wiki/Double-spending).
The most frequent solution to mitigate the double-spend problem is to wait for Ethereum finality; however, that solution results in high latency cross-chain communication and a poor user experience.

<Expandable title="What is double-spending?">
  ```mermaid theme={null}

  flowchart LR
      classDef ok fill:#8F8

      subgraph src["Source chain"]
          direction TB
          debit["Tokens debited"]
          emit["Initiating message emitted"]
          debit --> emit
      end

      subgraph dst["Destination chain"]
          direction TB
          receive["Initiating message verified"]
          credit["Tokens credited"]
          receive --> credit
      end

      emit ==>|cross-chain message|receive

      class debit,emit,receive,credit ok
  ```

  In a normal asset transfer tokens are debited on the source chain first, then a message is sent to the destination chain.
  When that message is received, the tokens are credited on the destination chain, where the user can now use those tokens.

  ```mermaid theme={null}

  flowchart LR
      classDef bad fill:#F89

      subgraph src["Source chain (after reorg)"]
          direction TB
          gone["Initiating transaction reorged out<br/>tokens never debited"]
      end

      subgraph dst["Destination chain"]
          direction TB
          receive["Stale initiating message accepted"]
          credit["Tokens credited"]
          receive --> credit
      end

      gone -.->|message no longer canonical|receive

      class gone,receive,credit bad
  ```

  A double-spend problem occurs when the destination chain receives a valid initiating message, but due to issues on the source chain, such as a reorg, that initiating transaction is no longer valid.
  When that happens, the tokens are still on the source chain, but they are also on the destination chain.

  The mechanism varies by asset.
  ETH is locked and unlocked in an on-chain liquidity contract; SuperchainERC20 tokens are burned and minted.
  The double-spend risk is the same either way.
</Expandable>

Most solutions to mitigate the double-spend problem rely on [L1 finality](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality). However, that solution results in high latency and poor user experience.

To mitigate the double-spend problem while delivering a low-latency cross-chain experience, OP Stack interop uses [block safety levels](/op-stack/interop/explainer#block-safety-levels).
This means users can transfer assets across OP Stack chains with 1-block latency, and should a reorg happen, either both the source and destination transactions remain or both of them revert.
In every case, there is no window of opportunity to double spend.

## Block safety levels

```mermaid theme={null}

graph LR
    classDef safe fill:#8F8
    classDef unsafe fill:#F89

    subgraph A ["Chain A"]
      A100["A<sub>100</sub>"]-->A101["A<sub>101</sub>"]-->A102["A<sub>102</sub>"]-->A103["A<sub>103</sub>"]
    end
    subgraph B ["Chain B"]
      B300["B<sub>300</sub>"]-->B301["B<sub>301</sub>"]-->B302["B<sub>302</sub>"]-->B303["B<sub>303</sub>"]
    end
    A101-.->B302
    B300-.->A100
    class A100,B300,B301 safe
    class A101,A102,A103,B302,B303 unsafe
```

In the diagram above, solid arrows show derivation of a block from the previous block in the chain. Dotted arrows go from a block with an initiating message (source) to a block with the matching executing message (destination). Throughout this page, blocks are colored by safety level: finalized (grey), safe (green), or unsafe (red).

Blockchain A has only published block A<sub>100</sub> to L1. Block A<sub>101</sub> is still unsafe, and so is every block that depends on it — directly (A<sub>102</sub> and B<sub>302</sub>) or indirectly (A<sub>103</sub> and B<sub>303</sub>). Even if blocks B<sub>302</sub> and B<sub>303</sub> have themselves been written to L1, they cannot become safe until A<sub>101</sub> does, because a block is only treated as safe once every initiating message it references is also at least safe. When A<sub>101</sub> eventually lands on L1, the chain of dependent blocks can promote in turn.

The message between A<sub>101</sub> and B<sub>302</sub> can be an asset moving across the bridge.
In that case, the initiating message (A<sub>101</sub>) burns `n` tokens on the source chain (A), and the executing message (B<sub>302</sub>) mints `n` tokens on the destination chain (B).

### How the dependency check is enforced

The dependency rule above — a block is only safe once every initiating message it references is also safe — is enforced by [op-supernode](/op-stack/interop/supernode), the component that hosts the consensus layer of every chain in a dependency set together. For each L2 timestamp, op-supernode's interop activity decides between *wait*, *advance*, *invalidate*, and *rewind*. The decision is persisted to a write-ahead log before being applied, so the supernode picks up after a restart in the same state it was in before.

Each chain's CL stays the single source of truth for safety on its own chain. The supernode influences advancement through interfaces the chain itself controls, never by reaching into the CL or the execution layer. The rest of this page describes the situations that drive each decision.

### L1 reorg

L1 reorgs typically happen at the unsafe head — only the most recent L1 blocks, before they have enough confirmations to be considered safe. Each chain's CL already filters L1 derivation through L1 safe and finalized labels, so almost all L1 reorgs never reach the L2 derivation pipeline at all.

When an L1 reorg does affect L2, one of two things happens:

* **The replacement L1 block carries the same batch data as the original.** Derivation is deterministic, so the L2 chain it produces is identical, and the reorg is a no-op from the L2 perspective.
* **The replacement L1 block does not carry that batch data.** The sequencer notices and reposts the affected batch in a later L1 block. As long as the batch lands again before the [sequencer window](https://specs.optimism.io/glossary.html#sequencing-window) elapses (3600 L1 blocks ≈ 12 hours on standard chains like OP Mainnet and Unichain), derivation reproduces the same L2 chain. If the window does elapse without the batch reappearing, the affected L2 blocks are replaced with deposit-only blocks (see [Invalid block](#invalid-block) below).

If a leaked L1 reorg leaves op-supernode with inconsistent per-chain views of L1, the interop activity issues a *rewind*: verified state is rolled back and re-derived once L1 settles.

L1 reorgs do not by themselves break interop guarantees. Either the data comes back and L2 stays identical, or the chain falls back to deposit-only blocks for that span — the same behavior as if the sequencer had simply gone offline.

### Equivocation

Sequencers inform the rest of the OP Stack chains about a new block in two ways:

* The gossip protocol, which is typically used as soon as the block is created.
  The problem is that the gossip protocol does not create a commitment.
* Posting to L1, which typically happens a few minutes after the block is created.
  The reason is cost; it is much cheaper if compression and L1 posting are done in large batches rather than for each individual block.

Equivocation happens when a sequencer publishes a block over the gossip protocol that differs from the one that eventually gets written to L1. The L1 version wins, and [op-supernode](#how-the-dependency-check-is-enforced) issues an *invalidate* for every unsafe dependent block (local or cross-chain) that built on the gossiped version.

```mermaid theme={null}

graph LR
    classDef finalized fill:#CCC
    classDef safe fill:#8F8
    classDef unsafe fill:#F89

    subgraph A ["Chain A"]
      A100["A<sub>100</sub>"]-->A101["A<sub>101</sub>"]-->A102["A<sub>102</sub>"]-->A103["A<sub>103</sub>"]
      A100-->A101b["A'<sub>101</sub>"]-->A102b["A'<sub>102</sub>"]-->A103b["A'<sub>103</sub>"]
    end
    subgraph B ["Chain B"]
      B300["B<sub>300</sub>"]-->B301["B<sub>301</sub>"]-->B302["B<sub>302</sub>"]-->B303["B<sub>303</sub>"]
      B300-->B301b["B'<sub>301</sub>"]-->B302b["B'<sub>302</sub>"]-->B303b["B'<sub>303</sub>"]
    end
    subgraph C ["Chain C"]
      C200["C<sub>200</sub>"]-->C201["C<sub>201</sub>"]-->C202["C<sub>202</sub>"]-->C203["C<sub>203</sub>"]
      C202-->C203b["C'<sub>203</sub>"]
    end
    A101-.->B302
    A101-.->B301
    A101b-.->B302b
    A101b-.->B301b    
    B300-.->A100
    B302-.->C203
    B302b-.->C203b    
    C200-.->B301    
    class C200 finalized
    class A100,B300,C201,C202 safe
    class A101b,A102b,A103b,B301b,B302b,B303b,C203b safe
    class A101,A102,A103,B301,B302,B303,C203 unsafe
```

A block in another chain can only depend on a specific block here if it referenced one of that block's logs in an executing message — and a block only earns the safe label once every initiating message it depends on has also reached at least safe. So the equivocation between A<sub>101</sub> and A'<sub>101</sub> only invalidates *unsafe* blocks: A<sub>102</sub> and A<sub>103</sub> on chain A (extending the bad history), B<sub>301</sub> and B<sub>302</sub> on chain B (which referenced A<sub>101</sub> directly) along with B<sub>303</sub> (which follows them on chain B), and C<sub>203</sub> on chain C (which referenced B<sub>302</sub>). All those unsafe blocks are reorged out and replaced by the corresponding `'`-marked blocks, which derive from A'<sub>101</sub>. Anything previously labeled safe or finalized is untouched.

### Invalid block

A block can also be canonically invalidated outright. If verifiers determine that an L2 block cannot be reproduced from L1 — for example because the batch claims an initiating message that does not exist on the source chain — the canonical chain replaces it with a *deposit-only block*: a block that contains only the deposit transactions forced through L1, with all sequencer transactions stripped out. For interop-specific failures like that example, [op-supernode](#how-the-dependency-check-is-enforced) is the verifier that makes the call.

<Expandable title="What makes a block invalid?">
  There are several potential reasons:

  * The block posted to L1 includes incorrect information — for example, a batch claims an initiating message that the source chain never actually emitted, so any executing message that references it cannot be reproduced.
  * The block was never posted at all. If the [sequencer window](https://specs.optimism.io/glossary.html#sequencing-window) elapses (3600 L1 blocks ≈ 12 hours on standard chains) without a batch covering an L1 epoch, verifiers fall back to a deposit-only block for that epoch.
</Expandable>

Functionally this is equivalent to equivocation, and the dependency rules above handle it the same way: only unsafe blocks (and any chain of blocks depending on them transitively) are reshaped, and any block that had already reached the safe label is untouched.

## Next steps

* Read the [interop explainer](/op-stack/interop/explainer) for the rest of the architecture.
* Read about [op-supernode](/op-stack/interop/supernode), the component that derives every chain in the dependency set together and enforces the safety levels described above.
* Read the [cross-chain security measures](/op-stack/security/interop-security) for safe interoperability.
* View more [interop guides and tutorials](/app-developers/guides/interoperability/get-started).


# Superchain ETH Bridge
Source: https://docs.optimism.io/op-stack/interop/superchain-eth-bridge

Learn basic details about Interoperable ETH.

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

<Info>
  This is an explanation of how interop ETH works.
  You can find a step by step tutorial [here](/app-developers/tutorials/bridging/bridge-crosschain-eth).
</Info>

InteroperableETH enables seamless ETH transfers across Superchain blockchains. It is implemented using three key contracts:

* [`SuperchainETHBridge`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainETHBridge.sol): A bridge contract that facilitates ETH transfers between Superchain blockchains.
* [`ETHLiquidity`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/ETHLiquidity.sol): A liquidity provider for ETH transfers.
  `SuperchainETHBridge` uses this contract as a liquidity repository to ensure ETH availability on the destination chain.
* [`L2ToL2CrossDomainMessenger`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/L2ToL2CrossDomainMessenger.sol): A messaging contract that [facilitates cross-chain communication](/app-developers/guides/interoperability/message-passing).

Superchain ETH Bridge deposits ETH into the `ETHLiquidity` contract on the source chain and withdraws an equivalent amount on the destination chain.
This mechanism improves capital efficiency and eliminates liquidity fragmentation and poor user experiences caused by asset wrapping or reliance on liquidity pools.

## Features and benefits

* Enables seamless ETH transfers across OP Stack chains
* Maintains fungibility of ETH across OP Stack chains
* Provides liquidity for cross-chain transactions
* Improves user experience by abstracting complex bridging processes

## How it works

```mermaid theme={null}

%%{
  init: {
    "sequence": {
      "wrap": true
    }
  }
}%%

sequenceDiagram
  box rgba(0,0,0,0.1) Source Chain
    participant src-liquidity as ETHLiquidity
    participant src-eth-bridge as SuperchainETHBridge
  end
  actor user as User
  participant any-offchain as User, Relayer, etc.  
  box rgba(0,0,0,0.1) Destination Chain
    participant dst-l2Xl2 as L2ToL2CrossDomainMessenger
    participant dst-eth-bridge as SuperchainETHBridge
    participant dst-liquidity as ETHLiquidity       
    participant dst-final as ETH Destination
  end
  rect rgba(0,0,0,0.1)
    note over src-eth-bridge, dst-l2Xl2: Initiating Message
    user->>src-eth-bridge: 1. sendETH(to, chainId) with n ETH
    src-eth-bridge->>src-liquidity: 2. Deposit n ETH
    src-eth-bridge->>dst-l2Xl2: 3. Send relayETH to SuperchainETHBridge on chainId
  end
  rect rgba(0,0,0,0.1)
    note over any-offchain,dst-eth-bridge: Executing message
    any-offchain->>dst-l2Xl2: 4. Relay the message
    dst-l2Xl2->>dst-eth-bridge: 5. relayETH(from, to, amount)
    dst-eth-bridge->>dst-liquidity: 6. Withdraw amount ETH
    dst-eth-bridge->>dst-final: 7. Here are amount ETH
  end
```

#### Initiating message

1. The user (or a contract operating on a user's behalf) calls `SuperchainETHBridge.sendETH` with a destination address and a chainId.
   ETH, in the amount to transfer must be attached to this call.

2. `SuperchainETHBridge` transfers the specified ETH amount to `ETHLiquidity`, removing it from circulation on the source chain.

3. `SuperchainETHBridge` on the source chain sends a [`relayETH`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/SuperchainETHBridge.sol) message to `SuperchainETHBridge` on the destination chain using the [`L2ToL2CrossDomainMessenger`](/app-developers/guides/interoperability/message-passing).

#### Executing message

4. An off-chain entity submits a transaction to execute the message.
   Any address can submit this transaction, but it must have ETH on the destination chain.
   Typically, this would be the chain's autorelayer.

5. `L2ToL2CrossDomainMessenger` on the destination chain calls `SuperchainETHBridge` with the following details:

   * Source of the ETH
   * Destination address
   * Amount of ETH

   `SuperchainETHBridge` performs several sanity checks:

   * The `relayETH` call must originate from `L2ToL2CrossDomainMessenger`.
   * The interop message must have been sent by `SuperchainETHBridge`

6. `SuperchainETHBridge` withdraws the specified amount of ETH from `ETHLiquidity`.
   Only `SuperchainETHBridge` can withdraw from `ETHLiquidity`, ensuring that the ETH is correctly reintroduced into circulation on the destination chain.

7. `SuperchainETHBridge` uses [`SafeSend`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/SafeSend.sol) to send ETH.
   This ensures that even if the destination is a smart contract, its custom logic is not executed.
   This behavior differs from [standard ETH transfers](https://docs.base.org/learn/address-and-payable/address-and-payable#receiving-ether-with-payable-addresses), where smart contracts can trigger custom logic upon receiving ETH.

## L1 Treasury

Every ETH in circulation on OP Stack chains—excluding ETH held by `ETHLiquidity`—must be backed by ETH on L1.

This is enforced by a lockbox contract on L1, which holds all ETH bridged to [OP Stack interop cluster chains](/interop/explainer#superchain-interop-cluster) that has not yet been withdrawn.
New ETH can only be minted on L2 when it is locked on L1, and it is burned on L2 before it can be released from the lockbox.

Here is an example of how this works.

| Step | User on L1 | Lockbox | User on chain A | ETHLiquidity on chain A | User on chain B | ETHLiquidity on chain B |
| ---: | ---------: | ------: | --------------: | ----------------------: | --------------: | ----------------------: |
|    1 |          7 |     200 |               0 |                  100000 |               0 |                  100000 |
|    2 |          4 |     203 |               3 |                  100000 |               0 |                  100000 |
|    3 |          4 |     203 |               2 |                  100001 |               0 |                  100000 |
|    4 |          4 |     203 |               2 |                  100001 |               1 |                   99999 |
|    5 |          4 |     203 |               2 |                  100001 |               0 |                   99999 |
|    6 |          5 |     202 |               2 |                  100001 |               0 |                   99999 |

1. The initial state. The user has 7 ETH on L1, and nothing on chains A and B.

2. The user bridges 3 ETH to chain A.
   The user sends 3 ETH on L1 to the bridge, which is locked in the lockbox.
   The bridge on chain A then mints 3 ETH for the user.

3. The user sent the initiating message to `SuperchainETHBridge` on chain A, along with 1 ETH to bridge to chain B.
   This 1 ETH is sent to `ETHLiquidity` on chain A.

4. Somebody (the user, a relayer action on behalf of the user, etc.) sent the corresponding executing message to chain B.
   `SuperchainETHBridge` transfers 1 ETH from `ETHLiquidity` on chain B to the user.

5. The user decides to withdraw 1 ETH from chain B back into L1.
   Normally, a user would do this through a third-party bridge, which is faster and usually cheaper, but for illustration purposes this user uses the standard OP bridge.
   The user starts with an initiating message on chain B, which burns 1 ETH and sends a message to L1.

6. After the week long [challenge period](/connect/resources/glossary#challenge-period), the user finalizes the withdrawal on L1.
   The lock box releases 1 ETH, which is then sent to the user.

## Next steps

* Practice [transferring ETH across chains using OP Stack interop](/app-developers/tutorials/bridging/bridge-crosschain-eth).


# OP Supernode
Source: https://docs.optimism.io/op-stack/interop/supernode

Learn how op-supernode runs every chain in an interop dependency set inside one process.

<Info>
  OP Stack interop is in active development.
  op-supernode is the runtime that operators of interop chains will run, and the architecture and interfaces described here may continue to evolve as the rollout progresses.
</Info>

# OP Supernode

*op-supernode* is a component that runs every chain in an interop dependency set together as virtual nodes inside one binary.
Where a pre-interop deployment runs one op-node per chain, op-supernode hosts every chain side by side, shares the L1 and beacon-chain plumbing across them, and adds the cross-chain message verification work that interop needs.

## Why op-supernode exists

OP Stack interop changes what a single node has to do.
Before interop, a node only had to derive its own chain.
With interop, a node has to derive *every chain in its dependency set*, because any of those chains can emit an initiating message that the local chain depends on.
The local chain cannot advance past a block whose dependencies it cannot prove, so the derivation of every other chain in the set is on the critical path.

Without consolidation, every operator runs a full op-node and execution client for every chain in the dependency set.
That duplicates the L1 client, the beacon-chain client, the derivation pipeline, the storage layout, and the operational glue around each one.
For a fully-connected dependency set — the configuration the [Superchain interop cluster](/op-stack/interop/explainer#superchain-interop-cluster) targets — the duplication scales with the size of the cluster.

op-supernode collapses that duplication.
It runs each chain as an in-memory *virtual node* inside one process, with a single L1 client and a single beacon client serving all of them, and adds the cross-chain message verification work above the per-chain layer.

## How op-supernode works

The supernode is composed of *chain containers* and *activities*.
Each chain container hosts one virtual node for one chain.
Activities are modular components that operate above the chain layer, with access to every chain.

<img alt="An op-supernode hosts two chain containers (Chain A and Chain B), each containing a Virtual Node and Engine Controller. The Engine Controllers drive external Execution Clients. A shared Interop Verification Activity and L1 Client sit alongside the chain containers." />

### Chain containers

A *chain container* is the supernode's wrapper around one chain.
Inside a chain container is a *virtual node*: a consensus-layer (CL) implementation hosted in-process rather than as a separate operating-system process.
Today the only virtual node implementation is op-node itself, hosted as a library; the chain container manages its lifecycle (start, stop, pause, resume) and exposes a stable interface to the rest of the supernode.

Chain containers also drive the execution engine for the chain through an engine controller.
They expose the operations the supernode needs to verify cross-chain messages — deriving the local-safe block at a timestamp, fetching receipts, answering output-root queries — without reaching into the internals of any one chain.

### Shared resources

Running every chain inside one process makes shared resources possible.

* A single **L1 RPC client** and a single **L1 beacon client** serve every chain. Cache hits on L1 blocks and blob lookups carry across chains.
* The **JSON-RPC surface** is namespaced per chain. `11155420/` reaches OP Sepolia's RPC; `1301/` reaches Unichain Sepolia's. Tools that expect an op-node-shaped endpoint reach a chain by addressing it through that prefix.
* **Metrics** are namespaced per chain via the same scheme.
* **Data directories** are namespaced so SafeDB and P2P state for one chain cannot collide with another's.

Some flags are intentionally owned at the supernode level rather than per chain.
`--l1` and `--l1.beacon` configure the shared L1 plumbing, and any per-chain override of them is silently replaced with the top-level value.

### Activities

An *activity* is a modular component that operates above the chain layer rather than inside any one chain.
Each activity can register an RPC namespace on the supernode root, expose Prometheus metrics, and run a goroutine for as long as the supernode is up.

The supernode ships with a small set of activities:

* **Heartbeat** — emits a liveness signal and exposes `heartbeat_check` over JSON-RPC.
* **SuperRoot** — produces a *super root*: a commitment over verified L2 blocks across the dependency set at a given timestamp. Exposed as `superroot_atTimestamp`. The fault proof system needs this commitment to produce an interop-aware proof.
* **Supernode** — exposes `supernode_syncStatus`, an aggregate per-chain sync status across the dependency set.
* **Interop** — does the actual cross-chain message verification (see the next section).

## Cross-chain message safety

The interop activity is the part of op-supernode that decides when a chain's blocks have satisfied their cross-chain dependencies and can be promoted past unsafe.
It runs above the chain containers and reaches into them through a narrow interface.

For every block produced on every chain, the interop activity answers one question: have all the initiating messages this block executes been reproduced from L1, and at the same safety level the destination block is trying to reach?
The activity decides per round between *wait*, *advance*, *invalidate*, and *rewind*.
The decision is recorded in a write-ahead log so the supernode can pick up after a restart in the same state it was in before.

When the answer is *advance*, the supernode signals the chain's CL to promote the block.
The signal flows through an *authority* interface that the chain container holds and the virtual node defers to: the supernode advances safety on a chain only via the chain's own CL.
The CL stays the single source of truth for safety on its chain, and the execution layer (EL) never has to learn about interop.

When the answer is *invalidate* or *rewind*, the supernode tells the chain to back out the affected blocks.
A block on chain B that referenced a chain-A log can be invalidated because the chain-A log never made it to L1, or because the L1 record contradicts what was gossiped over P2P.
See [Interop reorg awareness](/op-stack/interop/reorg) for how that plays out at the chain level.

The user-facing safety levels do not change.
Block safety levels (*unsafe*, *safe*, *finalized*) are still defined as they are without interop, and the EL's view of those labels matches.
The supernode's role is to make sure the labels mean what they say once cross-chain dependencies are part of the picture.

## op-supernode and Light CL

op-supernode pairs with the *Light CL* mode of op-node and kona-node.
A Light CL turns off local derivation and mirrors safe and finalized state from a trusted external source over the `optimism_syncStatus` RPC.
It still advances the unsafe chain over P2P; only the safe and finalized views are delegated.

Together, supernode and Light CL form a topology:

* One trusted op-supernode (or a small high-availability pool of them) runs derivation for every chain in the dependency set, plus the interop activity that promotes blocks to safe.
* The rest of the operator's fleet runs op-node or kona-node in Light CL mode, points at the supernode's `optimism_syncStatus`, and inherits its safe and finalized view.
* Node operators run the same setup, minus the sequencer Light CLs (only the chain operator produces blocks).

This split is what makes interop tractable for operators who already run dozens or hundreds of nodes per chain.
The expensive multi-chain derivation work happens once, on the supernode; the rest of the fleet stays cheap.

```mermaid theme={null}
graph LR
  classDef supernode fill:#FFE
  classDef transparent fill:none, stroke:none

  SnA[Supernode-A]
  SnB[Supernode-B]
  SnC[Supernode-C]

  Px0["Proxy CL<br/>Chain-0"]
  Px1["Proxy CL<br/>Chain-1"]

  subgraph c0["Chain-0 Light CL fleet"]
    direction TB
    C0Seq["Sequencer<br/>0..N"]
    C0Rep["Replica<br/>0..N"]
  end

  subgraph c1["Chain-1 Light CL fleet"]
    direction TB
    C1Seq["Sequencer<br/>0..N"]
    C1Rep["Replica<br/>0..N"]
  end

  SnA --> Px0
  SnA --> Px1
  SnB --> Px0
  SnB --> Px1
  SnC --> Px0
  SnC --> Px1

  Px0 --> C0Seq
  Px0 --> C0Rep
  Px1 --> C1Seq
  Px1 --> C1Rep

  class SnA,SnB,SnC supernode
  class c0,c1 transparent
```

## Where to go next

* Read the [interop prep notice](/notices/interop-prep) for the node-operator action checklist for the OP Sepolia and Unichain Sepolia activation.
* Read the [supernode configuration guide](/node-operators/guides/configuration/supernode) for recommended settings and a starter configuration, and the [op-supernode configuration reference](/node-operators/reference/op-supernode-config) for the full flag catalogue.
* Read the [specialized op-node topology notice](/notices/specialized-node-topology) for the operator-facing pattern of running light op-nodes with `--l2.follow.source`, the fleet-side of the supernode-plus-light-CL topology.
* Read [interop reorg awareness](/op-stack/interop/reorg) for how the safety model handles equivocation and L1 reorgs.
* Read the [cross-chain security measures](/op-stack/security/interop-security) for how an operator can configure the safety level it requires for inbound messages.
* Read the [interop explainer](/op-stack/interop/explainer) for how cross-chain messaging works at the protocol level.
* For implementation detail, see the [op-supernode source](https://github.com/ethereum-optimism/optimism/tree/develop/op-supernode) in the monorepo.


# Fact sheet
Source: https://docs.optimism.io/op-stack/introduction/fact-sheet

A quick look of the OP Stack's capabilities

While the OP Stack allows for full customization, standard OP Stack chains adhere to a [standard set of technical and governance parameters](/op-stack/protocol/blockspace-charter), facilitating OP Stack interoperability, network security, and ease of upgrading your chain.

# Technical stack

| Feature                           | Standard OP Stack             | OP Stack                    |
| --------------------------------- | ----------------------------- | --------------------------- |
| **Parent chain**                  | Ethereum                      | Any L1, any L2              |
| **Throughput<sup>1</sup>**        | 32.5Mgas/s                    | 50Mgas/s                    |
| **Gas limit<sup>2</sup>**         | 200M                          | 200M                        |
| **Blocktimes<sup>3</sup>**        | 200ms                         | 200ms                       |
| **Data availability support**     | Ethereum                      | Ethereum, Celestia, EigenDA |
| **Gas token support<sup>4</sup>** | ETH                           | ETH, Custom Gas Token       |
| **Upgrades**                      | Facilitated via OP Governance | Self-managed                |
| **EVM compatibility**             | Equivalent                    | Variable                    |

<sup>1</sup>Data for Standard OP Stack from [Base](https://etherscan.io/address/0x73a79Fab69143498Ed3712e519A88a918e1f4072#readProxyContract#F14). Data for OP Stack from [opBNB](https://docs.bnbchain.org/bnb-opbnb/core-concepts/opbnb-metrics/).

<sup>2</sup>The standard blockspace charter has a max gas limit of [200m](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs\&utm_medium=docs#gas-limit). Both gas limit and gas target can be configured through the system config.

<sup>3</sup>While protocol blocktimes can be lowered to 1 second, subsecond pre-confirmations are delivered by [Subblocks](/op-stack/features/subblocks).

<sup>4</sup>OP Stack chains can use [Custom Gas Token](/op-stack/features/custom-gas-token) to enable any asset as the native fee currency. Standard OP Stack chains use ETH as the gas token, though chain operators can achieve similar UX using an ERC-20 paymaster.


# The OP Stack
Source: https://docs.optimism.io/op-stack/introduction/op-stack

The standard framework for building Ethereum Layer 2 Rollups.

<Info>
  **Learn the OP Stack — stop 1 of 13.**
  This is the start of the track; nothing is assumed beyond general
  familiarity with Ethereum. This page gives you the mental model: what
  the OP Stack is and what it powers. When you're done, continue to
  [Design philosophy & principles](/op-stack/protocol/design-principles).
</Info>

The OP Stack is the standardized, shared, and open-source development stack that powers Optimism and makes it easy to spin up your own production-ready Layer 2 blockchain.
Whether you're building applications or deploying your own chain, the OP Stack provides the foundation you need.

## What is the OP Stack?

The OP Stack is a modular collection of software components that work together to create Layer 2 blockchains. It includes:

* **Execution Layer**: Processes transactions and manages state
* **Consensus Layer**: Handles block production and validation
* **Data Availability**: Ensures transaction data is available
* **Settlement Layer**: Finalizes transactions on Ethereum

## Choose Your Path

<CardGroup>
  <Card title="Build Applications" icon="code" href="/app-developers/quickstarts/starter-kit">
    Start building decentralized applications on existing OP Stack chains
  </Card>

  <Card title="Deploy a Chain" icon="server" href="/operators/chain-operators">
    Launch your own OP Stack chain for your project or organization
  </Card>

  <Card title="Run a Node" icon="computer" href="/operators/node-operators">
    Operate infrastructure by running your own OP Stack node
  </Card>

  <Card title="Contribute to Protocol" icon="github" href="https://github.com/ethereum-optimism/optimism/blob/develop/CONTRIBUTING.md">
    Help build the future of the OP Stack protocol
  </Card>
</CardGroup>

## Development Options

<Tabs>
  <Tab title="Mainnet">
    Build on **OP Mainnet** for production applications with real users and value.

    * Network: Production-ready Layer 2
    * Security: Secured by Ethereum mainnet
    * Ecosystem: Full ecosystem of tools and services
  </Tab>

  <Tab title="Testnet">
    Use **OP Sepolia** for testing and development without real costs.

    * Network: Test environment
    * Faucets: Free test ETH available
    * Perfect for: Development and testing
  </Tab>

  <Tab title="Local Development">
    Run your own local OP Stack chain for rapid development and testing.

    * Tools: Supersim, Anvil, Hardhat
    * Speed: Instant transactions
    * Control: Full control over chain behavior
  </Tab>
</Tabs>

## Quick Start Guide

<Steps>
  <Step title="Set Up Your Environment">
    Install Node.js, your preferred IDE, and essential development tools
  </Step>

  <Step title="Choose Your Framework">
    Select from popular frameworks like Hardhat, Foundry, or Remix
  </Step>

  <Step title="Get Test Funds">
    Use the [Superchain Faucet](https://console.optimism.io/faucet) to get test ETH
  </Step>

  <Step title="Deploy Your First Contract">
    Deploy a simple smart contract to get familiar with the process
  </Step>

  <Step title="Explore Advanced Features">
    Learn about cross-chain messaging, account abstraction, and more
  </Step>
</Steps>

## Key Features

* **EVM Compatibility**: Full compatibility with Ethereum tooling and smart contracts
* **Low Fees**: Significantly lower transaction costs than Ethereum mainnet
* **Fast Confirmations**: Near-instant transaction confirmation, with [full Ethereum finality](/op-stack/transactions/transaction-finality) typically under an hour
* **Ethereum Security**: Inherits security from Ethereum's consensus
* **Modular Design**: Customizable components for specific needs

## Next Steps

<CardGroup>
  <Card title="Architecture Overview" icon="stars" href="/op-stack/protocol/components">
    Understand the technical architecture of the OP Stack
  </Card>

  <Card title="Development Tools" icon="wrench" href="/app-developers/tools">
    Discover tools and services for building on OP Stack
  </Card>

  <Card title="Tutorials" icon="book" href="/app-developers/tutorials/deploy-a-contract">
    Follow step-by-step tutorials for common use cases
  </Card>
</CardGroup>

<Info>
  The OP Stack is continuously evolving. Check the [OP Stack specifications](https://specs.optimism.io) to stay current with new features and improvements, and stay up to date on the OP Stack by reading the [Optimism Blog](https://www.optimism.io/blog).
</Info>

## Ready to build your chain?

<Card title="Launching a chain for your organization?" icon="building" href="https://optimism.io/op-enterprise?utm_source=docs&utm_medium=docs&utm_campaign=op-enterprise">
  Compare running the stack yourself with OP Enterprise's managed and supported options. Either way, these docs are the reference for what your chain runs.
</Card>


# Learn the OP Stack
Source: https://docs.optimism.io/op-stack/learn/index

A linear learning track that takes you from newcomer to comfortable with the OP Stack, through existing pages in a recommended order.

This track is a guided path through the OP Stack documentation for readers
who want to learn the stack from the beginning. It sequences existing pages
into thirteen ordered stops: blocks of concept pages punctuated by three
hands-on projects, so you consolidate each idea by using it before moving on.

**Scope: this track takes you from newcomer to comfortable.** When you
finish, you will have deployed a test chain, followed a transaction from
submission to Ethereum, moved assets in both directions between layers, and
run a node, and you will know where each deeper layer of material lives.
Depth stays out of the track on purpose: exhaustive detail lives in the
reference sections and the [OP Stack specifications](https://specs.optimism.io/),
and the track exits to them rather than repeating them.

## How the track works

* Every stop is an existing page. A framing note at the top of each stop
  tells you where you are in the track and links the next stop, so you can
  walk the whole path without returning here.
* Do the stops in order. Later stops assume the vocabulary and the working
  setup of earlier ones.
* The three projects are the point, not a break: each one turns the
  concepts before it into something running on your machine.

The track's design rationale, ownership, and change history live in the
[track syllabus](/op-stack/contribute/learn-track-syllabus).

## Part 1: Foundations

* **Stop 1.** [The OP Stack](/op-stack/introduction/op-stack): what the
  stack is and what you can build with it.
* **Stop 2.** [Design philosophy & principles](/op-stack/protocol/design-principles):
  the four pillars that explain why the stack is built the way it is.
* **Stop 3.** [Differences from Ethereum](/op-stack/protocol/differences):
  what "EVM equivalent" means in practice and the small set of behaviors
  that differ.
* **Stop 4.** [OP Stack components](/op-stack/protocol/components): the
  conceptual layers of the stack and the software modules that fill them.

## Project 1: Deploy your own chain

* **Stop 5.** [Creating your own L2 rollup testnet](/chain-operators/tutorials/create-l2-rollup):
  deploy a rollup testnet with op-deployer and start each component
  yourself. A multi-part series; work through every part before
  continuing.

## Part 2: Transactions and bridging

* **Stop 6.** [Transaction flow](/op-stack/transactions/transaction-flow):
  how a transaction moves through the components you just ran, from
  submission to finality on Ethereum.
* **Stop 7.** [Transaction fees on OP Mainnet](/op-stack/transactions/fees):
  the fee components of an OP Stack transaction and what determines each
  one.
* **Stop 8.** [Deposit flow](/op-stack/bridging/deposit-flow): how a
  transaction triggered on L1 becomes an L2 transaction.
* **Stop 9.** [Withdrawal flow](/op-stack/bridging/withdrawal-flow): the
  initiate, prove, and finalize steps that move a transaction from L2
  back to L1.

## Project 2: Bridge in both directions

* **Stop 10.** [Submitting transactions from L1](/app-developers/tutorials/bridging/cross-dom-bridge-eth):
  walk a deposit and a withdrawal end to end from code, using Viem.

## Part 3: Security and the Superchain

* **Stop 11.** [Fault proofs explainer](/op-stack/fault-proofs/explainer):
  how anyone can permissionlessly propose and challenge the state
  proposals that withdrawals depend on.
* **Stop 12.** [OP Stack interoperability explainer](/op-stack/interop/explainer):
  how the OP Stack is evolving so a network of chains can feel like a
  single blockchain.

## Capstone: Run a node

* **Stop 13.** [Running a node with Docker](/node-operators/tutorials/node-from-docker):
  run an OP Stack node with the official Docker images and watch it sync
  a live network.

## After the track

The track ends where the deep material begins. Depending on what you want
to do next:

* **Operate or tune a chain:** the [use case guides](/use-cases/index)
  sequence cross-layer operator journeys, and the Chain Operators tab
  holds the full guides and reference.
* **Build applications:** the App Developers tab covers bridging,
  interoperability, and transactions at working depth.
* **Understand the protocol precisely:** the
  [derivation pipeline](/op-stack/protocol/derivation-pipeline) page goes
  one level deeper, and the
  [OP Stack specifications](https://specs.optimism.io/) are the normative
  definition of protocol behavior.

## Next steps

* Start the track at [stop 1: The OP Stack](/op-stack/introduction/op-stack).
* Maintainers: the track is governed by the
  [track syllabus](/op-stack/contribute/learn-track-syllabus) and swept on
  the cadence in the [curation review policy](/op-stack/contribute/curation-policy).


# The Blockspace and Standard Rollup Charters
Source: https://docs.optimism.io/op-stack/protocol/blockspace-charter

Learn about Blockspace Charters, the Standard Rollup Charter, and the superchain-registry.

Blockspace Charters provide the essential technical and governance framework for chains on the OP Stack. These frameworks provide a secure and scalable foundation for all stakeholders. By adhering to these charters, chain operators and users can operate confidently within the OP Stack ecosystem. The Standard Rollup Charter is the first of several blockspace charters with different customizations and security guarantees.

These documents establish standards to ensure security, transparency, and long-term sustainability. This guide offers an overview of each charter, explains how chains can achieve compliance to be considered Standard Chains, and how the charters tie into the superchain-registry.

This doc mostly covers the charters, but references the superchain-registry as they are all deeply connected. Read more about the superchain-registry [here](/op-stack/protocol/superchain-registry).

## Summary of charters

The components work in unison to form a cohesive governance and technical framework:

* **Blockspace Charters:** A type of framework that establishes criteria, governing policies, and precommitments for blockspace in the Optimism ecosystem, ensuring security, uptime, and alignment with the [Law of Chains](https://github.com/ethereum-optimism/OPerating-manual/blob/main/Law%20of%20Chains.md).
* **Standard Rollup Charter:** The Standard Rollup Charter is the first blockspace charter, defining the technical and governance requirements for our highest-security blockspace. By adhering to the Standard Rollup Charter, chains can achieve "Standard" status, ensuring consistency, high security, and operational reliability.
* **superchain-registry:** The superchain-registry is an index of chains which serves as the source of truth for OP Stack chain classification and configuration. The registry checks for compliance with the Standard Rollup Charter. Chains with `superchain_level = 2` meet all the criteria to be classified as a Standard Rollup.

Together, these components ensure a robust, scalable, and transparent ecosystem. Blockspace Charters provide the vision and principles, the Standard Rollup Charter translates these into concrete requirements, and the superchain-registry certifies compliance.

## Blockspace Charters

Blockspace Charters outline the foundational framework for governing blockspace within the Optimism ecosystem.

They are structured around three main components, detailed below:

### Criteria

The technical parameters defining which chains are subject to the charter include:

* **Version:** The OP Stack version powering the chain, validated via commit-hash or release tag.
* **Configuration:** Parameter bounds for deployment, covering both static variables like Chain ID and dynamic variables such as sequencer roles or upgrade keys.
* **Solvency:** Verification that all state transitions in the chain's history are valid, and free from invalid withdrawals or outputs that could undercollateralize the bridge.

### Governing policies

These establish rules and procedures for stakeholder interactions and blockspace management. For example:

* Expected behaviors for roles like sequencers and upgrade key holders.
* Processes for identifying and resolving violations, such as governance votes for removing non-compliant actors.
* Alignment with the [Law of Chains](https://github.com/ethereum-optimism/OPerating-manual/blob/main/Law%20of%20Chains.md), ensuring user protections like censorship resistance and security.

### Precommitments

Commitments outlining long-term governance stability and anticipated changes. Examples include:

* Future updates to fee models or role separations.
* Guidance for evolving technical parameters like gas limits and fee margins.

By defining these components, blockspace charters ensures secure, scalable, and governed blockspace while fostering trust and alignment within the ecosystem.

### Criteria governance

The criteria for Blockspace Charters are set in two ways; either by a governance vote or by the Optimism Foundation.

* **Governance controlled**: The three `TOML` files referenced in the charter ([standard config params](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-config-params-mainnet.toml), [standard config roles](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-config-roles-mainnet.toml), and [standard versions](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml)) require a governance vote to alter. Changes to the files require a governance vote, but changes to code or tools that consume or validate them don't "so long as they do not violate the semantic interpretation of those TOML files."
* **Foundation discretion**: Changes to validation, outside of the three TOML files referenced above, remain at the Foundation's discretion. This includes changes to, but is not limited to, `BHIC`, other config checks, and RPC availability.

Read more about Blockspace Charters in the [governance post](https://gov.optimism.io/t/season-6-introducing-blockspace-charters-superchain-first-governance/8133).

## The Standard Rollup Charter

The Standard Rollup Charter is the Blockspace Charter that defines the requirements for being a standard chain, our highest-security flagship blockspace. The Standard Rollup Charter ensures that chains adhere to the technical and operational benchmarks necessary to maintain the highest standards of security, compatibility, and compliance on the OP Stack.

Learn more about The Standard Charter in [the governance post](https://github.com/ethereum-optimism/OPerating-manual/blob/feat/standard-rollup-charter/Standard%20Rollup%20Charter.md#standard-rollup-charter).

Here are some specific criteria a chain must meet:

### Onchain criteria

* **Version validation:** Chains must deploy a governance-approved, up-to-date OP Stack release. Contracts must match the [standard bytecode](https://github.com/ethereum-optimism/superchain-registry/blob/main/validation/standard/standard-versions-mainnet.toml).
* **Configuration checks:** Chain parameters, such as block time and gas metering, must comply with governance-approved specifications. Administrative roles must align with Security Council requirements.

Read more about onchain checks in the [repo](https://github.com/ethereum-optimism/OPerating-manual/blob/feat/standard-rollup-charter/Standard%20Rollup%20Charter.md#onchain-criteria).

### Off-chain criteria

The Optimism Foundation performs off-chain checks to verify compliance. These include:

* Ensuring unique Chain IDs.
* Monitoring security configurations.
* Verifying governance authenticity.

Such measures remain under the Foundation's oversight until governance transitions to fully autonomous control.

Read more about Off-Chain checks in the [repo](https://github.com/ethereum-optimism/OPerating-manual/blob/feat/standard-rollup-charter/Standard%20Rollup%20Charter.md#offchain-criteria)

### History integrity

The history integrity check identifies discrepancies in chain history, including invalid state transitions. These checks are only required for chains that have not been managed by the Optimism Security Council from launch.

### Understanding chain compliance

Chains must meet strict requirements to qualify as "Standard." Below are answers to common questions:

* **Can I modify system smart contracts and remain Standard?** No, modifications invalidate compliance.
* **Is an alt-DA mode chain Standard?** No, Standard Rollups must adhere to the default data availability model.
* **Will beta features qualify as Standard?** No. Beta features have not yet been approved by Optimism Governance. When features graduate from Beta to GA, they may be included in the Standard Rollup Charter.

## The superchain-registry

The superchain-registry serves as the source of truth for OP Stack chain classification and what modifications chains have made. The superchain-registry has two main tasks:

* **Validates version and configuration:** The registry validates that chains align with governance-approved standards in the form of the Standard Rollup Charter.
* **Indicates adherence to the Standard Rollup Charter:** Once the registry validates that a chain meets the standard criteria, it promotes it to "Standard" by setting its `superchain_level` value to `2`.

By integrating with the Standard Rollup Charter, the registry offers an automated and transparent validation system. This ensures chains can independently demonstrate compliance. For additional details, refer to the [superchain-registry documentation](/op-stack/protocol/superchain-registry).


# OP Stack components
Source: https://docs.optimism.io/op-stack/protocol/components

Learn about OP Stack components including the different layers and modules available for development.

<Info>
  **Learn the OP Stack — stop 4 of 13.**
  You know how OP Stack chains relate to Ethereum. This page names the
  conceptual layers of the stack and the software modules that fill them:
  the components you deploy in the next stop. When you're done, continue
  to [Creating your own L2 rollup testnet](/chain-operators/tutorials/create-l2-rollup).
</Info>

**The OP Stack is a common development stack for building L2 blockchain ecosystems, built by the Optimism Collective to power Optimism.**

The OP Stack is best thought of as a collection of software components maintained by the Optimism Collective that either help to define new layers of the stack or fit in as modules within the stack.

Because the OP Stack is a work in progress, the different layers and modules are still evolving.
This page sketches out the different conceptual layers of the stack as they exist today and introduces some of the modules that fit into those layers.
This doesn't include all of the modules or layers that may exist in the future, but it gives a good overview of the major OP Stack components.
Layers are generally more tightly defined towards the bottom of the stack (like the Data Availability Layer) but become more loosely defined towards the top of the stack (like the Governance Layer).

<Info>
  Please note that not all of the modules described on this page already exist in a production state — these are explicitly marked as either "**in development**" or "**proposed**."
</Info>

## Layers

### Data availability

The Data Availability Layer defines where the raw inputs to an OP Stack based chain are published. An OP Stack chain can use a single Data Availability module to source its input data. Because an OP Stack chain is derived from the Data Availability Layer, the Data Availability module used has a significant impact on the security model of a system. For example, if a certain piece of data can no longer be retrieved from the Data Availability Layer, it may not be possible to sync the chain.

#### Ethereum DA

Ethereum DA is currently the most widely used Data Availability module for the OP Stack. When using the Ethereum DA module, source data can be derived from any piece of information accessible on the Ethereum blockchain. This includes Ethereum calldata, events, and 4844 data blobs.

* [Specifications](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#batch-submission-wire-format)
* [Source code](https://github.com/ethereum-optimism/optimism/tree/v1.1.4/op-batcher) (as of `v1.1.4`)

### Sequencing

The Sequencing Layer determines how user transactions on an OP Stack chain are collected and published to the Data Availability Layer module(s) in use. In the default Rollup configuration of the OP Stack, Sequencing is typically handled by a single dedicated Sequencer. Rules defined in the Derivation Layer generally restrict the Sequencer's ability to withhold transactions for more than a specific period of time. In the future, Sequencing will be modular such that chains can easily select and change the mechanism that controls their current Sequencer.

#### Single sequencer

The default Sequencer module for the OP Stack is the Single Sequencer module in which a dedicated actor is given the ability to act as the Sequencer. The Single Sequencer module allows a governance mechanism to determine who may act as the Sequencer at any given time.

#### Multiple sequencer

A simple modification to the Single Sequencer module is the Multiple Sequencer module in which the Sequencer at any given time is selected from a pre-defined set of possible actors. Individual OP Stack based chains would be able to determine the exact mechanism that defines the set of possible Sequencers and the mechanism that selects a Sequencer from the set.

### Derivation

The Derivation Layer defines how the raw data in the Data Availability Layer is processed to form the processed inputs that are sent to the Execution Layer via the standard [Ethereum Engine API](https://github.com/ethereum/execution-apis/blob/94164851c1630ff0a9c31d8d7d3d4fb886e196c0/src/engine/README.md). The Derivation Layer may also use the current system state, as defined by the Execution Layer, to inform the parsing of raw input data. The Derivation Layer can be modified to derive Engine API inputs from many different data sources. The Derivation Layer is typically tied closely to the Data Availability Layer because it must understand how to parse any raw input data.

#### Rollup

The Rollup module derives Engine API inputs from Ethereum block data, Sequencer transaction batches, Deposited transaction events, and more.

* [Specifications](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#l2-chain-derivation-pipeline)
* [Source code](https://github.com/ethereum-optimism/optimism/tree/v1.1.4/op-node) (as of `v1.1.4`)

#### Indexer

The Indexer module is a Derivation Layer module that would derive Engine API inputs when transactions are sent to, events are emitted by, or storage is modified in specific smart contracts on a Data Availability Layer module like Ethereum DA.

### Execution

The Execution Layer defines the structure of state within an OP Stack system and defines the state transition function that mutates this state. State transitions are triggered when inputs are received from the Derivation Layer via the Engine API. The Execution Layer abstraction opens up the door to EVM modifications or different underlying VMs entirely.

#### EVM

The EVM is an Execution Layer module that uses the same state representation and state transition function as the Ethereum Virtual Machine. The EVM module in the Ethereum Rollup configuration of the OP Stack is a lightly modified version of the EVM that adds support for L2 transactions initiated on Ethereum and adds an extra L1 Data Fee to each transaction to account for the cost of publishing transactions to Ethereum.

* [Source code](https://github.com/ethereum-optimism/optimism/tree/develop/rust/op-reth)

### Settlement layer

The Settlement Layer is a mechanism on external blockchains that establish a **view** of the state of an OP Stack chain (target) on those external, third-party chains (including other OP Stack chains). For each target chain, there may be one or more Settlement mechanisms on one or more external chains. Settlement Layer mechanisms are **read-only** and allow a third-party chain to make decisions, potentially impacting their own state, based on the state of the target OP Stack chain.

The term "Settlement Layer" has its origins in the fact that Settlement Layer mechanisms are often used to handle withdrawals of ETH and tokens out of a blockchain. This sort of withdrawal system first involves proving the state of the target blockchain to some third-party chain and then processing a withdrawal based on that state. The Settlement Layer, at its core, simply allows a third-party chain to become convinced of the state of the target chain.

Once a transaction is published and finalized on the corresponding Data Availability layer, the transaction is also finalized on the OP Stack chain. Short of breaking the underlying Data Availability layer, it can no longer be modified or removed. It may not be accepted by the Settlement Layer yet because the Settlement Layer needs to be able to verify transaction *results*, but the transaction itself is already immutable.

#### Attestation-based fault proof

An Attestation-based Fault Proof mechanism uses an optimistic protocol to establish a view of an OP Stack chain. In optimistic settlement mechanisms generally, **Proposer** entities can propose what they believe to be the current valid state of the OP Stack chain. If these proposals are not invalidated within a certain period of time (the "challenge period"), then the proposals are assumed by the mechanism to be correct. In the Attestation Proof mechanism in particular, a proposal can be invalidated if some threshold of pre-defined parties provide attestations to a valid state that is different than the state in the proposal. This places a trust assumption on the honesty of at least a threshold number of the pre-defined participants.

* [Specifications](https://specs.optimism.io/protocol/withdrawals.html?utm_source=op-docs\&utm_medium=docs) (called [withdrawal transactions](/app-developers/guides/bridging/messaging))
* [Source code](https://github.com/ethereum-optimism/optimism/tree/v1.1.4/packages/contracts-bedrock/src) (as of `v1.1.4`)

#### Fault Proof Optimistic Settlement

A Fault Proof Optimistic Settlement mechanism is mostly identical to the Attestation-based Fault Proof mechanism used today but it replaces the MultiSig challenger with a permissionless fault proving process. A correctly constructed fault proof should be able to invalidate any incorrect proposals during the allocated challenge period. This places a trust assumption on the correctness of the fault proof construction. At this time, work on the development of a Fault Proof mechanism is well underway.

#### Validity Proof Settlement

A Validity Proof Settlement mechanism uses a mathematical proof to attest to the correctness of a proposed view. When a proposed state is accompanied by a valid proof, it is immediately and unconditionally accepted; otherwise, it is rejected. This mechanism relies on cryptographic assumptions, rather than trust in certain participants or processes. While it eliminates the need for a challenge period, it requires significant upfront computation to generate the proof.

### Governance

The Governance Layer refers to the general set of tools and processes used to manage system configuration, upgrades, and design decisions. This is a relatively abstract layer that can contain a wide range of mechanisms on a target OP Stack chain and on third-party chains that impact many of the other layers of the OP Stack.

#### MultiSig contracts

MultiSig Contracts are smart contracts that carry out actions when they receive a threshold of signatures from some pre-defined set of participants. These are often used to manage upgrades of components of an OP Stack based system. Currently, this is the mechanism used to manage upgrades of the bridge contracts on OP Mainnet. The security of a MultiSig Contract system depends on many different factors, including the number of participants, the threshold, and the safety procedures of each individual participant.

#### Governance tokens

Governance Tokens are widely used to decentralize decision-making. Although the exact functionality of a Governance Token varies on a case-by-case basis, the most common mechanisms allow token holders to vote on some subset of decisions that a project must make. Voting can either be carried out directly or via delegation.


# Derivation pipeline
Source: https://docs.optimism.io/op-stack/protocol/derivation-pipeline

Overview of the derivation pipeline in the OP Stack protocol.

<NormativeSpec title="L2 chain derivation specification" href="https://specs.optimism.io/protocol/derivation.html" />

The derivation pipeline is a fundamental component of the OP Stack protocol, responsible for processing and validating transactions in the Optimism network. It ensures the integrity and security of the blockchain by deriving a consistent state from the sequenced transactions and batches submitted by the sequencer.

## Key functions of the derivation pipeline

The following are key functions of the derivation pipeline:

* **Batch Submission and Sequencing**: Transactions are collected and sequenced into batches by the sequencer. These batches are then submitted to Layer 1 (L1) for finality and inclusion in the blockchain.
* **Safe Head and Unsafe Blocks**: The derivation pipeline maintains two types of heads: the Safe Head and the Unsafe Head. The Safe Head represents the most recent confirmed state on L1, while the Unsafe Head represents the highest unsafe L2 block that the rollup node knows about. Unsafe Blocks are those that have been sequenced but not yet confirmed on L1 (i.e. those from above the Safe Head up to and including the Unsafe Head).
* **Reorg and Recovery**: If the sequencing window (typically 12 hours) is exceeded without a valid batch being discovered on L1, the pipeline will revert all Unsafe Blocks from that period. The pipeline then progresses using a default block that is empty except for deposits, allowing the network to recover and continue processing new transactions.

## Sequencer window

The sequencer window defines the maximum time allowed for batches to be submitted and confirmed on L1. If this window is exceeded, the derivation pipeline takes corrective actions to ensure the network's integrity and continued operation.

For example:

* In a 12-hour sequencing window, if no valid batch is discovered on L1, the pipeline reverts to Unsafe Blocks and uses a default block to move forward.
* Increasing the window to 24 hours allows nodes to wait longer before reorging out unsafe blocks, but it may introduce additional challenges such as increased resource constraints and difficulty in processing larger batches.

## Configuration and adjustments

The `sequencerWindowSize` parameter is set during the deployment configurations and may be difficult to change once established. It is important for chain operators to carefully consider the appropriate window size to balance network performance and stability.

## Next steps

* For more detailed information, refer to the [derivation pipeline specification](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs).
* Have questions? You can ask a question in the [developer support forum](https://github.com/ethereum-optimism/developers/discussions).


# Design philosophy & principles
Source: https://docs.optimism.io/op-stack/protocol/design-principles

Learn the design philosophy and principles used to build the OP Stack.

<Info>
  **Learn the OP Stack — stop 2 of 13.**
  You've seen what the OP Stack is and what you can build with it. This
  page adds the design pillars that explain why the stack is built the
  way it is. When you're done, continue to
  [Differences from Ethereum](/op-stack/protocol/differences).
</Info>

## Design philosophy

OP Stack is built according to a strong design philosophy that stands on four main pillars: **simplicity**, **pragmatism**, **sustainability**, and, of course, **optimism**.
It's important to understand these pillars as they heavily influence the design of Optimism as a whole.

### Simplicity

Optimism is designed to be as simple as possible for the feature set it provides.
Ideally, Optimism should be composed of the minimum number of moving parts required for a secure, scalable, and flexible L2 system.
This simplicity gives Optimism's design a number of significant advantages over other more complex L2 constructions.

Simplicity reduces engineering overhead, which in turn means we can spend our time working on new features instead of re-creating existing ones.
Optimism prefers to use existing battle-tested Ethereum code and infrastructure where possible.
The most visible example of this philosophy in practice is the choice to use Geth as Optimism's client software.

When dealing with critical infrastructure, simplicity is also security.
Every line of code we write is an opportunity to introduce unintentional bugs.
A simple protocol means there's less code to write and, as a result, less surface area for potential mistakes.
A clean and minimal codebase is also more accessible to external contributors and auditors.
All of this serves to maximize the security and correctness of the Optimism protocol.

Simplicity is also important for the long-term vision of Optimism.
By limiting the amount of code that we write on top of Ethereum tooling, we're able to spend most of our time working directly with existing codebases.
Engineering effort that goes into Optimism can also directly benefit Ethereum, and vice versa.
This will only become more pronounced as the Optimism protocol solidifies and existing resources can be redirected towards core Ethereum infrastructure.

### Pragmatism

For all its idealism, the design process behind Optimism is ultimately driven by pragmatism.
The core Optimism team has real-world constraints, the projects that build on Optimism have real-world needs, and the users that engage with Optimism have real-world problems.
Optimism's design philosophy prioritizes user and developer needs over theoretical perfection.
Sometimes the best solution isn't the prettiest one.

Optimism is also developed with the understanding that any core team will have limited areas of expertise.
Optimism is developed iteratively and strives to continuously pull feedback from users.
Many core Optimism features today (like [EVM Equivalence](https://web.archive.org/web/20231127160757/https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306) were only made possible by this iterative approach to protocol development.

### Sustainability

Optimism is in it for the long haul.
Application developers need assurance that the platform they're building on will remain not only operational but competitive over long periods of time.
Optimism's design process is built around the idea of long-term sustainability and not taking shortcuts to scalability.
At the end of the day, a scalable system means nothing without the ecosystem that sustains it.

Sustainability actively influences Optimism's protocol design in ways that go hand-in-hand with our philosophy of simplicity.
The more complex a codebase, the more difficult it is for people outside of the core development team to actively contribute.
By keeping our codebase simple we're able to build a bigger community of contributors who can help maintain the protocol long-term.

### Optimism

Of course, none of this would be possible without a sense of optimism.
Our optimism about the Ethereum vision keeps this project moving forward.
We believe in an optimistic future for Ethereum, a future where we get to redesign our relationships with the institutions that coordinate our lives.

Although Optimism looks like a standalone blockchain, it's ultimately designed as an extension to Ethereum.
We keep this in mind whenever we're creating new features or trying to simplify existing ones.
Optimism is as close to Ethereum as possible not only for pragmatic reasons, but because Optimism exists so that Ethereum can succeed.
We hope that you can see the influence of this philosophy when looking at Optimism's design.

## Design principles for USEful software

The OP Stack is USEful software. The OP Stack is a set of software components for building L2 blockchain ecosystems, built by the Optimism Collective to power Optimism.
Components to be added to the OP Stack should be built according to three key design principles: \*\*Utility, \*\*Simplicity, \*\*Extensibility.
Software that follows these principles is **USEful** software for the Optimism Collective!

### Utility

For something to be part of the OP Stack, it should help power the Optimism Collective.
This condition helps guide the type of software that can be included in the stack.
For instance, a powerful open-source block explorer that makes it easier for users to inspect [OP Stack chains](https://app.optimism.io/superchain/?utm_source=op-docs\&utm_medium=docs) would be a great addition to the OP Stack.

Although utility is important for inclusion in the OP Stack, you shouldn't be afraid to experiment.
Do something crazy.
Build something that's never been built before, even if it doesn't have any clear utility. Make a blockchain for Emojis, or whatever. Have fun!

### Simplicity

Complex code does not scale.
Code that makes it into the OP Stack should be simple.

Simplicity reduces engineering overhead, which in turn means the Collective can spend its time working on new features instead of re-creating existing ones.
The OP Stack prefers to use existing battle-tested code and infrastructure where possible.
The most visible example of this philosophy in practice is the choice to use Geth as the OP Stack's default execution engine.

When dealing with critical infrastructure, simplicity is also security and maintainability.
Every line of code written is an opportunity to introduce bugs and vulnerabilities.
A simple protocol means there's less code to write and, as a result, less surface area for potential mistakes.
A clean and minimal codebase is also more accessible to external contributors and auditors.
All of this serves to maximize the security and correctness of the OP Stack.

### Extensibility

Good OP Stack code is inherently open, collaborative, and extensible.
Collaboration allows us to break out of siloed development.
Collaboration allows us to spend more time building on top of one another's work and less time rebuilding the same components over and over again.
Collaboration is how we win, *together*.

Extensible code should be designed with the mindset that others will want to build with and on top of that code.
In practice, this means that the code should be open source (under a permissive license), expose clean APIs, and generally be modular such that another developer can relatively easily extend the functionality of the code.
Extensibility is a key design principle that unlocks the superpower of collaboration within the Optimism Collective ecosystem.


# Differences from Ethereum
Source: https://docs.optimism.io/op-stack/protocol/differences

Learn the minor differences between the behavior of Ethereum and the OP Stack.

<Info>
  **Learn the OP Stack — stop 3 of 13.**
  You know what the stack is and the principles behind it. This page
  grounds what "EVM equivalent" means in practice: the small set of
  behaviors where OP Stack chains differ from Ethereum. When you're done,
  continue to [OP Stack components](/op-stack/protocol/components).
</Info>

OP Stack chains are designed to be [EVM equivalent](https://web.archive.org/web/20231127160757/https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306) and introduces as few changes as possible to the Ethereum protocol.
However, there are some minor differences between the behavior of Ethereum and OP Stack chains that developers should be aware of.

## Bridging

### Bridging - Deposit Transactions

Deposit transactions don't exist on L1s, and are how transactions on an L2 can be initiated from the L1. Importantly, this is how bridge applications can get L1 ETH or tokens into an L2 OP Stack chain. You can read more on deposit transactions [here](/op-stack/bridging/deposit-flow).

### Bridging - Withdrawal Transactions and Fault Proofs

Withdrawal transactions are how the state of the L2 rollup can be proven to the L1. Often this involves users withdrawing tokens or ETH to the L1. Fault proofs are the mechanism by which withdrawal transactions are currently proven to the L1. You can read more about fault proofs [here](/op-stack/fault-proofs/explainer).

## Opcodes

| Opcode       | Solidity Equivalent | Behavior                                                                                                                                                                                                                                                |
| ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COINBASE`   | `block.coinbase`    | Returns the address of the current Sequencer's fee wallet. Effectively the same as Ethereum with the caveat that the value typically does not change from block to block.                                                                               |
| `PREVRANDAO` | `block.prevrandao`  | Returns the PREVRANDAO (the most recent [RANDAO](https://eips.ethereum.org/EIPS/eip-4399)) value of L1 at the current L1 origin block.                                                                                                                  |
| `ORIGIN`     | `tx.origin`         | If the transaction is an L1 ⇒ L2 transaction triggered by a smart contract on L1, then `tx.origin` is set to the [aliased address](#address-aliasing) of the address that triggered the L1 ⇒ L2 transaction. Otherwise, this opcode behaves normally.   |
| `CALLER`     | `msg.sender`        | If the transaction is an L1 ⇒ L2 transaction triggered by a smart contract on L1, and this is the first call frame (rather than an internal transaction from one contract to another), the same [address aliasing](#address-aliasing) behavior applies. |

### Address aliasing

<Info>
  Address aliasing is an important security feature that impacts the behavior of transactions sent from L1 to L2 by smart contracts.
  Make sure to read this section carefully if you are working with cross-chain transactions.
  Note that the `CrossChainMessenger` contracts will handle address aliasing internally on your behalf.
</Info>

When transactions are sent from L1 to L2 by an Externally Owned Account, the address of the sender of the transaction on L2 will be set to the address of the sender of the transaction on L1.
**However, the address of the sender of a transaction on L2 will be different if the transaction was triggered by a smart contract on L1**.

Because of the behavior of the `CREATE` opcode, it is possible to create a contract on both L1 and on L2 that share the same address but have different bytecode.
Even though these contracts share the same address, they are fundamentally two different smart contracts and cannot be treated as the same contract.
As a result, the sender of a transaction sent from L1 to L2 by a smart contract cannot be the address of the smart contract on L1 or the smart contract on L1 could act as if it were the smart contract on L2 (because the two contracts share the same address).

To prevent this sort of impersonation, the sender of a transaction is slightly modified by the `OptimismPortal` when a smart contract calls `depositTransaction` to send a transaction from L1 to L2.
This alias is applied when the caller has code, and that code is not a valid EIP-7702 delegation.
When the address has no code, or the code present at the address is a valid EIP-7702 delegation, the sender is not modified.
Note that ephemeral contracts (those that are created and self-destructed in the same transaction) WILL be aliased, despite having no code at the start or end of transaction execution.

Instead of appearing to be sent from the actual L1 contract address, the L2 transaction is sent from an "aliased" version of the L1 contract address.
This aliased address is produced by treating the address as a 160-bit integer, adding a constant offset with overflows allowed, and then truncating the result to a 20-byte address.
The address hashing function ensures that aliased address will never conflict with any other address on L2.
The simple offset original L1 address can easily be recovered from the aliased address.

The `OptimismPortal` applies this change only to L2 transactions sent by L1 smart contracts.
In all other cases, the transaction sender address is set according to the same rules used by Ethereum.

| Transaction Source                                        | Sender Address                                                              |
| --------------------------------------------------------- | --------------------------------------------------------------------------- |
| L2 user (Externally Owned, or EIP-7702 Delegated Account) | The user's address (same as in Ethereum)                                    |
| L1 user (Externally Owned, or EIP-7702 Delegated Account) | The user's address (same as in Ethereum)                                    |
| L1 contract (using `OptimismPortal.depositTransaction`)   | `uint160(L1_contract_address) + 0x1111000000000000000000000000000000001111` |

## Transactions

### Transaction fees

Transactions on OP Stack chains must pay for an [L1 data fee](/op-stack/transactions/fees#the-l1-data-fee) on top of the standard [execution gas fee](/op-stack/transactions/fees#execution-gas-fee) you would expect on Ethereum.
Refer to the guide on [OP Stack Transaction Fees](/op-stack/transactions/fees) for more information.

You can use the [JS library viem](https://viem.sh/op-stack) to estimate the entire transaction gas costs, including the L1 Data Fee.

### EIP-1559 parameters

The base fee on OP Stack is, like Ethereum, computed via the [EIP-1559](https://notes.ethereum.org/@vbuterin/eip-1559-faq) mechanism.
The EIP-1559 parameters used by OP Stack differ per chain.

### Mempool rules

Unlike Ethereum, OP Stack chains do not have a public mempool.
The OP Stack mempool is currently only visible to the Sequencer.
The Sequencer executes transactions from the mempool in priority fee order (highest fee first).

## Chain Finality

Unlike L1s such as Ethereum, OP Stack chains have Unsafe, Safe, and Finalized Heads which indicate the state of finality for a given L2 block. Fault proofs do not impact the finalization of the L2 rollup, only the finalization of withdrawal transactions to the L1. You can read more about these [in the docs glossary](/connect/resources/glossary#unsafe-l2-block).

## What's Next

There are various useful tools linked above. Here are a few more tools and links you may want to check out:

* [OP-viem](https://viem.sh/op-stack): JS framework that can handle many of these unique functions on OP Chains. It is similar to Ethers.js for OP Stack chains.

* [Specs](https://specs.optimism.io/root.html?utm_source=op-docs\&utm_medium=docs): For more in-depth technical explanations and examples.


# Canyon
Source: https://docs.optimism.io/op-stack/protocol/hardforks/canyon

Hardfork registry entry for the Canyon network upgrade, which brought L1's Shapella upgrade to the OP Stack.

<NormativeSpec title="Canyon specification" href="https://specs.optimism.io/protocol/canyon/overview.html" />

Canyon brought Ethereum's Shapella upgrade to the OP Stack along with minor
protocol fixes.

|                                         |                                                                                            |
| --------------------------------------- | ------------------------------------------------------------------------------------------ |
| Status                                  | Active                                                                                     |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/canyon/overview.html)               |
| Governance approval                     | [proposal](https://gov.optimism.io/t/final-upgrade-proposal-2-canyon-network-upgrade/7088) |
| Mainnet activation (superchain default) | Thu, 11 Jan 2024 17:00:01 UTC (`1704992401`)                                               |
| Sepolia activation (superchain default) | Tue, 14 Nov 2023 17:00:00 UTC (`1699981200`)                                               |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/canyon/overview.html):

* Shapella EIPs on L2: [EIP-3651](https://eips.ethereum.org/EIPS/eip-3651)
  (warm COINBASE), [EIP-3855](https://eips.ethereum.org/EIPS/eip-3855)
  (`PUSH0`), [EIP-3860](https://eips.ethereum.org/EIPS/eip-3860) (limit and
  meter initcode), [EIP-4895](https://eips.ethereum.org/EIPS/eip-4895)
  (withdrawals operations, set to the empty array on L2), and
  [EIP-6049](https://eips.ethereum.org/EIPS/eip-6049) (deprecate
  `SELFDESTRUCT`).
* Modified the EIP-1559 denominator.
* Added the deposit nonce and deposit nonce version to the deposit receipt
  hash.
* Deployed the `create2Deployer` predeploy at
  `0x13b0D85CcB8bf860b6b79AF3029fCA081AE9beF2`.
* Consensus layer: channel ordering fix.


# Delta
Source: https://docs.optimism.io/op-stack/protocol/hardforks/delta

Hardfork registry entry for the Delta network upgrade, which introduced span batches.

<NormativeSpec title="Delta specification" href="https://specs.optimism.io/protocol/delta/overview.html" />

Delta consisted of a single consensus-layer feature: span batches, which reduce
the fixed per-block overhead of batch submission.

|                                         |                                                                                           |
| --------------------------------------- | ----------------------------------------------------------------------------------------- |
| Status                                  | Active                                                                                    |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/delta/overview.html)               |
| Governance approval                     | [proposal](https://gov.optimism.io/t/final-upgrade-proposal-3-delta-network-upgrade/7310) |
| Mainnet activation (superchain default) | Thu, 22 Feb 2024 00:00:00 UTC (`1708560000`)                                              |
| Sepolia activation (superchain default) | Fri, 22 Dec 2023 00:00:00 UTC (`1703203200`)                                              |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/delta/overview.html):

* Consensus layer: [span batches](https://specs.optimism.io/protocol/delta/span-batches.html).
  Delta is specified only in the rollup node (`delta_time`); it required no
  execution-engine change.


# Ecotone
Source: https://docs.optimism.io/op-stack/protocol/hardforks/ecotone

Hardfork registry entry for the Ecotone network upgrade, which adopted EIP-4844 blobs for data availability.

<NormativeSpec title="Ecotone specification" href="https://specs.optimism.io/protocol/ecotone/overview.html" />

Ecotone brought Ethereum's Dencun upgrade to the OP Stack and adopted
[EIP-4844](https://eips.ethereum.org/EIPS/eip-4844) blobs for data
availability, dramatically reducing L1 data costs.

|                                         |                                                                                       |
| --------------------------------------- | ------------------------------------------------------------------------------------- |
| Status                                  | Active                                                                                |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/ecotone/overview.html)         |
| Governance approval                     | [proposal](https://gov.optimism.io/t/upgrade-proposal-5-ecotone-network-upgrade/7669) |
| Mainnet activation (superchain default) | Thu, 14 Mar 2024 00:00:01 UTC (`1710374401`)                                          |
| Sepolia activation (superchain default) | Wed, 21 Feb 2024 17:00:00 UTC (`1708534800`)                                          |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/ecotone/overview.html):

* Cancun EIPs on L2: [EIP-1153](https://eips.ethereum.org/EIPS/eip-1153)
  (transient storage), [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844)
  (with blob transactions disabled on L2),
  [EIP-4788](https://eips.ethereum.org/EIPS/eip-4788) (L1 beacon block root
  embedded into L2), [EIP-5656](https://eips.ethereum.org/EIPS/eip-5656)
  (`MCOPY`), [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780)
  (`SELFDESTRUCT` only in same transaction), and
  [EIP-7516](https://eips.ethereum.org/EIPS/eip-7516) (`BLOBBASEFEE`, always
  pushing 1 on L2).
* Consensus layer: blob data availability in the L1 data-retrieval stage and
  in L1 data fee computation.
* Auto-upgrade and extension of the `L1Block` (L1 attributes) predeploy.


# Fjord
Source: https://docs.optimism.io/op-stack/protocol/hardforks/fjord

Hardfork registry entry for the Fjord network upgrade, which introduced FastLZ fee estimation and Brotli compression.

<NormativeSpec title="Fjord specification" href="https://specs.optimism.io/protocol/fjord/overview.html" />

Fjord improved fee estimation and batch compression, and added the secp256r1
precompile.

|                                         |                                                                                     |
| --------------------------------------- | ----------------------------------------------------------------------------------- |
| Status                                  | Active                                                                              |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/fjord/overview.html)         |
| Governance approval                     | [proposal](https://gov.optimism.io/t/upgrade-proposal-9-fjord-network-upgrade/8236) |
| Mainnet activation (superchain default) | Wed, 10 Jul 2024 16:00:01 UTC (`1720627201`)                                        |
| Sepolia activation (superchain default) | Wed, 29 May 2024 16:00:00 UTC (`1716998400`)                                        |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/fjord/overview.html):

* Execution layer: [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md)
  precompile for secp256r1 curve support; FastLZ compression for L1 data fee
  calculation; deprecated the `getL1GasUsed` method on the `GasPriceOracle`
  predeploy and the `L1GasUsed` receipt field.
* Consensus layer: constant maximum sequencer drift; Brotli channel
  compression; increased max bytes per channel and max channel bank size.


# Granite
Source: https://docs.optimism.io/op-stack/protocol/hardforks/granite

Hardfork registry entry for the Granite network upgrade, a hardening upgrade limiting bn256Pairing input size.

<NormativeSpec title="Granite specification" href="https://specs.optimism.io/protocol/granite/overview.html" />

Granite was a small hardening upgrade to the fault-proof surface area.

|                                         |                                                                                        |
| --------------------------------------- | -------------------------------------------------------------------------------------- |
| Status                                  | Active                                                                                 |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/granite/overview.html)          |
| Governance approval                     | [proposal](https://gov.optimism.io/t/upgrade-proposal-10-granite-network-upgrade/8733) |
| Mainnet activation (superchain default) | Wed, 11 Sep 2024 16:00:01 UTC (`1726070401`)                                           |
| Sepolia activation (superchain default) | Mon, 12 Aug 2024 16:00:00 UTC (`1723478400`)                                           |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/granite/overview.html):

* Execution layer: limited the `bn256Pairing` precompile input size.
* Consensus layer: reduced the channel timeout to 50.


# Holocene
Source: https://docs.optimism.io/op-stack/protocol/hardforks/holocene

Hardfork registry entry for the Holocene network upgrade, which introduced stricter derivation and dynamic EIP-1559 parameters.

<NormativeSpec title="Holocene specification" href="https://specs.optimism.io/protocol/holocene/overview.html" />

Holocene reworked derivation rules and made EIP-1559 fee parameters
configurable by chain operators.

|                                         |                                                                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Status                                  | Active                                                                                                                       |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/holocene/overview.html)                                               |
| Governance approval                     | [proposal](https://vote.optimism.io/proposals/20127877429053636874064552098716749508236019236440427814457915785398876262515) |
| Operator notice                         | [View notice](/notices/archive/holocene-changes)                                                                             |
| Mainnet activation (superchain default) | Thu, 09 Jan 2025 18:00:01 UTC (`1736445601`)                                                                                 |
| Sepolia activation (superchain default) | Tue, 26 Nov 2024 15:00:00 UTC (`1732633200`)                                                                                 |

Minimum component versions (from [Holocene notice](/notices/archive/holocene-changes)):

| Component | Minimum version |
| --------- | --------------- |
| `op-node` | `v1.10.2`       |
| `op-geth` | `v1.101411.4`   |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/holocene/overview.html):

* Execution layer: [dynamic EIP-1559 parameters](https://specs.optimism.io/protocol/holocene/exec-engine.html#dynamic-eip-1559-parameters).
* Consensus layer: [Holocene derivation](https://specs.optimism.io/protocol/holocene/derivation.html#holocene-derivation).
* Smart contracts: `SystemConfig` updates.

The [Holocene notice](/notices/archive/holocene-changes) covers the operator
steps that accompanied activation, including the L1 contract upgrades.


# Isthmus
Source: https://docs.optimism.io/op-stack/protocol/hardforks/isthmus

Hardfork registry entry for the Isthmus network upgrade, which brought L1's Pectra upgrade to the OP Stack and added the operator fee.

<NormativeSpec title="Isthmus specification" href="https://specs.optimism.io/protocol/isthmus/overview.html" />

Isthmus brought Ethereum's Pectra upgrade to the OP Stack and introduced the
operator fee.

|                                         |                                                                                                                             |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Status                                  | Active                                                                                                                      |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/isthmus/overview.html)                                               |
| Governance approval                     | [proposal](https://vote.optimism.io/proposals/8705916809146420472067303211131851783087744913535435360574720946039078686841) |
| Operator notice                         | [Upgrade 15 notice](/notices/archive/upgrade-15)                                                                            |
| Mainnet activation (superchain default) | Fri, 09 May 2025 16:00:01 UTC (`1746806401`)                                                                                |
| Sepolia activation (superchain default) | Thu, 17 Apr 2025 16:00:00 UTC (`1744905600`)                                                                                |

Minimum component versions (from [Upgrade 15 notice](/notices/archive/upgrade-15)):

| Component       | Minimum version |
| --------------- | --------------- |
| `op-node`       | `v1.13.2`       |
| `op-geth`       | `v1.101503.4`   |
| `op-batcher`    | `v1.12.0`       |
| `op-challenger` | `v1.4.0`        |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/isthmus/overview.html):

* Pectra EIPs on L2, including
  [EIP-7702](https://eips.ethereum.org/EIPS/eip-7702) (set EOA account code),
  [EIP-2537](https://eips.ethereum.org/EIPS/eip-2537) (BLS12-381
  precompiles), [EIP-2935](https://eips.ethereum.org/EIPS/eip-2935)
  (historical block hashes in state), and
  [EIP-7623](https://eips.ethereum.org/EIPS/eip-7623) (increased calldata
  cost). The [EIP-7002](https://eips.ethereum.org/EIPS/eip-7002) and
  [EIP-7251](https://eips.ethereum.org/EIPS/eip-7251) predeploy contracts and
  syscalls are not adopted by the OP Stack.
* `L2ToL1MessagePasser` storage root in the block header.
* [Operator fee](https://specs.optimism.io/protocol/isthmus/exec-engine.html#operator-fee).
* Smart contracts: predeploy, L1 block attributes, and `SystemConfig` updates.

The [Upgrade 15 notice](/notices/archive/upgrade-15) covers the operator steps
that accompanied activation.


# Jovian
Source: https://docs.optimism.io/op-stack/protocol/hardforks/jovian

Hardfork registry entry for the Jovian network upgrade, which introduced the minimum base fee and DA footprint limit.

<NormativeSpec title="Jovian specification" href="https://specs.optimism.io/protocol/jovian/overview.html" />

Jovian introduced fee-market and data-availability controls for chain
operators.

|                                         |                                                                                                                             |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Status                                  | Active                                                                                                                      |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/jovian/overview.html)                                                |
| Governance approval                     | [proposal](https://vote.optimism.io/proposals/3118571676657709551286937570456546163542507117143005939043790253732885172699) |
| Operator notice                         | [Upgrade 17 notice](/notices/archive/upgrade-17)                                                                            |
| Mainnet activation (superchain default) | Tue, 02 Dec 2025 16:00:01 UTC (`1764691201`)                                                                                |
| Sepolia activation (superchain default) | Wed, 19 Nov 2025 16:00:01 UTC (`1763568001`)                                                                                |

Minimum component versions (from [Upgrade 17 notice](/notices/archive/upgrade-17)):

| Component       | Minimum version |
| --------------- | --------------- |
| `op-node`       | `v1.16.2`       |
| `op-batcher`    | `v1.16.2`       |
| `op-geth`       | `v1.101603.5`   |
| `op-challenger` | `v1.7.0`        |
| `kona-node`     | `v1.2.4`        |
| `op-reth`       | `v1.9.2`        |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/jovian/overview.html):

* Execution layer:
  [minimum base fee](https://specs.optimism.io/protocol/jovian/exec-engine.html#minimum-base-fee),
  [DA footprint limit](https://specs.optimism.io/protocol/jovian/exec-engine.html#da-footprint-block-limit),
  and [operator fee](https://specs.optimism.io/protocol/jovian/exec-engine.html#operator-fee)
  changes.
* Consensus layer: network upgrade transactions applied during derivation;
  auto-upgrade and extension of the `L1Block` (L1 attributes) predeploy.
* Smart contracts: `SystemConfig` updates.

The [Upgrade 17 notice](/notices/archive/upgrade-17) covers the operator steps
that accompanied activation.


# Karst
Source: https://docs.optimism.io/op-stack/protocol/hardforks/karst

Hardfork registry entry for the Karst network upgrade, which introduced the L2 Contract Manager and Osaka EIPs on L2.

<NormativeSpec title="Karst specification" href="https://specs.optimism.io/protocol/karst/overview.html" />

Karst (Upgrade 19) introduced the L2 Contract Manager, activated a subset of
Osaka EIPs on L2, promoted `CANNON_KONA` to the respected game type, and
reduced the `bn256Pairing` precompile input limit as a preemptive Glamsterdam
defense. `op-geth` and `op-program` do not support Karst — see the
[end-of-support notice](/notices/archive/op-geth-deprecation).

|                                         |                                                                             |
| --------------------------------------- | --------------------------------------------------------------------------- |
| Status                                  | Active                                                                      |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/karst/overview.html) |
| Operator notice                         | [Upgrade 19 notice](/notices/archive/upgrade-19)                            |
| Mainnet activation (superchain default) | Wed, 08 Jul 2026 16:00:01 UTC (`1783526401`)                                |
| Sepolia activation (superchain default) | Wed, 17 Jun 2026 16:00:01 UTC (`1781712001`)                                |

Minimum component versions (from [Upgrade 19 notice](/notices/archive/upgrade-19)):

| Component        | Minimum version |
| ---------------- | --------------- |
| `op-node`        | `v1.19.1`       |
| `op-reth`        | `v2.3.3`        |
| `op-challenger`  | `v1.9.3`        |
| `op-dispute-mon` | `v1.5.2`        |
| `op-contracts`   | `v7.0.0`        |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/karst/overview.html)
and the [Upgrade 19 notice](/notices/archive/upgrade-19):

* [L2 Contract Manager (L2CM)](/op-stack/features/l2-contract-manager):
  governance-approved L2 predeploy upgrades through a consensus-layer
  mechanism.
* Osaka EIPs on L2, including
  [EIP-7825](https://eips.ethereum.org/EIPS/eip-7825) (transaction gas limit
  cap, not applied to deposits),
  [EIP-7823](https://eips.ethereum.org/EIPS/eip-7823) and
  [EIP-7883](https://eips.ethereum.org/EIPS/eip-7883) (MODEXP bounds and gas),
  [EIP-7910](https://eips.ethereum.org/EIPS/eip-7910) (`eth_config`),
  [EIP-7939](https://eips.ethereum.org/EIPS/eip-7939) (CLZ opcode), and
  [EIP-7951](https://eips.ethereum.org/EIPS/eip-7951) (secp256r1 gas cost
  alignment).
* Reduced the `bn256Pairing` precompile maximum input size from 427 to 300
  pairs (Glamsterdam defense).
* Promoted `CANNON_KONA` (game type 8) to the respected game type, making
  `kona-client` the primary fault proof program used for withdrawals.
* Consensus layer: network upgrade transactions applied during derivation.


# Lagoon
Source: https://docs.optimism.io/op-stack/protocol/hardforks/lagoon

Hardfork registry entry for the Lagoon network upgrade, which activates Superchain interop.

<NormativeSpec title="Lagoon specification" href="https://specs.optimism.io/protocol/lagoon/overview.html" />

Lagoon is the upcoming hardfork that activates Superchain
[interop](/op-stack/interop/explainer). No superchain-wide activation defaults
are set in the superchain-registry yet; the first activations are being
prepared per chain — see the
[interop activation prep notice](/notices/interop-prep) for OP Sepolia and
Unichain Sepolia.

|                                         |                                                                              |
| --------------------------------------- | ---------------------------------------------------------------------------- |
| Status                                  | In development                                                               |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/lagoon/overview.html) |
| Operator notice                         | [View notice](/notices/interop-prep)                                         |
| Mainnet activation (superchain default) | Not scheduled                                                                |
| Sepolia activation (superchain default) | Not scheduled                                                                |

## What's included

Per the [spec overview](https://specs.optimism.io/protocol/lagoon/overview.html)
(subject to change while the spec is in development):

* Interop: dependency set, cross-chain messaging, derivation, sequencer and
  verifier behavior, super roots, interop fault proofs, and the interop
  bridging contracts.
* Execution layer: post-execution transactions and sequencer-defined
  metering.


# Regolith
Source: https://docs.optimism.io/op-stack/protocol/hardforks/regolith

Hardfork registry entry for the Regolith network upgrade, which corrected deposit processing after Bedrock.

<NormativeSpec title="Regolith specification" href="https://specs.optimism.io/protocol/regolith/overview.html" />

Regolith made minor corrections to deposit processing based on audit findings
after Bedrock. It activates at timestamp `0` on OP Mainnet and OP Sepolia —
that is, from the Bedrock migration onward — which predates the
superchain-registry's superchain-wide hardfork defaults.

|                                         |                                                                                |
| --------------------------------------- | ------------------------------------------------------------------------------ |
| Status                                  | Active                                                                         |
| Governing spec                          | [specs.optimism.io](https://specs.optimism.io/protocol/regolith/overview.html) |
| Mainnet activation (superchain default) | Genesis / at Bedrock                                                           |
| Sepolia activation (superchain default) | Genesis / at Bedrock                                                           |

## What changed

Per the [spec overview](https://specs.optimism.io/protocol/regolith/overview.html):

* Disabled the `isSystemTx` boolean; system transactions use the same gas
  accounting rules as regular deposits.
* Records actual deposit gas usage in the deposit transaction receipt and
  subtracts it from the L2 block gas pool (unused deposit gas is not refunded).
* Adds the optional `depositNonce` receipt field and uses it to correct
  transaction and receipt metadata in RPC responses.
* Commits `gas` and `depositNonce` into the consensus representation of the
  receipt so the data syncs safely between L2 nodes.
* Corrects the L1 cost function to more closely match pre-Bedrock behavior.


# OP Stack protocol
Source: https://docs.optimism.io/op-stack/protocol/index

The protocol layer's home on this site, routing to the normative specifications, the rollup explainers, and the hardfork registry.

This section is the protocol layer's home on docs.optimism.io. Protocol
behavior is normatively defined in the
[OP Stack specifications](https://specs.optimism.io/); per the
[content guide](/op-stack/contribute/content-guide), the pages here explain
concepts and route to the exact spec section; they never restate normative
text.

<CardGroup>
  <Card title="Get the canonical definition" href="https://specs.optimism.io/">
    Read the OP Stack specifications, the normative source for all protocol
    behavior.
  </Card>

  <Card title="Understand how the rollup works" href="/op-stack/protocol/overview">
    Learn how Optimistic Rollups work: block storage, production, execution,
    bridging, and fault proofs at a high level.
  </Card>

  <Card title="Look up a network upgrade" href="/op-stack/protocol/network-upgrades">
    Find any hardfork's activation timestamps, governing spec, and minimum
    component versions in the registry.
  </Card>

  <Card title="Meet the components that implement it" href="/op-stack/components/index">
    Find the canonical hub for each OP Stack component, grouped by protocol
    role.
  </Card>

  <Card title="Check who holds privileged roles" href="/op-stack/protocol/privileged-roles">
    See the privileged roles OP Stack chains still include, the risks they
    pose, and their mitigations.
  </Card>

  <Card title="Looking for something else?" href="/">
    Browse the documentation by role: app developer, chain operator, or node
    operator.
  </Card>
</CardGroup>


# Network upgrades
Source: https://docs.optimism.io/op-stack/protocol/network-upgrades

The hardfork registry — activation times, governing specs, and minimum component versions for every OP Stack network upgrade.

<NormativeSpec title="Superchain upgrades specification" href="https://specs.optimism.io/protocol/superchain-upgrades.html#activation-rules" />

This page is the index of the **hardfork registry**: every OP Stack hardfork
has one permanent page recording its activation timestamps, governing
specification, governance approval, and minimum component versions.
Governance-approved [contract upgrades](#contract-upgrades) that carry no
hardfork are listed separately below. Network upgrade names after Bedrock
follow a geology theme based on the next letter of the English alphabet.

The table below is generated from the registry pages' structured frontmatter
and validated against the
[superchain-registry](https://github.com/ethereum-optimism/superchain-registry) —
it is never hand-edited. See
[How this registry is maintained](#how-this-registry-is-maintained).

## Activations

Network upgrades activate by L2 block timestamp. Failing to upgrade your OP
Stack software before the activation timestamp causes a chain divergence, and
you will need to resync the chain. Operator action items for each upgrade are
published in [Notices](/notices).

| Hardfork                                          | Status         | [Mainnet activation](https://github.com/ethereum-optimism/superchain-registry/blob/main/superchain/configs/mainnet/superchain.toml) | [Sepolia activation](https://github.com/ethereum-optimism/superchain-registry/blob/main/superchain/configs/sepolia/superchain.toml) |
| ------------------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [Lagoon](/op-stack/protocol/hardforks/lagoon)     | In development | Not scheduled                                                                                                                       | Not scheduled                                                                                                                       |
| [Karst](/op-stack/protocol/hardforks/karst)       | Active         | Wed, 08 Jul 2026 16:00:01 UTC (`1783526401`)                                                                                        | Wed, 17 Jun 2026 16:00:01 UTC (`1781712001`)                                                                                        |
| [Jovian](/op-stack/protocol/hardforks/jovian)     | Active         | Tue, 02 Dec 2025 16:00:01 UTC (`1764691201`)                                                                                        | Wed, 19 Nov 2025 16:00:01 UTC (`1763568001`)                                                                                        |
| [Isthmus](/op-stack/protocol/hardforks/isthmus)   | Active         | Fri, 09 May 2025 16:00:01 UTC (`1746806401`)                                                                                        | Thu, 17 Apr 2025 16:00:00 UTC (`1744905600`)                                                                                        |
| [Holocene](/op-stack/protocol/hardforks/holocene) | Active         | Thu, 09 Jan 2025 18:00:01 UTC (`1736445601`)                                                                                        | Tue, 26 Nov 2024 15:00:00 UTC (`1732633200`)                                                                                        |
| [Granite](/op-stack/protocol/hardforks/granite)   | Active         | Wed, 11 Sep 2024 16:00:01 UTC (`1726070401`)                                                                                        | Mon, 12 Aug 2024 16:00:00 UTC (`1723478400`)                                                                                        |
| [Fjord](/op-stack/protocol/hardforks/fjord)       | Active         | Wed, 10 Jul 2024 16:00:01 UTC (`1720627201`)                                                                                        | Wed, 29 May 2024 16:00:00 UTC (`1716998400`)                                                                                        |
| [Ecotone](/op-stack/protocol/hardforks/ecotone)   | Active         | Thu, 14 Mar 2024 00:00:01 UTC (`1710374401`)                                                                                        | Wed, 21 Feb 2024 17:00:00 UTC (`1708534800`)                                                                                        |
| [Delta](/op-stack/protocol/hardforks/delta)       | Active         | Thu, 22 Feb 2024 00:00:00 UTC (`1708560000`)                                                                                        | Fri, 22 Dec 2023 00:00:00 UTC (`1703203200`)                                                                                        |
| [Canyon](/op-stack/protocol/hardforks/canyon)     | Active         | Thu, 11 Jan 2024 17:00:01 UTC (`1704992401`)                                                                                        | Tue, 14 Nov 2023 17:00:00 UTC (`1699981200`)                                                                                        |
| [Regolith](/op-stack/protocol/hardforks/regolith) | Active         | Genesis / at Bedrock                                                                                                                | Genesis / at Bedrock                                                                                                                |

Activation timestamps are the superchain-wide defaults from the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry). Timestamps are the canonical activation mechanism — block heights differ per chain, so no block numbers are listed. Individual chains outside those defaults set their own activation times in their chain config.

All of the above build on **Bedrock**, the
[governance-approved](https://gov.optimism.io/t/final-upgrade-1-bedrock-protocol-upgrade-v2/5548)
2023 re-genesis of OP Mainnet at block `105235063` (L2 timestamp `1686068903`)
that the hardfork series starts from. Sepolia OP Stack chains launched on
Bedrock directly.

## Contract upgrades

Not every governance-approved upgrade is a hardfork: hardforks activate by L2
block timestamp on every chain, while contract upgrades ship as
[op-contracts releases](/releases/op-contracts) and are executed on each
chain's L1 contracts after governance approval. Contract-only upgrades have no
activation timestamp, so they do not get hardfork registry pages — their
permanent record is the op-contracts release history and the operator notice.

| Upgrade     | What it shipped                                                                                                   | Operator notice                        | op-contracts release               |
| ----------- | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------- |
| Upgrade 18  | Cannon + Kona game type, Custom Gas Token v2, creator-pattern dispute game refactor                               | [Notice](/notices/archive/upgrade-18)  | [`v6.0.0`](/releases/op-contracts) |
| Upgrade 16a | Maintenance release superseding Upgrade 16 (removes unused interop withdrawal-proving code, adds feature toggles) | [Notice](/notices/archive/upgrade-16a) | [`v4.1.0`](/releases/op-contracts) |
| Upgrade 16  | Interop-ready `OptimismPortal`, Stage 1 updates, Go 1.23 support in Cannon                                        | [Notice](/notices/archive/upgrade-16)  | [`v4.0.0`](/releases/op-contracts) |
| Upgrade 14  | Multithreaded 64-bit Cannon (MT-Cannon) and Isthmus L1 contracts                                                  | [Notice](/notices/archive/upgrade-14)  | [`v3.0.0`](/releases/op-contracts) |
| Upgrade 13  | OP Contracts Manager (OPCM) and incident response improvements                                                    | [Notice](/notices/archive/upgrade-13)  | [`v2.0.0`](/releases/op-contracts) |

Hardfork-carrying upgrades (for example Upgrade 15 / Isthmus, Upgrade 17 /
Jovian, Upgrade 19 / Karst) are listed in the
[activations table](#activations) above and link to their notices from their
registry pages.

## Upgrade process

Network upgrades follow this general process in which the features included in
the upgrade are put into a release version cut from the `develop` branch and
then the software is deployed on production networks.

<Info>
  "Baking" on a network means the node software has been deployed and is live.
  Engineers take this time to observe the behavior of the software on
  production networks.
</Info>

<Image alt="Node Software Release Timeline" />

<Steps>
  <Step title="Devnet">
    * `Devnet Upgrade Notice Period` is for core developers to upgrade the
      node software on an internal devnet prior to the activation timestamp.
    * `Upgrade Activates on Devnet`
    * `Baking on Devnet`
  </Step>

  <Step title="Testnet">
    * `Testnet Upgrade Notice Period` is to allow testnet node operators to
      upgrade the node software on testnet prior to the activation timestamp.
    * `Upgrade Activates on Testnet`
    * `Baking on Testnet`
  </Step>

  <Step title="Mainnet">
    * `Governance Voting Review Period` is when Optimism governance
      reviews proposals, including network upgrade proposals.
    * `Governance Voting Period` is when Optimism governance
      votes on proposals.
    * `Veto Period` is when the Citizens' House of the governance system can
      veto a protocol upgrade that has been approved by the Token House.
    * `Cut Mainnet Release`
    * `Mainnet Upgrade Notice Period` is to allow mainnet node operators to
      upgrade the node software on mainnet prior to the activation timestamp.
    * `Upgrade Activated`
  </Step>
</Steps>

## How this registry is maintained

Each hardfork page keeps its machine-readable facts (lifecycle, activation
timestamps, spec link, minimum component versions) in structured frontmatter.
`scripts/generate-hardforks.ts` validates that data against the
superchain-registry and renders the activation tables — a frontmatter edit
followed by regeneration is the only way to change an activation row. The
schema is documented in
[`scripts/hardfork-registry.md`](https://github.com/ethereum-optimism/optimism/blob/develop/docs/public-docs/scripts/hardfork-registry.md).


# Sequencer outages
Source: https://docs.optimism.io/op-stack/protocol/outages

Learn what happens if the Sequencer goes down and how you can be prepared.

<NormativeSpec title="deposits specification" href="https://specs.optimism.io/protocol/deposits.html#user-deposited-transactions" />

All OP Stack chains have a Sequencer that can receive, order, and publish L2 transactions to L1.
Like any software system, a Sequencer could potentially become unavailable for any number of different reasons.
It's important to be aware of the implications of a Sequencer outage and how you can be prepared for it.

Sequencer outages can broadly be categorized into two different types:

1. **Sequencer Downtime Outages** occur when the Sequencer is entirely unable to receive and/or process L2 transactions from users. Outages of this type will appear to users as a complete inability to submit transactions to the Sequencer.
2. **Transaction Submission Outages** occur when the Sequencer is still able to receive and process L2 transactions from users but is unable to publish these transactions to L1. Outages of this type generally do not impact users unless they remain unresolved for an extended period of time.

Both outage types can be circumvented by submitting transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684) contract on L1 with certain important caveats.
Keep reading to learn more about these potential outages and how to handle them.

## Sequencer downtime outages

### Description

Sequencer downtime outages occur when the Sequencer is unable to receive and/or process L2 transactions from users.
Outages of this type may be caused by any number of different issues, including bugs in client software, cloud outages, or other similar errors.
Exact causes of Sequencer downtime outages can be dependent on the specific infrastructure used to run the Sequencer for any given OP Stack chain.

### Impact

Sequencer downtime outages can have a significant impact on the user experience.
During an outage of this type, users will be unable to submit transactions directly to the Sequencer.
Users may observe that the network appears to be "stuck" at a particular block height.

### Mitigation

Users can always bypass the Sequencer by sending L2 transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684) contract on L1.
Refer to the [Bypassing the Sequencer](#bypassing-the-sequencer) section below for more information about this functionality.

## Transaction submission outages

### Description

Transaction submission outages occur when the Sequencer is still able to receive and process L2 transactions from users but is unable to publish these transactions to L1.
Outages of this type may be caused by any number of different issues including unexpected L1 network conditions, bugs in transaction submission software, or other similar errors.

### Impact

Transaction submission outages generally do not have a significant impact on the user experience unless they remain unresolved for an extended period of time.
During an outage of this type, users will be able to submit transactions directly to the Sequencer but the blocks including these transactions will not be published to L1.
Users may observe that the "safe" and "finalized" block heights of the L2 chain appear to remain stuck while the "unsafe" block height continues to increase.

Transaction submission outages can cause a more significant impact if they remain unresolved.
Crucially, L2 transactions sent directly to the Sequencer must be published within a certain amount of time after they are included in an L2 block by the Sequencer.
If this time limit is exceeded, the L2 chain must be reorganized to include these transactions in a later block.
This can appear to users as a large change in the expected state of the L2 chain.

### Mitigation

Users can always bypass the Sequencer by sending L2 transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684) contract on L1.
Refer to the [Bypassing the Sequencer](#bypassing-the-sequencer) section for more information about this functionality.

## Bypassing the sequencer

A core security goal of OP Stack chains is that the Sequencer should not be able to prevent users from submitting transactions to the L2 chain.
Users of OP Stack chains can always bypass the sequencer and include transactions in the L2 chain by sending their L2 transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684) contract on L1.

### About the OptimismPortal

The `OptimismPortal` contract is an L1 smart contract that can be used by both smart contracts and EOAs to create L2 transactions without the direct involvement of the Sequencer.
Many users already interact with this contract indirectly when they bridge ETH or other tokens between L1 and L2 via the Standard Bridge system available on all OP Stack chains.

The `OptimismPortal` contract is currently a unique contract for each OP Stack chain.
Refer to the contract addresses page for your OP Stack chain to find the address of the `OptimismPortal` contract.
L2 transactions can be triggered on L1 by calling the `depositTransaction` function on the `OptimismPortal` contract.

### Capabilities

Users can send any type of L2 transaction to the `OptimismPortal` contract including contract creations and transactions that carry ETH value.
As a security measure, transactions sent via the `OptimismPortal` are indistinguishable from transactions sent via the Sequencer from the perspective of smart contracts on L2.

### Address aliasing

Transactions triggered via the `OptimismPortal` contract will appear to have been sent by the L1 address that triggered the transaction **unless** the transaction was sent by a smart contract.
L2 transactions sent by smart contracts via the `OptimismPortal` contract will appear to have been sent by an "aliased" version of the smart contract's address.
Refer to the [address aliasing](/op-stack/protocol/differences#address-aliasing) explainer for more information about address aliasing.

### Inclusion rules

Transactions sent to the `OptimismPortal` contract are processed according to a set of rules designed to limit the impact of a failed Sequencer.
It's important to understand these rules in detail to properly mitigate the effects of an outage.

For all transactions sent to the `OptimismPortal`:

1. Transactions sent within a specific L1 block are processed together.
2. Transactions are given a timestamp no more than [`max_sequencer_drift`](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#overview) in the future.
3. Transactions are processed in the order they are received.
4. Transactions are processed within the [`sequencer_window`](https://specs.optimism.io/glossary.html?utm_source=op-docs\&utm_medium=docs#sequencing-window).

In practice, this means that transactions sent to the `OptimismPortal` contract will always be processed in the order they are received and within a maximum delay of the `sequencer_window` (set to 12 hours by default but may differ from chain to chain).
If the Sequencer is unavailable or transactions are not published to L1 within this `sequencer_window`, OP Stack chains will automatically reorganize themselves to guarantee that these transactions are included in the L2 chain.

Refer to the [L2 Chain Derivation Specification](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs) for a much more detailed explanation of how transactions sent to the `OptimismPortal` contract are processed.

### Inclusion scenarios

It can be helpful to understand how transactions sent to the `OptimismPortal` contract are processed in different scenarios.
The following scenarios make different assumptions about the state of the Sequencer and the L2 chain to illustrate how transactions sent to the `OptimismPortal` contract are processed.

#### Total sequencer outage

In this scenario we'll assume that the Sequencer is completely unavailable and unable to process any transactions.
Users must send transactions directly to the `OptimismPortal` contract to have them included in the L2 chain.
We'll also assume that the `sequencer_window` has been set to 12 hours.
Here, two users are sending transactions to the `OptimismPortal` contract.

Observe how the transactions sent by both users are included in the L2 chain automatically after the `sequencer_window` has elapsed.
The transactions are included in the L2 chain in the order they were received by the `OptimismPortal` contract.

```mermaid theme={null}
sequenceDiagram
    participant S as Sequencer
    participant U1 as User 1
    participant U2 as User 2
    participant OP as OptimismPortal Contract
    participant L2 as Layer 2

    Note over S: Sequencer goes offline
    U1->>OP: User 1 sends transaction 1 to OptimismPortal
    U2->>OP: User 2 sends transaction 2 to OptimismPortal
    Note over U1: User 1 waits 12 hours
    Note over U2: User 2 waits 12 hours
    OP->>L2: Transaction 1 included in L2 automatically
    OP->>L2: Transaction 2 included in L2 automatically
```

#### Partial sequencer outage

In this scenario we'll assume that the Sequencer is down for some period of time but comes back online before the `sequencer_window` has elapsed.
A user sends a transaction to the `OptimismPortal` during the downtime but the Sequencer comes back online and includes the transaction in an L2 block before the full `sequencer_window` ends.

```mermaid theme={null}
sequenceDiagram
    participant S as Sequencer
    participant U as User
    participant OP as OptimismPortal Contract
    participant L2 as Layer 2

    Note over S: Sequencer goes offline
    U->>OP: User sends transaction to OptimismPortal
    Note over U: User waits 1 hour
    Note over S: Sequencer comes back online after 1 hour
    S->>L2: Transaction included by Sequencer
```

#### Partial outage ordering

Here we'll again assume that the Sequencer is down for some period of time but comes back online before the `sequencer_window` has elapsed.
In this scenario, we'll observe the ability that the Sequencer has to include additional transactions in the L2 chain in between transactions sent to the `OptimismPortal` contract.

Here, even though the first user sends their transaction to the `OptimismPortal` contract before the second user sends their transaction to the Sequencer, the Sequencer is able to include the second user's transaction before the first user's transaction is included.
**Sequencers will typically choose to include transactions sent to the `OptimismPortal` contract before any other transactions but this is not guaranteed.**

```mermaid theme={null}
sequenceDiagram
    participant S as Sequencer
    participant U1 as User 1
    participant U2 as User 2
    participant OP as OptimismPortal Contract
    participant L2 as Layer 2

    Note over S: Sequencer goes offline
    U1->>OP: User 1 sends transaction 1 to OptimismPortal
    Note over U1: User waits 1 hour
    Note over S: Sequencer comes back online after 1 hour
    
    U2->>S: User 2 sends transaction 2 to Sequencer
    S->>L2: Transaction 2 included by Sequencer
    S->>L2: Transaction 1 included by Sequencer
```


# Rollup protocol overview
Source: https://docs.optimism.io/op-stack/protocol/overview

Learn how Optimistic Rollups work at a high level.

<NormativeSpec title="OP Stack specifications" href="https://specs.optimism.io/" />

The big idea that makes Optimism possible is the Optimistic Rollup.
We'll go through a brief explainer of *how* Optimistic Rollups work at a high level.
Then we'll explain *why* Optimism is built as an Optimistic Rollup and why we believe it's the best option for a system that addresses all of our design goals.
Check out the [protocol specs](https://specs.optimism.io/?utm_source=op-docs\&utm_medium=docs), if you want more details about the rollup protocol.

## Optimistic rollups TL;DR

Optimism is an "Optimistic Rollup," which is basically just a fancy way of describing a blockchain that piggy-backs off of the security of another "parent" blockchain.
Specifically, Optimistic Rollups leverage the consensus mechanism (like PoW or PoS) of their parent chain instead of providing their own. In OP Mainnet's case, this parent blockchain is Ethereum.

<img alt="Ethereum and Optimism Forever Doodle." />

## Block storage

In Bedrock, L2 blocks are saved to the Ethereum blockchain using a non-contract address ([`0xff00..0010` on Ethereum](https://etherscan.io/address/0xff00000000000000000000000000000000000010)) to minimize the L1 gas expense.
As these blocks are submitted as transactions using EIP-4844 [blobs](/chain-operators/guides/features/blobs), there is no way to modify or censor them after the "transaction" is included in a block that has enough attestations.
This is the way that OP Mainnet inherits the availability and integrity guarantees of Ethereum.

Blocks are written to L1 in [a compressed format](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#batch-submission-wire-format) to reduce costs.
This is important because writing to L1 is [the major cost of OP Mainnet transactions](/op-stack/transactions/fees).

## Block production

Optimism block production is primarily managed by a single party, called the "sequencer," which helps the network by providing the following services:

* Providing transaction confirmations and state updates.
* Constructing and executing L2 blocks.
* Submitting user transactions to L1.

In Bedrock, the sequencer does have a mempool, similar to L1 Ethereum, but the mempool is private to avoid opening opportunities for MEV.
In OP Mainnet, blocks are produced every two seconds, regardless of whether they are empty (no transactions), filled up to the block gas limit with transactions, or anything in between.

Transactions get to the sequencer in two ways:

1. Transactions submitted directly to the sequencer.
   These transactions are a lot cheaper to submit, as they do not require the expense of a separate L1 transaction. However, they cannot be made censorship resistant since the sequencer is the only participant that knows about them.

2. Transactions submitted on L1 (called *deposits*) are included in the chain in the appropriate L2 block.
   Every L2 block is identified by the "epoch" (the L1 block to which it corresponds, which typically has happened a few minutes before the L2 block) and its serial number within that epoch.
   The first block of the epoch includes all the deposits that happened in the L1 block to which it corresponds.
   If the sequencer attempts to ignore a legitimate L1 transaction, it ends up with a state that is inconsistent with the verifiers, same as if the sequencer tried to fake the state by other means.
   This mechanism ensures that transactions submitted on L1 benefit from Ethereum's censorship resistance, even if inclusion is delayed.
   You can read more about this mechanism [in the protocol specifications](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#deriving-the-transaction-list).

For the moment, [The Optimism Foundation](https://www.optimism.io/) runs the only block producer on OP Mainnet.

## Block execution

The execution engine (implemented as the `op-geth` component) receives blocks using two mechanisms:

1. The execution engine can update itself using a peer-to-peer network with other execution engines.
   This operates in the same way that the L1 execution clients synchronize the state across the network.
   You can read more about it [in the specs](https://specs.optimism.io/protocol/exec-engine.html?utm_source=op-docs\&utm_medium=docs#happy-path-sync).

2. The rollup node (implemented as the `op-node` component) derives the L2 blocks from L1.
   This mechanism is slower, but censorship resistant.
   You can read more about it [in the specs](https://specs.optimism.io/protocol/exec-engine.html?utm_source=op-docs\&utm_medium=docs#worst-case-sync).

## Bridging ETH or tokens between layers

Optimism is designed so that users can send arbitrary messages between smart contracts on L2 (OP Mainnet, OP Sepolia, etc.) and the underlying L1 (Ethereum mainnet, Sepolia, etc.).
This makes it possible to transfer ETH or tokens, including ERC20 tokens, between the two networks, and the Standard bridge uses this functionality to let users deposit tokens from Ethereum to OP Mainnet and withdraw them back again.
Transactions going from L1 to L2 are called *deposits*; they become part of the canonical chain in the first L2 block of the "epoch" corresponding to the L1 block where the deposit was made, usually a few minutes later.
Transactions going from L2 to L1 are called *withdrawals*; a withdrawal is initiated on L2, proven on L1 against an output root, and finalized on L1 only after the fault challenge period (a week on mainnet, less than that on the test network) has passed.
For the step-by-step mechanics of each direction, see [Deposit flow](/op-stack/bridging/deposit-flow) and [Withdrawal flow](/op-stack/bridging/withdrawal-flow); for using the Standard bridge from an application, see the [developer documentation and examples](/app-developers/guides/bridging/standard-bridge).

## Fault proofs

In an Optimistic Rollup, state commitments are published to L1 (Ethereum in the case of OP Mainnet) without any direct proof of the validity of these commitments.
Instead, these commitments are considered pending for a period of time (called the "challenge window").
If a proposed state commitment goes unchallenged for the duration of the challenge window (currently set to 7 days), then it is considered final.
Once a commitment is considered final, smart contracts on Ethereum can safely accept withdrawal proofs about the state of OP Mainnet based on that commitment.

When a state commitment is challenged, it can be invalidated through a "fault proof" ([formerly known as a "fraud proof"](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs)) process.
If the commitment is successfully challenged, then it is removed from the `StateCommitmentChain` to eventually be replaced by another proposed commitment.
It's important to note that a successful challenge does not roll back OP Mainnet itself, only the published commitments about the state of the chain.
The ordering of transactions and the state of OP Mainnet is unchanged by a fault proof challenge.

## Next steps

* If you want to learn more about rollup protocol, check out the guides on [deposit flow](/op-stack/bridging/deposit-flow), [withdrawal flow](/op-stack/bridging/withdrawal-flow), or [transaction flow](/op-stack/transactions/transaction-flow).
* To learn about operating your own L2 rollup, see the guide on [starting a self-hosted chain](/chain-operators/tutorials/create-l2-rollup) or go directly to the tutorial on [creating your own L2 rollup](/chain-operators/tutorials/create-l2-rollup).


# Privileged Roles in OP Stack Chains
Source: https://docs.optimism.io/op-stack/protocol/privileged-roles

Learn about the privileged roles in OP Stack chains.

<NormativeSpec title="Stage 1 roles and requirements specification" href="https://specs.optimism.io/protocol/stage-1.html" />

OP Stack chains follow a [Pragmatic Path to Decentralization](https://blog.oplabs.co/decentralization-roadmap/).
In their current state, OP Stack chains still include some "privileged" roles that give certain addresses the ability to carry out specific actions.
Members and users of the OP Stack ecosystem should be aware of these roles and their associated risks because they're shared across many OP Stack chains.
Read this page to understand these roles, why they exist, and what risks they pose.

## L1 Proxy Admin

The L1 Proxy Admin is an address that can be used to upgrade most OP Stack chains system contracts.

### Risks

* Compromised L1 Proxy Admin could upgrade contracts to malicious versions.
* Compromised L1 Proxy Admin could remove or lock ETH or tokens in the Standard Bridge.
* Compromised L1 Proxy Admin could fail to mitigate a risk as described on this page.

### Mitigations

* L1 Proxy Admin owner is a 2-of-2 [multisig](https://etherscan.io/address/0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A#readProxyContract). One owner is an Optimism Foundation 5/7 [multisig](https://etherscan.io/address/0x847B5c174615B1B7fDF770882256e2D3E95b9D92#readProxyContract) and the other owner is the [Security Council](https://gov.optimism.io/t/intro-to-optimisms-security-council/6885) [multisig](https://etherscan.io/address/0xc2819DC788505Aac350142A7A707BF9D03E3Bd03#readProxyContract).

### Addresses

* **Optimism Governed Chains on Ethereum**: [`0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A`](https://etherscan.io/address/0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A)
* **Optimism Governed Chains on Sepolia:** [`0x1Eb2fFc903729a0F03966B917003800b145F56E2`](https://sepolia.etherscan.io/address/0x1Eb2fFc903729a0F03966B917003800b145F56E2)

## L2 Proxy Admin

The L2 Proxy Admin is an address that can be used to upgrade most OP Stack chains system contracts on L2. The L2 Proxy Admin owner is the [aliased address](/op-stack/protocol/differences#address-aliasing) of the L1ProxyAdmin owner, which means the L2 ProxyAdmin Owner is equal to the L1 ProxyAdmin Owner, but due to aliasing it's a different address. Here's how that works:

* Given an L1 contract address, the aliased L2 address is equal to `L1_contract_address` + `0x1111000000000000000000000000000000001111`.
* Using `0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b` as an example, the `0x6B` address is the L2 address that's been aliased, so to figure out the original L1 address you calculate `0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b` - `0x1111000000000000000000000000000000001111`.
* That result gives an L1 contract address of `0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A`, which should be the 2/2 Safe owned by Foundation + Security Council that is L1 ProxyAdmin Owner.
* No one has the private key for `0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b` on OP Stack chains, which means the only way for the L2 ProxyAdmin owner to send transactions is via deposit transactions from the L1 `0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A` address.
* For help with the calculations, see the [`AddressAliasHelper` library](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/vendor/AddressAliasHelper.sol).

### Risks

* Compromised L2 Proxy Admin could upgrade contracts to malicious versions.
* Compromised L2 Proxy Admin could remove or lock ETH or tokens in the Standard Bridge.
* Compromised L2 Proxy Admin could fail to mitigate a risk as described on this page.

### Mitigations

* L2 Proxy Admin is controlled by the same L1 account as the [L1 Proxy Admin](#l1-proxy-admin). This is enabled by [address aliasing](/connect/resources/glossary#address-aliasing).

### Addresses

<Info>
  These addresses are controlled by the same L1 Proxy Admin addresses. Please read the descriptions above for more details.
</Info>

* **Optimism Governed Chains on Ethereum**: [`0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b`](https://explorer.optimism.io/address/0x6B1BAE59D09fCcbdDB6C6cceb07B7279367C4E3b)
* **Optimism Governed Chains on Sepolia:** [`0x2FC3ffc903729a0f03966b917003800B145F67F3`](https://testnet-explorer.optimism.io/address/0x2FC3ffc903729a0f03966b917003800B145F67F3)

## System Config Owner

The System Config Owner is an address that can be used to change the values within the [`SystemConfig`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/SystemConfig.sol) contract on Ethereum.

### Risks

* Compromised System Config Owner could cause a temporary network outage.
* Compromised System Config Owner could cause users to be overcharged for transactions.

### Mitigations

* System Config Owner is a 5-of-7 [multisig](https://etherscan.io/address/0x9BA6e03D8B90dE867373Db8cF1A58d2F7F006b3A#readProxyContract).
* System Config Owner may eventually be operated by a [Security Council](https://gov.optimism.io/t/intro-to-optimisms-security-council/6885).
* System Config Owner can be replaced by the [L1 Proxy Admin](#l1-proxy-admin).

### Addresses

The System Config owner is chain specific and you can see which addresses are configured in the [Superchain Registry](/op-stack/protocol/superchain-registry).

## Batcher

### Description

The Batcher is a software service that submits batches of transactions to Ethereum on behalf of the current OP Stack chains Sequencer.
OP Stack chains nodes will look for transactions from this address to find new batches of L2 transactions to process.

### Risks

* Batcher address is typically a hot wallet.
* Compromised batcher address can cause L2 reorgs or sequencer outages.

### Mitigations

* Compromised batcher address cannot publish invalid transactions.
* Compromised batcher address can be replaced by the [L1 Proxy Admin](#l1-proxy-admin).

### Addresses

The batcher address is chain specific and you can see which addresses are configured in the [Superchain Registry](/op-stack/protocol/superchain-registry).

## Proposer

### Description

The Proposer is a role that is allowed to create instances of the `PermissionedDisputeGame` dispute game type.
The `PermissionedDisputeGame` can be used as a fallback dispute game in the case that the `FaultDisputeGame` is found to include a critical security vulnerability.
The Guardian role is responsible for changing the respected dispute game type if necessary.

### Capabilities

* Can create instances of the `PermissionedDisputeGame` dispute game type.
* Can participate in the `PermissionedDisputeGame` dispute game process.

### Risks

* Proposer address is typically a hot wallet.
* Compromised proposer address could propose invalid state proposals.
* Invalid state proposals can be used to execute invalid withdrawals after 7 days.

### Mitigations

* Compromised proposer address can be replaced by the [L1 Proxy Admin](#l1-proxy-admin).
* Invalid state proposals can be challenged by the [Challenger](#challenger) within 7 days.

### Addresses

The proposer address is chain specific and you can see which addresses are configured in the [Superchain Registry](/op-stack/protocol/superchain-registry).

## Challenger

### Description

The Challenger is an address that can participate in and challenge `PermissionedDisputeGame` instances created by the [Proposer](#proposer) role. It is important to note that this is different from the [`op-challenger`](/op-stack/fault-proofs/challenger) services that challenges invalid output roots.

### Capabilities

* Can participate in the `PermissionedDisputeGame` dispute game process.

### Risks

* Compromised challenger could invalidate valid state proposals.
* Compromised challenger could fail to challenge invalid state proposals.

### Mitigations

* Compromised challenger address can be replaced by the [L1 Proxy Admin](#l1-proxy-admin).
* Challenges can be executed by replaced challenger address.

### Addresses

* **Optimism Governed Chains on Ethereum**: [`0x9BA6e03D8B90dE867373Db8cF1A58d2F7F006b3A`](https://etherscan.io/address/0x9BA6e03D8B90dE867373Db8cF1A58d2F7F006b3A)
* **Optimism Governed Chains on Sepolia**: [`0xfd1D2e729aE8eEe2E146c033bf4400fE75284301`](https://sepolia.etherscan.io/address/0xfd1D2e729aE8eEe2E146c033bf4400fE75284301)

## Guardian

### Description

The Guardian is an address that can be used to pause several system contracts on OP Stack chains.
This is a backup safety mechanism that allows for a temporary halt, particularly of withdrawal logic, in the event of a security concern.
The Guardian can also manage various aspects of the `OptimismPortal` contract to address active security concerns.

### Capabilities

* Pause several system contracts on OP Stack chains.
* Disable the ability for specific dispute game types from being used to execute withdrawals.
* Disable the ability for specific dispute game instances from being used to execute withdrawals.

### Risks

* Compromised guardian could pause withdrawals for 3 months, after which withdrawals are automatically unpaused.

### Mitigations

* Compromised guardian address can be replaced by the [L1 Proxy Admin](#l1-proxy-admin).
* Withdrawals can be unpaused by replaced guardian address.

### Addresses

* **Optimism Governed Chains on Ethereum**: [`0x09f7150D8c019BeF34450d6920f6B3608ceFdAf2`](https://etherscan.io/address/0x09f7150D8c019BeF34450d6920f6B3608ceFdAf2)
* **Optimism Governed Chains on Sepolia**: [`0xf64bc17485f0B4Ea5F06A96514182FC4cB561977`](https://sepolia.etherscan.io/address/0xf64bc17485f0B4Ea5F06A96514182FC4cB561977)

## Mint Manager Owner

The Mint Manager Owner is an address that controls the [`MintManager`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/governance/MintManager.sol) contract that can be used to mint new OP tokens on OP Stack chains.

### Risks

* Compromised Mint Manager Owner could mint arbitrary amounts of OP tokens.
* Compromised Mint Manager Owner could prevent OP tokens from being minted.

### Mitigations

* Mint Manager Owner is a 3-of-5 [multisig](https://explorer.optimism.io/address/0x2a82ae142b2e62cb7d10b55e323acb1cab663a26#readProxyContract).

### Addresses

* **Ethereum**: [`0x2a82ae142b2e62cb7d10b55e323acb1cab663a26`](https://explorer.optimism.io/address/0x2a82ae142b2e62cb7d10b55e323acb1cab663a26)
* **Sepolia**: [`0x5c4e7ba1e219e47948e6e3f55019a647ba501005`](https://explorer.optimism.io/address/0x5c4e7ba1e219e47948e6e3f55019a647ba501005)


# Smart Contract overview
Source: https://docs.optimism.io/op-stack/protocol/smart-contracts

Learn about the smart contracts that make up the OP Stack.

<NormativeSpec title="Optimism Overview specification" href="https://specs.optimism.io/protocol/overview.html#architecture-overview" />

The OP Stack's onchain logic lives in two groups of smart contracts: the
Layer 1 contracts deployed to Ethereum, and the Layer 2 predeploys that exist
in every OP Stack chain's genesis state. This page explains what each group
is for and routes you to the canonical definition of each contract. It does
not restate interfaces, parameters, or per-release versions:

* **Behavior** is defined in the [OP Stack specifications](https://specs.optimism.io/?utm_source=op-docs\&utm_medium=docs).
* **Source code** lives in [`packages/contracts-bedrock`](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock) in the monorepo, with generated interface documentation at [devdocs.optimism.io](https://devdocs.optimism.io/contracts-bedrock).
* **Deployed addresses** are on the [OP Mainnet addresses page](/op-mainnet/network-information/op-addresses), sourced from the [superchain-registry](https://github.com/ethereum-optimism/superchain-registry).

## Layer 1 contracts

The L1 contracts hold the chain's bridge liquidity, accept deposits, verify
withdrawals, store the chain's configuration, and adjudicate output proposals
through the fault proof system. The [Optimism Overview
specification](https://specs.optimism.io/protocol/overview.html?utm_source=op-docs\&utm_medium=docs#core-l1-smart-contracts)
includes an architecture diagram showing how they connect.

### Bridging and messaging

Deposits enter the chain and withdrawals leave it through a layered stack:
the `OptimismPortal` is the low-level deposit and withdrawal contract, the
`L1CrossDomainMessenger` adds replayable message passing on top of it, and
the token bridges sit on top of the messenger. Messages sent directly to the
`OptimismPortal` are not replayable, so users and app developers should
prefer the messenger or bridge interfaces.

| Contract                 | Role                                                                                                                 | Normative spec                                                                                                                                                                                                                                                                                                                                                                                             |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OptimismPortal`         | Low-level deposit entry point and withdrawal exit; withdrawals are proven and finalized against dispute game results | [Deposits](https://specs.optimism.io/protocol/deposits.html?utm_source=op-docs\&utm_medium=docs#deposit-contract), [Withdrawals](https://specs.optimism.io/protocol/withdrawals.html?utm_source=op-docs\&utm_medium=docs#the-optimism-portal-contract), [OptimismPortal fault proof integration](https://specs.optimism.io/fault-proof/stage-one/optimism-portal.html?utm_source=op-docs\&utm_medium=docs) |
| `ETHLockbox`             | Escrows the ETH deposited through authorized portals, so ETH liquidity can be managed and migrated as a unit         | [ETH Lockbox](https://specs.optimism.io/interop/eth-lockbox.html?utm_source=op-docs\&utm_medium=docs)                                                                                                                                                                                                                                                                                                      |
| `L1CrossDomainMessenger` | Replayable cross-domain message passing between L1 and L2; the recommended messaging interface                       | [Cross Domain Messengers](https://specs.optimism.io/protocol/messengers.html?utm_source=op-docs\&utm_medium=docs)                                                                                                                                                                                                                                                                                          |
| `L1StandardBridge`       | ETH and ERC-20 bridging built on the messenger; escrows L1-native tokens                                             | [Standard Bridges](https://specs.optimism.io/protocol/bridges.html?utm_source=op-docs\&utm_medium=docs)                                                                                                                                                                                                                                                                                                    |
| `L1ERC721Bridge`         | ERC-721 bridging built on the messenger; escrows L1-native NFTs                                                      | [Standard Bridges](https://specs.optimism.io/protocol/bridges.html?utm_source=op-docs\&utm_medium=docs)                                                                                                                                                                                                                                                                                                    |

<Info>
  The standard bridge is not intended to support every ERC-20 variant. Tokens
  with transfer fees, rebasing logic, or blocklists may not work correctly.
  See [Standard Bridge](/app-developers/guides/bridging/standard-bridge) for
  guidance.
</Info>

### Chain configuration

| Contract           | Role                                                                                                                                                   | Normative spec                                                                                                            |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| `SystemConfig`     | Per-chain configuration (batcher, gas, fee scalars) read by the derivation pipeline, plus the onchain registry of the chain's other contract addresses | [System Config](https://specs.optimism.io/protocol/system-config.html?utm_source=op-docs\&utm_medium=docs)                |
| `SuperchainConfig` | Superchain-wide configuration and the Guardian's pause mechanism; pauses are scoped by an identifier and expire automatically                          | [Superchain Configuration](https://specs.optimism.io/protocol/superchain-config.html?utm_source=op-docs\&utm_medium=docs) |

### Proposals and fault proofs

Claims about the L2 state are proposed and challenged permissionlessly
through dispute games rather than trusted output submission. See the [fault
proofs explainer](/op-stack/fault-proofs/explainer) for how the system works
end to end.

| Contract                  | Role                                                                                                                                           | Normative spec                                                                                                                                                         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DisputeGameFactory`      | Deploys and tracks dispute game instances; the entry point for proposing L2 state                                                              | [Dispute Game Interface](https://specs.optimism.io/fault-proof/stage-one/dispute-game-interface.html?utm_source=op-docs\&utm_medium=docs#disputegamefactory-interface) |
| `FaultDisputeGame`        | Adjudicates a claim about L2 state through a bisection game backed by an onchain fault proof VM                                                | [Fault Dispute Game](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html?utm_source=op-docs\&utm_medium=docs)                                      |
| `PermissionedDisputeGame` | A `FaultDisputeGame` variant restricting participation to a designated proposer and challenger; used where stricter access control is required | [Fault Dispute Game](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html?utm_source=op-docs\&utm_medium=docs)                                      |
| `AnchorStateRegistry`     | Tracks anchor states (recent, unchallenged starting points for new games) and the validity of game results                                     | [AnchorStateRegistry](https://specs.optimism.io/fault-proof/stage-one/anchor-state-registry.html?utm_source=op-docs\&utm_medium=docs)                                  |
| `DelayedWETH`             | Holds dispute bonds and delays payouts so bad resolutions can be caught before funds move                                                      | [Bond Incentives](https://specs.optimism.io/fault-proof/stage-one/bond-incentives.html?utm_source=op-docs\&utm_medium=docs#delayedweth)                                |
| `MIPS64`                  | Onchain fault proof VM: a big-endian, 64-bit, multithreaded MIPS emulator that executes a single disputed instruction step                     | [Cannon Fault Proof VM](https://specs.optimism.io/fault-proof/cannon-fault-proof-vm.html?utm_source=op-docs\&utm_medium=docs)                                          |
| `PreimageOracle`          | Serves the preimages of hashed inputs that the fault proof VM reads during a disputed step                                                     | [Pre-image Oracle](https://specs.optimism.io/fault-proof/index.html?utm_source=op-docs\&utm_medium=docs#pre-image-oracle)                                              |

### Legacy and deprecated contracts

* `AddressManager` is a legacy name-to-address registry from the pre-Bedrock
  system. It survives only because the `L1CrossDomainMessenger` still sits
  behind a legacy `ResolvedDelegateProxy` that resolves through it.
* `L2OutputOracle` was the trusted output proposal contract before fault
  proofs. It is deprecated: output proposals are made through the
  `DisputeGameFactory` instead, per the [L2 output root proposals
  specification](https://specs.optimism.io/protocol/proposals.html?utm_source=op-docs\&utm_medium=docs).
* `ProtocolVersions` signaled recommended and required protocol versions to
  node operators. The contract has been removed from the OP Stack contracts;
  the versioning scheme it exposed remains documented in the [Superchain
  Upgrades specification](https://specs.optimism.io/protocol/superchain-upgrades.html?utm_source=op-docs\&utm_medium=docs#protocol-version).

### Upgrading the contracts

L1 contracts are upgraded through the
[OP Contracts Manager (OPCM)](/chain-operators/reference/opcm), which deploys
and upgrades the L1 contracts as a versioned set. The
[superchain-ops](/chain-operators/tutorials/l1-contract-upgrades/superchain-ops-guide)
workflow drives OPCM under the hood and is the path for chains that require
Security Council signing; other chains can call OPCM directly. `op-deployer`
remains the tool for initial deployments, but its upgrade command is
deprecated in favor of OPCM; see the
[deprecation notice](/notices/archive/op-deployer-upgrade-deprecation).

L2 predeploys are upgraded through the L2 Contract Manager (L2CM),
introduced in [Upgrade 19](/notices/archive/upgrade-19). At a network upgrade, the
consensus layer emits a network upgrade transaction that has the L2
`ProxyAdmin` delegatecall the `L2ContractsManager` contract, which updates
every predeploy implementation in a single atomic transaction, replacing the
older practice of per-contract multisig transactions. See the
[L2 Contract Manager feature page](/op-stack/features/l2-contract-manager)
and the [L2 Upgrades specification](https://specs.optimism.io/protocol/l2-upgrades-1-execution.html?utm_source=op-docs\&utm_medium=docs).

### Contract releases

Contracts are released as tagged monorepo releases named
`op-contracts/vX.Y.Z`, following the documented
[versioning policy](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/book/src/policies/versioning.md).
This page does not track releases; use these sources instead:

* The [op-contracts release history](/releases/op-contracts) lists every
  release with its notes, generated from the GitHub releases.
* The [superchain-registry standard versions](https://github.com/ethereum-optimism/superchain-registry/tree/main/validation/standard)
  files record the exact contract versions and implementation addresses
  that make up each standard release.
* The [network upgrades registry](/op-stack/protocol/network-upgrades) maps
  each hardfork to its governance approval and required component versions.

<Warning>
  Releases tagged `v<semver>` without a component name (for example `v1.1.4`)
  are Go code releases and do not include smart contracts. Only deploy
  contracts from `op-contracts/vX.Y.Z` tags.
</Warning>

## Layer 2 contracts (predeploys)

Predeploys are contracts placed at fixed, well-known addresses in the genesis
state of every OP Stack chain. Unlike precompiles they are ordinary EVM
contracts, which keeps them portable across client implementations and
visible to standard tooling. Most live in the
`0x4200000000000000000000000000000000000xxx` address namespace and sit behind
proxies owned by the L2 `ProxyAdmin`.

The [Predeploys specification](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs)
is the canonical list: it maintains the full table of predeploy addresses,
the upgrade each was introduced in, deprecation status, and whether each is
proxied, along with the normative definition of each contract.

### Bridging predeploys

The L2 side mirrors the L1 bridging stack. The
[`L2CrossDomainMessenger`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#l2crossdomainmessenger)
is the recommended high-level messaging interface, the
[`L2ToL1MessagePasser`](https://specs.optimism.io/protocol/withdrawals.html?utm_source=op-docs\&utm_medium=docs#the-l2tol1messagepasser-contract)
records withdrawal messages whose inclusion is later proven on L1, and the
[`L2StandardBridge`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#l2standardbridge)
and `L2ERC721Bridge` pair with their L1 counterparts. The
[`OptimismMintableERC20Factory`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#optimismmintableerc20factory)
and `OptimismMintableERC721Factory` permissionlessly create the L2 token
contracts that the bridges mint and burn.

<Info>
  Do not bridge an ERC-721 that was originally deployed on an OP Stack chain
  through the ERC-721 bridge; it only supports NFTs originally deployed on
  L1.
</Info>

### Fee and system predeploys

* The [`GasPriceOracle`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#gaspriceoracle)
  exposes the parameters and helper functions for estimating the data
  availability portion of the transaction fee. The exact fee formula
  changes across upgrades and is defined in the spec, not here; see
  [transaction fees](/op-stack/transactions/fees) for the explanation.
* The [`L1Block`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#l1block)
  predeploy exposes information about the latest known L1 block, written by
  the protocol through a system deposit transaction.
* The fee vaults ([`SequencerFeeVault`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#sequencerfeevault),
  [`BaseFeeVault`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#basefeevault),
  [`L1FeeVault`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#l1feevault),
  and, since the Isthmus upgrade, the
  [`OperatorFeeVault`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#operator-fee-vault))
  collect the components of the transaction fee for withdrawal to
  configured recipients. See [fee vaults](/op-stack/transactions/fee-vaults)
  for operational details.
* The [`ProxyAdmin`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#proxyadmin)
  owns the proxies of the other predeploys and controls their upgrades.
* The [`BeaconBlockRoot`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#beacon-block-root)
  contract ([EIP-4788](https://eips.ethereum.org/EIPS/eip-4788)) exposes L1
  beacon block roots, available since the Ecotone upgrade.
* [`WETH9`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#weth9)
  is the standard Wrapped Ether contract at a deterministic address.

### GovernanceToken

The [`GovernanceToken`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#governance-token)
is the OP token used in Optimism governance, supporting voting and
delegation. It is owned by a `MintManager` contract that enforces the token
inflation schedule. See the [governance resources](/governance/resources)
for how the token is used.

### EAS (Ethereum Attestation Service)

The [`EAS`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#eas)
and [`SchemaRegistry`](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs#schemaregistry)
predeploys implement the [Ethereum Attestation Service](https://attest.sh/)
protocol, an open-source public good for issuing and managing onchain
attestations. You can interact with EAS through the
[EAS Scan UI](https://optimism.easscan.org/), the
[EAS SDK](https://docs.attest.sh/docs/developer-tools/eas-sdk), or
[directly onchain](https://github.com/ethereum-attestation-service/eas-contracts/blob/master/contracts/EAS.sol),
and index attestations with the
[EAS API](https://docs.attest.sh/docs/developer-tools/api) or the
[open source indexer](https://github.com/ethereum-attestation-service/eas-indexing-service).
See [attestations](/governance/eas-attestations) for how attestations are
used in Optimism governance.

### Deprecated predeploys

The `LegacyMessagePasser`, `DeployerWhitelist`, `LegacyERC20ETH`, and
`L1BlockNumber` contracts remain in state for backwards compatibility with
the pre-Bedrock system but are deprecated and unused. Their addresses and
history are in the
[Predeploys specification](https://specs.optimism.io/protocol/predeploys.html?utm_source=op-docs\&utm_medium=docs).

## Next steps

* Read the [Optimism Overview specification](https://specs.optimism.io/protocol/overview.html?utm_source=op-docs\&utm_medium=docs) for the architecture diagrams connecting these contracts.
* Browse the [contract source](https://github.com/ethereum-optimism/optimism/tree/develop/packages/contracts-bedrock) and the [generated contract reference](https://devdocs.optimism.io/contracts-bedrock).
* Look up [contract addresses on OP Mainnet](/op-mainnet/network-information/op-addresses).
* Learn how the [fault proof system](/op-stack/fault-proofs/explainer) uses the dispute contracts.


# The superchain-registry
Source: https://docs.optimism.io/op-stack/protocol/superchain-registry

Learn about OP Stack chain classification, what makes a chain standard, and the superchain-registry.

The [superchain-registry](https://github.com/ethereum-optimism/superchain-registry/tree/main) serves as the source of truth for OP Stack chain classification and what modifications chains have made. The superchain-registry introduces:

* A step-by-step process new chains can follow to join the registry
* Validation checks to ensure standard chains comply with the Standard Rollup Charter and non-standard chains pass baseline validation before joining the superchain-registry
* A repository that shows who's in the registry and each chain's configuration

The main benefit of joining the registry is a practical one: a registered chain's genesis and rollup configuration are baked into releases of the canonical OP Stack node software, including op-node and op-reth. Operators and node runners can start a node against a registered chain simply by passing its name to the client's network flag, with no need to hand-distribute configuration files. See [hard fork activation inheritance behavior](#hard-fork-activation-inheritance-behavior) below for the exact flags. Registration also lists your chain publicly alongside its configuration and signals reliability and alignment with the OP Stack ecosystem.

## What is a standard chain?

The standard configuration within the OP Stack ensures that chains deployed in the OP Stack ecosystem adhere to a consistent set of technical and governance parameters.
This standardization is critical for OP Stack interoperability, network security, and ease of upgrading your chain.
This configuration targets the highest bar for security, uptime, and decentralization in the OP Stack ecosystem.
For the parameter values themselves, consult the [OP Stack Configurability Specification](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs\&utm_medium=docs).

A standard chain in the OP Stack refers to a rollup that adheres to the following principles:

1. **Technical conformance:**
   * Compliance with the consensus parameters, policy parameters, admin roles, and service roles defined in the specifications.
     For more details, please see the [OP Stack Configurability Specification](https://specs.optimism.io/protocol/configurability.html?utm_source=op-docs\&utm_medium=docs).
   * Utilization of officially supported features and modules of the OP Stack.

2. **Governance alignment:**
   * Adherence to the [Standard Rollup Charter](/op-stack/protocol/blockspace-charter#the-standard-rollup-charter).
   * Transparent and collaborative decision-making aligned with the OP Stack ecosystem.

3. **Interoperability:**
   * Standard chains get Superchain interop by default: they can exchange cross-chain messages and assets with other standard chains under identical trust assumptions.

Chains that deviate from these principles, such as introducing unsupported features, are considered non-standard configurations.
For example, any alterations to core system contracts break standardization and aren't supported in the official OP Stack specification.
For a detailed list of standard configurations, refer to the [Standard Rollup Charter documentation](/op-stack/protocol/blockspace-charter).

## Why standardization matters

Standardization benefits the OP Stack ecosystem in several ways:

* **Interoperability:**
  A standard stack and security model gives your chain interop with other standard chains by default, such as single block cross-chain messaging and token transfers, with identical trust assumptions across all interoperating chains.

* **Simplified upgrade path:**
  Reduces the complexity of upgrading your chain to the latest version.

* **Reduced support overhead:**
  Minimizes the need for custom support by ensuring uniformity across deployments.

Two features define a standard chain in practice:

* **Default system contracts:**
  Core protocol contracts must use governance approved release implementations of the OP Stack to provide security and compatibility.

* **Specified sequencer configurations:**
  Sequencer settings must follow prescribed parameters for transaction ordering and submission to maintain network stability.

## Role of op-deployer in standardization

The [op-deployer](/chain-operators/tools/op-deployer/overview) is a tool designed to automate and streamline the deployment of standard configuration-compliant chains.
Key features include:

* **Default values:**
  op-deployer provides default values that adhere to standard specifications.

* **Ease of customization within standards:**
  The op-deployer tool allows for overriding default values. For example, you can override the L2 block time to 1s, which is standard. However, please ensure you know what you're doing when applying overrides because they may violate standard specifications.

By using op-deployer, chain operators can reduce the complexity of chain deployment while ensuring alignment with OP Stack standards.

<Info>
  We **strongly** recommend using the [op-deployer](/chain-operators/tools/op-deployer/overview) to deploy L1 contracts and generate the L2 genesis file that meets the configuration requirements outlined in the [Standard Rollup Charter](/op-stack/protocol/blockspace-charter).
</Info>

## Joining the Registry

To join the Registry, follow the [Join the Superchain Registry guide](/chain-operators/guides/join-superchain-registry) to submit a pull request and join the Registry. This guide will help you set up your chain, create your environment, and run all the validation checks needed to ensure your chain is ready to join the Registry.

## Hard fork activation inheritance behavior

After being included into the superchain-registry, subsequent releases of the `op-node` and `op-geth` will contain the chain's genesis and rollup configurations baked in. You can use then use the `--network` (`op-node`) and `--op-network` (`op-geth`) flags to start up your node with this information. Using these flags means that the node will automatically inherit the hard fork activation times from the superchain-registry, so you don't need to manually set them in your node configuration.

Additionally, chains can opt into the hard fork activation inheritance behavior by specifying the `superchain_time` in the chain's TOML file to start inheriting OP Stack wide activation timestamps.
Networks that utilize this mechanism will activate network hard forks specified in the `superchain.toml` files: [Sepolia superchain.toml](https://github.com/ethereum-optimism/superchain-registry/blob/main/superchain/configs/sepolia/superchain.toml) and [Mainnet superchain.toml](https://github.com/ethereum-optimism/superchain-registry/blob/main/superchain/configs/mainnet/superchain.toml).


# Glossary
Source: https://docs.optimism.io/op-stack/reference/glossary

Learn the meaning of important terminology used throughout the Optimism Developer Documentation.

The glossary provides definitions of important terminology used throughout the Optimism Developer Documentation. To make revisions to this page, please [submit an issue](https://github.com/ethereum-optimism/optimism/issues/new?assignees=\&labels=glossary%2Cdocumentation%2Ccommunity-request\&projects=\&template=suggest_glossary_term.yaml\&title=%5BGLOSSARY%5D+Add+PR+title).

## Table of contents

* [General Terms](#general-terms)
* [OP Profile & Identity](#op-profile--identity)
* [OP Stack & OP Chains](#op-stack--op-superchain)
* [Protocol](#protocol)

## General terms

### Address aliasing

When a contract submits a [deposit](#deposit) from L1 to L2, its address (as returned by `ORIGIN` and `CALLER`) will be
aliased with a modified representation of the address of a contract.

### Block

A sequential list of transactions, along with a couple of properties stored in the '''header''' of the block; can refer to an [L1](#layer-1-l1) block, or to an [L2](#layer-2-l2) block, which are structured similarly.
It is useful to distinguish between input block properties, which are known before executing the transactions in the
block, and output block properties, which are derived after executing the block's transactions (e.g., [Merkle Patricia Trie roots](#merkle-patricia-trie)).

### Block time

L2 block time is 2 seconds, meaning there is an L2 block at every 2s [time slot](#time-slot).
*Post-merge*, it could be said that L1 block time is 12s as that is the L1 [time slot](#time-slot). However, in
reality the block time is variable as some time slots might be skipped. Pre-merge, the L1 block time is variable, though it is on average 13s.

### Delegation

Refers to the process of assigning the voting power of your tokens to a designated community member, known as a delegate.
Delegates are individuals who have volunteered to actively participate in the governance of the Optimism Token House.
By delegating your voting power, you enable these delegates to vote on governance matters on your behalf, while you retain full ownership of your tokens and the freedom to use them as you wish.
You can also change your chosen delegate at any time, allowing for flexibility in how your voting power is represented in the governance process.

### EOA or externally owned account

Ethereum term to designate addresses operated by users, as opposed to contract addresses.

### Execution engine

Responsible for executing transactions in blocks and computing the resulting state roots,
receipts roots, and block hash. Both L1 (*post-merge*) and L2 have an execution engine. On L1, the executed blocks can
come from L1 block synchronization or from a block freshly minted by the execution engine (using transactions from the L1 mempool),
at the request of the L1 consensus layer. On L2, the executed blocks are freshly minted by the execution engine at the request of the
[rollup node](#rollup-node), using transactions [derived from L1 blocks](#l2-chain-derivation).

### Optimism collective

The Optimism Collective is a band of people, projects, and companies working together to build a better economy for everyone,
united by a mutually beneficial pact to adhere to the axiom of impact=profit — the principle that positive impact to the collective should be rewarded with profit to the individual.
New model of digital democratic governance optimized to drive rapid and sustained growth of a decentralized ecosystem.

### OP token

A governance token, referred to as "OP." Content should not discuss the token price or speculate on the price, and content that refers to OP incorrectly will be removed from Optimism platforms and will not be eligible for promotion.

### Layer 1 (L1)

Refers the Ethereum blockchain, used in contrast to [layer 2](#layer-2-l2), which refers to Optimism.

### Layer 2 (L2)

Refers to the Optimism blockchain and is used in contrast to [layer 1](#layer-1-l1), which refers to the Ethereum blockchain.

### L2 output root

32 byte value which serves as a commitment to the current state of the L2 chain.

### L2 output oracle contract

L1 contract to which [L2 output roots](#l2-output-root) are posted by the [sequencer](#sequencer).

### Predeployed contract

A contract placed in the L2 genesis state (i.e. at the start of the chain).

### PGA or priority gas auction

Transactions in ethereum are ordered by the price that the transaction pays to the miner. Priority Gas Auctions
(PGAs) occur when multiple parties are competing to be the first transaction in a block. Each party continuously
updates the gas price of their transaction. PGAs occur when there is value in submitting a transaction before other
parties (like being the first deposit or submitting a deposit before there is not more guaranteed gas remaining).
PGAs tend to have negative externalities on the network due to a large amount of transactions being submitted in a
very short amount of time.

### Receipt

The output generated by a transaction, comprising a status code, the amount of gas used, a list of log
entries, and a [bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) indexing these entries. Log entries are most notably used to encode Solidity events.
Receipts are not stored in blocks, but blocks store a [Merkle Patricia Trie root](#merkle-patricia-trie) for a tree containing the receipt
for every transaction in the block.

### Rollup Node

The node responsible for [deriving the L2 chain](#l2-chain-derivation) from the L1 chain (L1 [blocks](#block) and their
associated [receipts](#receipt). The rollup node can run either in *[validator](#validator-mode)* or *[sequencer](#sequencer-mode)* mode.

### Sequencer mode

The rollup node receives L2 transactions from users, which it uses to create L2 blocks. These are
then submitted to a [data availability provider](#data-availability-provider) via [batch submission](#batch-submission). The L2 chain
derivation then acts as a sanity check and a way to detect L1 chain re-orgs.

### Time slot

On L2, there is a block every 2 seconds (this duration is known as the [block time](#block-time)).
We say that there is a "time slot" every multiple of 2s after the timestamp of the [L2 genesis block](#l2-genesis-block).
On L1, post-merge, the time slots are every 12s. However, an L1 block may not be produced for every time slot, in case
of even benign consensus issues.

### Transaction Type

Ethereum provides a mechanism as described in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) for defining different transaction types.
Different transaction types can contain different payloads and be handled differently by the protocol.

### Validator

An entity (individual or organization) that runs a [rollup node](#rollup-node) in validator mode. Doing so grants a lot of benefits
similar to running an Ethereum node, such as the ability to simulate L2 transactions locally, without rate limiting. It also lets the
validator verify the work of the [sequencer](#sequencer), by re-deriving [output roots](#l2-output-root) and comparing them against those submitted by the sequencer.
In case of a mismatch, the validator can perform a [fault proof](#fault-proof).

### Validator mode

The rollup node performs derivation as indicated in sequencer mode, but is also able to "run ahead" of the L1
chain by getting blocks directly from the sequencer, in which case derivation serves to validate the sequencer's
behavior. A rollup node running in validator mode is sometimes called *a replica*.

\[[return to top](#table-of-contents)]

## OP profile & identity

### Attestations

Statements or evidence of information made by anyone about anything.

### Attestation recipient

The entity or individual that receives the [attestation](#attestations) from the attester.
In decentralized identity, the attestation recipient can be a service provider, website, or any other entity that requires verification of a person's identity or personal information.

### Attestation issuer

The entity or individual that performs the attestation process and issues the [attestation](#attestations).
In decentralized identity, the attestation issuer can be a government agency, financial institution, or any other trusted entity that is authorized to verify a person's identity or personal information.

### Attestation verifier

The entity or individual that verifies the [attestation](#attestations) and ensures that it is valid and accurate.
In decentralized identity, the attestation verifier can be a service provider, website, or any other entity that requires verification of a person's identity or personal information.

### Decentralized identity

A system that enables individuals to have greater control and ownership over their personal data and identity.
In decentralized identity, personal information is stored on a blockchain or other decentralized system, and individuals have the ability to grant or revoke access to their data as they see fit.
This allows for greater privacy, security, and control over personal information.

### Ethereum attestation service (EAS)

An Ethereum infrastructure public good for making attestations on or off-chain about anything.

### Sybil-resistance

A defense mechanism that prevents someone from creating multiple fake identities in a decentralized identity system.

### Web of trust

A decentralized model used to establish trust among participants in a network. It relies on the concept of participants vouching for the authenticity or trustworthiness of other participants. In a web of trust, trust is built through the accumulation of attestations from trusted individuals.

\[[return to top](#table-of-contents)]

## OP Stack & OP Chains

### Attestation-based fault proof

A fault proof where challenges can be successfully made by supplying an [attestation proof](#attestation-proof) which disagrees with the original withdrawal claim.

### Attestation-based validity proof

A validity proof which can be verified by supplying an [attestation proof](#attestation-proof) which agrees with the withdrawal claim.

### Attestation proof

A proof which consists of some number of signatures from a pre-agreed upon set of chain attestors.

### Cannon fault proof

A fault proof where challenges are evaluated using an onchain game which is guaranteed to result in a truthful outcome, given economic rationality assumptions.

### Chain

A state [transition system](https://en.wikipedia.org/wiki/Transition_system) consisting of an initial state, a state transition function, and a list of inputs (transactions)—which is cryptographically committed to and can be independently replicated with commodity computer hardware and internet connection.

### Chain proof

Difficult to forge evidence of the validity of a particular withdrawal claim. Proofs are commonly used to enable chains to communicate with each other.

### Challenge period

The window of time in which a challenge can be made to disprove a fault proof.

### Fault proof

A proof which relies on the absence of counter-evidence to prove correctness.

### L1 origin

the L1 origin of an L2 block is the L1 block corresponding to its [sequencing epoch](#sequencing-epoch).

### Merkle patricia trie

sparse [trie](https://en.wikipedia.org/wiki/Trie), which is a tree-like structure that maps keys to values.
The root hash of a MPT is a commitment to the contents of the tree, which allows a proof to be constructed for any key-value mapping encoded in the tree. Such a proof is called a Merkle proof, and can be
verified against the Merkle root.

### Modular proof

The ability to use multiple proof systems for the same OP Chain. For instance, it should be possible to prove an OP Chain using a fault proof or a validity proof.

### Modular sequencing

The ability to configure the sequencer address during OP Chain deployment. This value can be configured by the OP Chain deployer.

### OP Chain

An individual chain within the OP Stack ecosystem. All chains, regardless of their specific properties are considered OP Chains if they are officially governed by the Optimism Collective.

### OP Mainnet

Layer 2 blockchain powered by the OP Stack. Previously known as just "Optimism," OP Mainnet is where it all started, and the first chain on the OP Stack.

### OP Stack

the modular, open source, MIT-licensed development stack that powers the OP Mainnet, OP Chains, and the OP Stack ecosystem. The OP Stack is maintained by the Optimism Collective.

### OP Stack Fork

Layer 2 blockchain that has been built using the MIT-licensed OP Stack, but is not governed by Optimism's governance or contributing sequencer revenue back to the Collective. This means OP Stack Forks won't necessarily share security or interoperability with OP Chains in the OP Stack ecosystem.

### Alt-DA Chain

A chain where transaction data is committed to on L1 but not supplied to L1 directly, with a data availability challenge fallback.

### Rollup Chain

A chain where all transaction data is submitted to L1.

### Rollup transactions

Rollup transactions can be included in two ways: through a [deposited transaction](#deposited-transaction) enforced by the system and through a regular transaction embedded in a [sequencer batch](#sequencer-batch).
Submitting transactions for inclusion in a batch saves costs by reducing overhead, and enables the sequencer to
pre-confirm the transactions before the L1 confirms the data.

### Sequencer

The specific entity or smart contract which has priority when submitting transactions to an OP Chain, can be either a [rollup node](#rollup-node) run in sequencer mode or the operator of this rollup node.
The sequencer receives L2 transactions from L2 users, creates L2 blocks using them, which it then submits to [data availability provider](#data-availability-provider) (via a [batcher](#batcher)).
It also submits [output roots](#l2-output-root) to L1.

### Sequencing Window

Range of L1 blocks from which a [sequencing epoch](#sequencing-epoch) can be derived.
A sequencing window whose first L1 block has number `N` contains [batcher transactions](#batcher-transaction) for epoch
`N`. The window contains blocks `(N, N + SWS)` where `SWS` is the sequencer window size.
The current default `SWS` is 3600 epochs.
Additionally, the first block in the window defines the [depositing transactions](#depositing-transaction) which determine the
[deposits](#deposit) to be included in the first L2 block of the epoch.

### Sequencing Epoch

sequential range of L2 blocks derived from a [sequencing window](#sequencing-window) of L1 blocks.
Each epoch is identified by an epoch number, which is equal to the block number of the first L1 block in the
sequencing window. Epochs can have variable size, subject to some constraints.

### OP Stack interop cluster

The network of OP Stack chains connected by native interoperability. Not yet live. Chains that are part of the OP Stack ecosystem share security and a common development stack (the OP Stack). The interop cluster specifically refers to the subset of chains connected by the OP Stack interoperability layer.

### Dependency set

The set of chains that a given chain accepts initiating messages from. A chain's local block cannot become safe until every initiating message it depends on has also been derived from L1. The *transitive* dependency set extends this to the dependencies of those chains, and so on. The [OP Stack interop cluster](#op-stack-interop-cluster) is configured as a fully-connected dependency set: every chain in the set has every other chain in its dependency set.

### Supernode

A component that runs the consensus layer of every chain in a [dependency set](#dependency-set) together as in-memory [virtual nodes](#virtual-node) inside one binary. The supernode shares the L1 client, L1 beacon client, JSON-RPC surface, and metrics across chains, and verifies that every cross-chain message a chain depends on has been reproduced from L1 before promoting blocks to "safe". It connects to an execution client for each chain using the engine API. Often referred to as `op-supernode` after the binary name. See the [supernode explainer](/op-stack/interop/supernode) for the architecture.

### Chain container

The [supernode](#supernode)'s wrapper around a single chain. A chain container hosts one [virtual node](#virtual-node), drives that chain's execution engine via an engine controller, and exposes a stable interface the rest of the supernode uses to derive blocks, fetch receipts, and answer output-root queries.

### Virtual node

A consensus-layer node hosted in-process inside a [supernode](#supernode), rather than as a separate operating-system process. Today the only virtual node implementation is op-node itself, hosted as a library.

### Super root

A commitment over verified L2 blocks across a [dependency set](#dependency-set) at a given timestamp. Produced by the supernode's `superroot_atTimestamp` RPC and consumed by the fault proof system as the input it needs to generate an interop-aware proof.

### Light CL

A mode of operation for the consensus layer (op-node or kona-node) that turns off local L1-to-L2 derivation and mirrors safe and finalized state from a trusted external source over the `optimism_syncStatus` RPC. A light CL still advances the unsafe chain over P2P. Pairs with a [supernode](#supernode) acting as the safe source for a fleet of light CLs.
Learn more at the [Light Node Topology Notice Page](/notices/specialized-node-topology).

### Shared L1 Bridge

The L1 bridge contracts which govern all OP Chains in the OP Stack ecosystem. This bridge can be upgraded by the Optimism Collective.

### Validity Proof

A proof of a withdrawal claim which can be immediately validated, without a challenge period.

### Withdrawal Claim

A claim about the state of one chain made on another chain. For instance, I can claim that in OP Mainnet I have burned my tokens with the intent to withdraw those tokens back to L1.

### Zero Knowledge Proof

A validity proof which relies on cryptographic properties and low error margins.

\[[return to top](#table-of-contents)]

## Protocol

### Batcher

Software component (independent program) that is responsible to make channels available on a data
availability provider. The batcher communicates with the rollup node in order to retrieve the channels. The channels are
then made available using [batcher transactions](#batcher-transaction).

### Batcher Transaction

Transaction submitted by a [batcher](#batcher) to a data availability provider, in order to make
channels available. These transactions carry one or more full frames, which may belong to different channels. A
channel's frame may be split between multiple batcher transactions. When submitted to Ethereum calldata, the batcher
transaction's receiver must be the sequencer inbox address. The transaction must also be signed by a recognized batch submitter account.

### Channel

Sequence of [sequencer batches](#sequencer-batch) (for sequential blocks) compressed together; uniquely identified by its timestamp
(UNIX time at which the channel was created) and a random value. The reason to group multiple batches together is simply to obtain
a better compression rate, hence reducing data availability costs.

* A channel can be split in [frames](#channel-frame) in order to be transmitted via [batcher transactions](#batcher-transaction). The reason to split a channel
  into frames is that a channel might be too large to include in a single batcher transaction.
* On the side of the [rollup node](#rollup-node) (which is the consumer of channels), a channel is considered to be
  *opened* if its final frame (explicitly marked as such) has not been read, or closed otherwise.

### Channel Frame

Chunk of data belonging to a [channel](#channel). [Batcher transactions](#batcher-transaction) carry one or
multiple frames. The reason to split a channel into frames is that a channel might be too large to include in a single
batcher transaction.

### Channel Timeout

Duration (in L1 blocks) during which [channel frames](#channel-frame) may land on L1 within
[batcher transactions](#batcher-transaction). The acceptable time range for the frames of a [channel](#channel) is `[channel_id.timestamp, channel_id.timestamp +
CHANNEL_TIMEOUT]`. The acceptable L1 block range for these frames are any L1 block whose timestamp falls inside this
time range. (Note that `channel_id.timestamp` must be lower than the L1 block timestamp of any L1 block in which frames
of the channel are seen, or else these frames are ignored.)

<Info>
  The purpose of channel timeouts is dual:

  * Avoid keeping old unclosed channel data around forever (an unclosed channel is a channel whose final frame was not
    sent).
  * Bound the number of L1 blocks we have to look back in order to decode [sequencer batches](#sequencer-batch) from
    channels. This is particularly relevant during L1 re-orgs.
</Info>

### Data Availability

Guarantee that some data will be "available" (i.e. *retrievable*) during a reasonably long time
window. In Optimism's case, the data in question are [sequencer batches](#sequencer-batch) that [validators](#validator)
need in order to verify the sequencer's work and validate the L2 chain. The [finalization period](#finalization-period)
should be taken as the lower bound on the availability window, since that is when data availability is the most crucial,
as it is needed to perform a [fault proof](#fault-proof). "Availability" **does not** mean guaranteed long-term storage of the data.

### Data Availability Provider

Service that can be used to make [data available](#data-availability). Ideally, a good data availability provider provides strong *verifiable* guarantees
of data availability, such as Ethereum call data and EIP4844.

### Deposit

L2 transaction derived from an L1 block (by the rollup driver). While transaction deposits are notably (but not only) used to "deposit" (bridge) ETH and tokens to L2, the word
*deposit* should be understood as "a transaction *deposited* to L2 from L1".

### Deposit contract

L1 contract to which [EOAs](#eoa-or-externally-owned-account) and contracts may send deposits. The deposits are
emitted as log records (in Solidity, these are called *events*) for consumption by [rollup nodes](#rollup-node).

<Info>
  The deposits are not stored in calldata because they can be sent by contracts, in which case the calldata
  is part of the *internal* execution between contracts, and this intermediate calldata is not captured in one of the
  [Merkle Patricia Trie roots](#merkle-patricia-trie) included in the L1 block.
</Info>

### Deposited Transaction

L2 transaction that was derived from L1 and included in a L2 block. There are two kinds of deposited transactions:
L1 attributes deposited transaction (submits the L1 block's attributes to the L1 Attributes Predeployed Contract) and User deposited transactions
(transactions derived from an L1 call to the deposit contract).

### Depositor

L1 address (contract or \[EOA]) that makes (is the `msg.sender` of) the [depositing
call](#depositing-call). The *depositor* is **NOT** the originator of the [depositing transaction](#depositing-transaction) (i.e. `tx.origin`).

### Depositing Call

L1 call to the deposit contract, which will be derived to a [user-deposited transaction](#user-deposited-transaction) by the rollup driver.
This call specifies all the data (destination, value, calldata, ...) for the deposited transaction.

### Depositing Transaction

L1 transaction that makes one or more [depositing calls](#depositing-call).

### Deposited transaction type

EIP-2718 transaction type, which specifies the input fields and correct handling of a deposited transaction.

### Event or log data

Data generated by the [depositing call](#depositing-call) and read by the rollup driver to derive the [deposited transaction](#deposited-transaction).

### Finalized L2 Head

Highest L2 block that can be derived from *finalized* L1 blocks — i.e. L1
blocks older than two L1 epochs (64 L1 [time slots](#time-slot)).

### Finalization Period

The minimum amount of time (in seconds) that must elapse before a withdrawal can be finalized, sometimes called **withdrawal delay**.
The finalization period is necessary to afford sufficient time for validators to make a fault proof.

### L1 Attributes Deposited Transaction

A [deposited transaction](#deposited-transaction) that is used to register the L1 block
attributes (number, timestamp, ...) on L2 via a call to the [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract).
That contract can then be used to read the attributes of the L1 block corresponding to the current L2 block.

### L1 Attributes Predeployed Contract

A [predeployed contract](#predeployed-contract) on L2 that can be used to retrieve the L1 block attributes of L1 blocks with a given
block number or a given block hash.

### L2 Chain Derivation

The process that reads [L2 derivation inputs](#l2-derivation-inputs) from L1 in order to derive the L2
chain.

### L2 Chain Inception

L1 block number at which the output roots for the [genesis block](#l2-genesis-block) were proposed on the [output
oracle](#l2-output-oracle-contract) contract. In the current implementation, this is the L1 block number at which the output oracle contract was deployed or upgraded.

### L2 Derivation Inputs

Data that is found in L1 blocks and is read by the [rollup node](#rollup-node) to construct [payload
attributes](#payload-attributes). L2 derivation inputs include: L1 block attributes (block number, timestamp, basefee), deposits (as log data),
sequencer batches (as transaction data), and system configuration updates (as log data).

### Payload Attributes

Object that can be derived from [L2 chain derivation inputs](#l2-derivation-inputs) found on L1, which are
then passed to the [execution engine](#execution-engine) to construct L2 blocks. The payload attributes object essentially
encodes a [block](#block) without output properties.

### Relayer

EOA on L1 which finalizes a withdrawal by submitting the data necessary to verify its inclusion on L2.

### Safe L2 Block

L2 block that can be derived entirely from L1 by a [rollup node](#rollup-node). This can vary
between different nodes, based on their view of the L1 chain.

### Safe L2 Head

Highest [safe L2 block](#safe-l2-block) that a [rollup node](#rollup-node) knows about.

### Sequencer Batch

A list of L2 transactions (that were submitted to a sequencer) tagged with an [epoch
number](#sequencing-epoch) and an L2 block timestamp (which can trivially be converted to a block number, given our
block time is constant). Sequencer batches are part of the [L2 derivation inputs](#l2-derivation-inputs). Each batch represents the inputs needed to build
**one** L2 block (given the existing L2 chain state) — except for the first block of each epoch, which also needs
information about deposits (cf. the section on [L2 derivation inputs](#l2-derivation-inputs)).

### System Configuration

Collection of dynamically configurable rollup parameters maintained
by the [`SystemConfig`](https://github.com/ethereum-optimism/optimism/blob/v1.1.4/packages/contracts-bedrock/src/L1/SystemConfig.sol) (as of `v1.1.4`) contract on L1 and read by the L2 [derivation](#l2-chain-derivation) process.
These parameters enable keys to be rotated regularly and external cost parameters to be adjusted
without the network upgrade overhead of a hardfork.

### Unsafe L2 Block

L2 block that a [rollup node](#rollup-node) knows about, but which was not derived from the L1
chain. In sequencer mode, this will be a block sequenced by the sequencer itself. In validator mode, this will be a
block acquired from the sequencer via [unsafe sync](#unsafe-sync).

### Unsafe L2 Head

Highest [unsafe L2 block](#unsafe-l2-block) that a [rollup node](#rollup-node) knows about.

### Unsafe Block Consolidation

Process through which the [rollup node](#rollup-node) attempts to move the [safe L2
head](#safe-l2-head) a block forward, so that the oldest [unsafe L2 block](#unsafe-l2-block) becomes the new safe L2 head. In order to perform consolidation,
the node verifies that the [payload attributes](#payload-attributes) derived from the L1 chain match the oldest unsafe L2 block exactly.

### Unsafe Sync

Process through which a [validator](#validator) learns about [unsafe L2 blocks](#unsafe-l2-block) from
the [sequencer](#sequencer). These unsafe blocks will later need to be confirmed by the L1 chain (via [unsafe block consolidation](#unsafe-block-consolidation)).

### User-Deposited Transaction

Deposited transaction which is derived from an L1 call to the deposit contract and [depositing call](#depositing-call); explicitly excludes [L1 attributes deposited
transactions](#l1-attributes-depositedtransaction).

### Withdrawal transaction

Sent from L2 to L1 that may transfer data and/or value; these "transactions" exist at multiple levels (see withdrawal initiating transaction and withdrawal finalizing transaction for details).

### Withdrawal initiating transaction

A specific transaction on L2 sent to the Withdrawals predeploy.

### Withdrawal finalizing transaction

A specific L1 transaction which finalizes and relays the withdrawal.

\[[return to top](#table-of-contents)]


# Block time research
Source: https://docs.optimism.io/op-stack/research/block-time-research

Sunnyside Labs' (formerly Test in Prod) and OP Labs 1 second block time research.

Sunnyside Labs (formerly Test in Prod) and OP Labs have researched whether we can drop OP Chains' block time to one second.

To validate if dropping the block time is safe, we should check if nodes can build a block under a second when the block spends maximum gas in the production environment–i.e., block building time should take less than one second when the block spends maximum gas. We benchmarked the block-building time of every block at Base and grouped the data in various gas ranges using multiple clients–op-geth & op-reth.

## Method and raw data

This [GitHub repository](https://github.com/testinprod-io/block-building-stats/tree/main) contains the test methods, data sets, client versions, and raw data.

The following benchmarks are available in this [notebook](https://github.com/testinprod-io/block-building-stats/blob/main/stats.ipynb).

## Benchmarks

| <img alt="Figure 1: op-geth / archive node / block 5492540 ~ 9816497." /> |
| :-----------------------------------------------------------------------: |
|      **Figure 1**: op-geth / archive node / block 5492540 \~ 9816497      |

| <img alt="Figure 2: op-geth / full node / block 5492540 ~ 9816497." /> |
| :--------------------------------------------------------------------: |
|      **Figure 2**: op-geth / full node / block 5492540 \~ 9816497      |

Figures 1 and 2 show the Base nodes' block-building time distribution with op-geth archive node & full node from block 5492540 to 9816497. We can see that the average block building time takes 0.58 and 0.36 seconds each for blocks that spent 25M \~ 30M gas, which is less than one second.

| <img alt="Figure 3: op-reth / archive node / block 5492540 ~ 9816497." /> |
| :-----------------------------------------------------------------------: |
|      **Figure 3**: op-reth / archive node / block 5492540 \~ 9816497      |

Figure 3 shows the Base nodes' block-building time distribution using the op-reth archive node from block 5492540 to 9816497. Compared to op-geth's archive node, we can see that op-reth shows a better performance in all ranges.

| <img alt="Figure 4: op-geth / archive node / block 13686867 ~ 15074141." /> |
| :-------------------------------------------------------------------------: |
|      **Figure 4:** op-geth / archive node / block 13686867 \~ 15074141      |

| <img alt="Figure 5: op-geth / full node / block 14567037 ~ 15074141." /> |
| :----------------------------------------------------------------------: |
|      **Figure 5:** op-geth / full node / block 14567037 \~ 15074141      |

Throughout the research, we found that the node meaningfully takes longer to build a block as the chain stores more states and transactions to access more historical data. Therefore, we benchmarked the latest blocks in Figures 4 and 5. On average, both the full node and archive node could build a congested block on time. It is worth noting that the average block-building time of high gas spending range is similar to the older blocks, but the average block-building time is higher on the newer blocks.

| <img alt="Figure 6: op-geth / archive node / block 13686867 ~ 15074141 / histogram of 25m~30m gas range." /> |
| :----------------------------------------------------------------------------------------------------------: |
|      **Figure 6**: op-geth / archive node / block 13686867 \~ 15074141 / histogram of 25m\~30m gas range     |

If we zoom in on the 25m\~30m gas range of the archive node, the average could be potentially concerning–0.51 sec. It is worth noting that we can see the average is diverged from p50 (0.4 sec) because of outliers in the histogram (Figure 6), and p50 is a more important metric than the average for the block progression (Sequencer) because of its asynchronous nature.

When the sequencer seals the block after the block time, it stops to include the transactions and yields the current processing transactions to the next block. Therefore, the sequencer can include most transactions that took less than one second in the block on time and include outliers in the next block. Therefore, we can expect the system to be able to build blocks in one second in most cases, even in the highest gas range (25m\~30m gas).

As a result, we can learn that nodes can build the latest blocks of Base Mainnet with the highest level of production loads in one second with an [i3en.3xlarge instance](https://aws.amazon.com/ec2/instance-types/i3en/) (or similar specs).

## Expected impacts

### Verifier

* Sync from genesis: If OP Chains' block time drops to one second, verifiers may need longer to sync the chain from the genesis with L1 derivation. However, we expect it won't be a notable issue for verifiers as OP Stack supports the [engine sync](/node-operators/reference/consensus-layer-sync).
* Following the tip: The research suggests that verifiers are less likely to have a problem following the tip because nodes could build a block under one second at the highest gas range, especially since most verifiers are full nodes.

### Sequencer

* Block progression: As the previous paragraph mentioned, the data suggests we don't expect problems on a shorter block time.

## Limitation

The data suggests we don't expect a problem dropping the block time to one second for now, as the average block building time of the latest blocks takes 0.19 seconds for the Base Mainnet. One concerning point: the benchmark shows that it takes longer to build a block as the chain progresses. When the chain stores more states over time and usage surges to a peak like 2017 Ethereum, we might need performance patches then.

However, it is also worth noting that the research assumes that the Base Mainnet handles 2x of their current traffic–dropping the block time to half but still spending gas as current (when it runs two seconds of block time). Plus, the Base Mainnet's average block gas spending is 10M. To make all blocks reach the highest gas level that this research focuses on (25M), it's another 2.5x.

Therefore, this research assumes the chain processes approximately 5x traffic compared to the current Base Mainnet (2x in block time \* 2.5x in gas spending).

## Reference

Base's prior research for raising gas limit: [replayor](https://github.com/danyalprout/replayor)


# Audit reports
Source: https://docs.optimism.io/op-stack/security/audit-reports

A comprehensive list of security reviews for the OP Stack, including links to detailed audit reports and descriptions of their scope.

Security is a top priority for the OP Stack.
Below, you'll find a comprehensive list of past audits conducted on various components of the OP Stack ecosystem.
Each report includes the scope, focus, and a link to the full audit documentation.
These reviews ensure that the system is secure and reliable for all users.

Find all security audits conducted to date [in the monorepo](https://github.com/ethereum-optimism/optimism/tree/develop/docs/security-reviews#security-reviews).


# OP Stack security model
Source: https://docs.optimism.io/op-stack/security/faq-sec-model

Learn about the OP Stack security model and answers to common questions.

Many OP Stack chains, such as OP Mainnet, are a work in progress.
Constant, iterative improvement of the security mechanisms that safeguard OP Stack users is a top priority for [Optimism](/governance/evolution-and-experimentation).
Optimism strives to be clear and transparent about the security of OP Stack chains and the OP Stack as a whole.

## Bottom line

The security model of any blockchain system is only as strong as its lowest common denominator.
At the moment, **it's important to understand that the security of OP Stack chains is dependent on a [multisig](https://etherscan.io/address/0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A)** managed jointly by the [Optimism Security Council](https://gov.optimism.io/t/intro-to-optimisms-security-council/6885) and the Optimism Foundation.
OP Stack chains **may also contain unknown bugs that could lead to the loss of some or all of the ETH or tokens held within the system**.

## OP Stack multisig

The security of OP Stack chains is currently dependent on a multisig managed jointly by the [Optimism Security Council](https://gov.optimism.io/t/intro-to-optimisms-security-council/6885) and the Optimism Foundation.
This multisig is a [2-of-2 nested multisig](https://etherscan.io/address/0x5a0Aae59D09fccBdDb6C6CcEB07B7279367C3d2A) which is in turn governed by a [10-of-13 multisig](https://etherscan.io/address/0xc2819DC788505Aac350142A7A707BF9D03E3Bd03) managed by the Optimism Security Council and a [5-of-7 multisig](https://etherscan.io/address/0x847B5c174615B1B7fDF770882256e2D3E95b9D92) managed by the Optimism Foundation.

This multisig can be used to upgrade core OP Stack smart contracts **without upgrade delays** to allow for quick responses to potential security concerns.
All upgrades to the OP Stack system must be approved by both component multisigs and either can veto an upgrade.

## Fault proofs

<Info>
  It is important to understand that **fault proofs are not a silver bullet** and that **fault proofs provide limited improvements to the security of a system if the system still has a multisig or security council that can instantly upgrade the system**.
  OP Stack chains are following a multi-client and multi-proof approach designed to eventually remove the need for instant upgrades entirely.
</Info>

Users can withdraw ETH and tokens from OP Stack chains to Ethereum by submitting a withdrawal proof that shows the withdrawal was actually included inside of the OP Stack chain.
Withdrawals are proven against proposals about the state of the chain that are published through the [`DisputeGameFactory`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/DisputeGameFactory.sol) contract.

Proposals can be submitted to the `DisputeGameFactory` contract by any user and submissions do not require any special permissions.
Each submitted proposal creates a [`FaultDisputeGame`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/dispute/FaultDisputeGame.sol) contract that allows any other user to challenge the validity of a proposal by participating in a "fault proof" process.
A more detailed explanation of the fault proof game can be found in the [Fault Proofs Explainer](/op-stack/fault-proofs/explainer).

Although the fault proof game is permissionless, the Optimism Security Council acting as the [Guardian](/op-stack/protocol/privileged-roles#guardian) role provides a backstop in case of a failure in the fault proof game.

Each proposal must wait for a delay period during which the Guardian can prevent invalid proposals from being used to withdraw ETH or tokens through a number of safety hatches.
The Guardian can also choose to shift the system to use a `PermissionedDisputeGame` in which only specific `PROPOSER` and `CHALLENGER` roles can submit and challenge proposals.

## Bugs and unknowns

Please also keep in mind that just like any other system, **the Optimism codebase may contain unknown bugs** that could lead to the loss of some or all of the ETH or tokens held within the system.
The OP Stack has been audited [on many occasions](https://github.com/ethereum-optimism/optimism/tree/v1.1.4/technical-documents/security-reviews) (as of `v1.1.4`), but **audits are not a stamp of approval** and **a completed audit does not mean that the audited codebase is free of bugs.**

It's important to understand that using OP Stack chains inherently exposes you to the risk of bugs within the Optimism codebase, and that you use these chains at your own risk.

## Work in progress

### Sequencer decentralization

The Optimism Foundation currently operates the sole sequencer on OP Stack chains.
Although users can always bypass the Sequencer by sending transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol) contract, sequencer decentralization can still help mitigate the effect of short-term outages for users.

## Security model FAQ

### Do OP Stack chains have fault proofs?

**Yes**, fault proofs are available to OP Stack chains.
It is important to note that **fault proofs are not a silver bullet** and that **fault proofs provide limited improvements to the security of a system if the system still has a multisig or security council that can instantly upgrade the system**.
A system with fast upgrade keys, such as OP Mainnet, is fully dependent on the upgrade keys for security.
The goal is to be the first system that deploys fault proofs that can secure the system by themselves, without fast upgrade keys.

### How is Optimism planning to remove the multisig?

Check out Optimism's detailed [Pragmatic Path to Decentralization](https://web.archive.org/web/20230331065342/https://medium.com/ethereum-optimism/our-pragmatic-path-to-decentralization-cb5805ca43c1) post for a detailed view into how the multisig may be removed in a way that makes OP Stack chains the first with true fault proof security.

### How can I help make OP Stack chains more secure?

[OP Stack has one of the biggest bug bounties (ever)](/op-stack/security/security-policy).
You can earn up to \$2,000,042 by finding critical bugs in the Optimism codebase.
You can also run your own verifier node to detect network faults.

### Where do I report bugs?

For details about reporting vulnerabilities and available bug bounty programs, see the [Security Policy](/op-stack/security/security-policy).

### Is every OP Stack chain safe?

The security model of an OP Stack based blockchain depends on the modules used for its components. Because of the flexibility and permissionless nature of the OP Stack, it is always possible for someone to maliciously or in error set up a chain which does not make use of core security features, but uses other components of OP Stack. **The goal of the OP Stack is to provide safe defaults.**

Please also keep in mind that just like any other system, **the OP Stack (or chains built using the OP Stack) may contain unknown bugs**  that could lead to the loss of some or all of the ETH and tokens held within an OP Stack based system.
Many components of the OP Stack codebase have been [audited](https://github.com/ethereum-optimism/optimism/tree/v1.1.4/technical-documents/security-reviews) (as of `v1.1.4`), but successful audits do not remove all potential risk from an emerging technology, and a completed audit does not mean that the codebase is completely free of bugs.
It's important to understand that using the OP Stack inherently exposes you to the risk of bugs within the OP Stack codebase.

### Is the OP Stack safe to modify?

As with anything, modify the OP Stack at your own risk. There is no guarantee that modifications to the stack will be safe. If you aren't entirely sure about what you're doing, stick with the safer defaults that the OP Stack provides. At the moment, the OP Stack is not particularly amenable to modifications and **you should not expect any technical support for modifications that fall outside of the standard Rollup configuration of the stack**.


# Crosschain security measures for safe interoperability
Source: https://docs.optimism.io/op-stack/security/interop-security

Learn more about crosschain security measures for safe interoperability

<Info>OP Stack interop is in active development. Some features may be experimental.</Info>

## The trust model

This interop vulnerability arises when an initiating message seems to exist, prompting the processing of the executing message. However, the initiating message ends up not actually appearing in the canonical chain.
Excluding L1 reorgs, this can happen in two ways:

* *Equivocation*. A sequencer publishes a block using the gossip protocol that is different from the one that eventually gets written to L1.
  The problem happens when the gossip protocol block includes a log entry that is used as an initiating message, but the real block (the one written to L1) doesn't.
  The way this is handled is that a block that depends on an unsafe block is, itself, unsafe.
  It does not get treated as safe until all the blocks on which it depends (directly or indirectly) are also written to L1.

* *Faulty information*. The sequencer operator can run a verifier node for every chain in the dependency set, in which case it can deduce the initiating messages from the safe transactions of every chain.
  To save on resources, the sequencer can choose to query existing nodes of the source blockchain.
  In that case, if the information provided to sequencer is incorrect, of course the blocks posted by the sequencer will be also incorrect.

  In this case, invalid blocks will be replaced with deposit only blocks by other verifiers.

  <Expandable title="What are deposit only blocks?">
    Normally the blocks that make it to the canonical blockchain are those posted to L1 by the sequencer.
    However, when those blocks are missing or invalid (for example because they rely on an initiating message that is missing), they're replaced by *deposit only blocks*, blocks whose content can be calculated from L1 without relying on the sequencer.

    The way this works is that there are two types of user transactions in an OP Stack block:

    * Sequencer transactions, which go through the sequencer.
      These transactions are extremely cheap, but in theory a sequencer could censor them.
    * Deposit transactions, which users submit through L1.
      These transactions have the cost of an L1 transaction, which is a lot higher, but they cannot be censored by the sequencer.

    A deposit only block only contains the deposit transactions and some internal transactions, not the sequencer transactions.

    For more information about this process, [see the technical specifications](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#deriving-the-transaction-list).
  </Expandable>

## The latency/security tradeoff

The initiating message comes from a block on a different blockchain.
If we accept initiating messages as soon as the block is available through the gossip protocol, we have minimal latency but at a security cost (because the source sequencer can send incorrect information through gossip).
Alternatively, we can wait until the source sequencer posts the block to L1.
In that case we can be more certain that the block is correct, but at the cost of higher latency.

There are three different possibilities, at different levels of latency and security.

### Unsafe initiating messages

L2 blocks start as unsafe, meaning that there's no L1 evidence for them, and the sequencer for that blockchain can send out incorrect information.
Sending out incorrect information, for example that a certain transaction is included in a block when it isn't, is called *equivocation*.
A sequencer that builds blocks with interop can choose to accept messages from unsafe blocks (received through the gossip protocol), for minimal latency.

To minimize the risk of equivocation, a block written to L1 (*local safe*) is only considered fully safe (*cross safe*) once both that block and all preceding blocks in its blockchain are also written to L1.
If the source block is written to L1 first, the destination sequencer can detect it.
If the source block is missing an initiating message that the sequencer relied on due to equivocation, the sequencer can identify the error and recalculate the state. In this scenario, no significant harm occurs.

However, if the destination block—containing the executing message that depends on the initiating message—is written to L1 first (e.g., due to higher traffic on the chain), a different risk arises.
If the source block that is eventually written to L1 lacks the initiating message, verifiers will detect that the derivation of the destination block, and any blocks dependent on it, is incorrect.
In this case, the destination block and all subsequent blocks on any chain that depend on it are classified as deposit-only blocks.

```mermaid theme={null}

sequenceDiagram
    actor app as User
    participant src as Source Chain
    participant dst as Destination Chain
    participant l1 as Ethereum Mainnet
    note over src,dst: ↓ Initiating message ↓
    src->>dst: Block src_n will have transaction txn_0 that emits log event evt_0
    note over app,dst: ↓ Executing message ↓    
    app->>dst: Transaction txn_1: If you have evt_0, call contract C with the data in evt_0. Otherwise, revert.
    note left of dst: Block dst_m will <br/> have the results of <br/> calling contract C <br/> with the data in evt_0.
    break
        note over app,l1: time passes
    end
    dst->>l1: Write block dst_m, which includes a successful txn_1.
    break
        note over app,l1: time passes
    end    
    src->>l1: Write block src_n without txn_0 (so no evt_0)
    l1->>dst: This is the safe block src_n
    note left of dst: No evt_0, so block dst_m is incorrect <br /> and so is every subsequent block. <br /> All those blocks are replaced with <br /> deposit only blocks.
```

### Safe initiating messages

Alternatively, a sequencer can be configured to only accept executing messages once the initiating message is in a cross safe block.
A cross safe block is one that is written to L1, and whose dependencies (direct or indirect, including dependencies of previous blocks in the same chain) are all written to L1.

When a block is cross safe, the source sequencer cannot equivocate, and the state will only need to be recalculated if there's an [L1 reorg](https://www.alchemy.com/overviews/what-is-a-reorg#what-happens-to-reorgs-after-the-merge).
The cost of this enhanced security that it would take longer for a message to pass from one blockchain to the other.
Higher throughput OP Stack chains like Base and OP Mainnet submit a batch about every 5 minutes, so on average it takes about 2.5 minutes for an initiating message to become safe.

You can use [this dune dashboard](https://dune.com/oplabspbc/op-stack-chains-l1-activity#submission-frequency) to see how often OP Stack chains submit batches.

```mermaid theme={null}

sequenceDiagram
    actor app as User
    participant src as Source Chain
    participant dst as Destination Chain
    participant l1 as Ethereum Mainnet
    note over src,dst: ↓ Initiating message ↓
    src->>dst: Block src_n will have transaction txn_0 that emits log event evt_0
    note over app,dst: ↓ Executing message ↓    
    app->>dst: Transaction txn_1: If you have evt_0, call contract C with the data in evt_0, otherwise revert.
    note over dst: Block src_n is not safe yet,<br />txn_1 fails
    break
        note over app,l1: time passes
    end
    src->>l1: Write block src_n with txn_0
    l1->>dst: This is the safe block src_n
    app->>dst: Transaction txn_2: If you have evt_0, call contract C with the data in evt_0. 
    note over app,dst: Executing message
    note over dst: Now I have evt_0, <br />so txn_2 is successful

```

### Finalized initiating messages

A sequencer can also be configured to reject all executing messages until the initiating message is *finalized*, meaning it's irrevocably on L1 and immune to reorgs.
Currently, this adds [about 15 minutes](https://ethereum.org/en/roadmap/single-slot-finality/) to the message latency.

<br />

<Image alt="Safe and Unsafe Security Diagram" />

<Info>
  Even if a sequencer accepts unsafe initiating messages, the blocks it constructs that rely on them are considered unsafe until the blocks with those initiating messages are written to L1 and become safe.
</Info>

* For more info about how OP Stack interoperability works under the hood, [check out the specs](https://specs.optimism.io/interop/overview.html?utm_source=op-docs\&utm_medium=docs)
* View more [interop tutorials](/app-developers/tutorials/interoperability/message-passing)


# Pausing the bridge
Source: https://docs.optimism.io/op-stack/security/pause

Learn how the OP Stack bridge can be paused as backup safety mechanism.

The [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol) is the low-level L1 message passing contract present on all standard OP Stack chains.
This contract handles the L1 side of the communication channel between an OP Stack chain and its L1 parent chain.

As a safety mechanism, a privileged `GUARDIAN` address can pause withdrawals.
When paused, the `OptimismPortal` contract will prevent L2-to-L1 transactions from being executed.
This is a backup safety mechanism that can be used to help mitigate potential active security concerns.

Pause functionality were introduced to the OP Stack to mitigate the risk of withdrawal bugs that have led to exploits in other bridging systems.

## Pause functionality

The `OptimismPortal` points to a `SuperchainConfig` smart contract which has a privileged `GUARDIAN` address that can pause and unpause L2-to-L1 transactions from being executed.
The `SuperchainConfig` contract is a shared implementation across OP Stack chains. All Optimism-governed chains point to it, and any OP Stack chain can point its `SuperchainConfigProxy` to this shared implementation.
L2-to-L1 transactions allow users and smart contracts on the OP Stack chain to send messages to the L1 parent chain.
Pause functionality allows a `GUARDIAN` to halt L2-to-L1 transaction execution for the OP Stack chain in question.
L1-to-L2 transactions are not affected by pause functionality.

Pauses by the `GUARDIAN` impact all L2-to-L1 transactions for the OP Stack chain in question and cannot be targeted to specific users, smart contracts, or transactions.
Pauses are designed to be a backup safety mechanism and are expected to be used only in the event of an active pressing security concern.

## Pause and unpause functions

The `GUARDIAN` can pause and unpause L2-to-L1 transactions at any time by calling the [`pause`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/SuperchainConfig.sol#L81-L94) and [`unpause`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/SuperchainConfig.sol#L98-L105) functions on the `SuperchainConfig` contract.

## Guardian address

The `GUARDIAN` address is configured in the `SuperchainConfig` contract and can be modified by the network's administrative address or smart contract. To learn more about the privileged role, see [documentation](/op-stack/protocol/privileged-roles#guardian).

The `GUARDIAN` address is set as an `immutable` variable inside of the `SuperchainConfig` contract.
To change the `GUARDIAN` address, the `SuperchainConfig` proxy contract must be upgraded to a new implementation contract that has a different `GUARDIAN` address.

## Additional information

While this functionality is available for the OP Stack protocol, it does not cover the security of centralized exchanges and third party bridges.
If you operate a centralized exchange or third party bridge, you should monitor this contract and pause withdrawals from OP Stack chains if you see that it has been paused.
If you'd like to learn more about the privileged roles in the OP Stack, see the [privileged roles](/op-stack/protocol/privileged-roles) documentation.


# Security policy and bug bounty program
Source: https://docs.optimism.io/op-stack/security/security-policy

Learn about the bug bounty program and best practices for reporting bugs in the OP Stack codebase.

This page describes general best practices for reporting bugs and provides specific reporting guidelines for OP Stack and OP Mainnet code contained within the [ethereum-optimism](https://github.com/ethereum-optimism) GitHub organization.

<Info>
  **Do not** disclose vulnerabilities publicly or by executing them against a production network. If you do, you will not only be putting users at risk, but you will forfeit your right to a reward. Always follow the appropriate reporting pathways as described below.

  * **Do not** disclose the vulnerability publicly, for example by filing a public ticket.
  * **Do not** test the vulnerability on a publicly available network, either the testnet or the mainnet.
</Info>

## Optimism bug bounty program

The Optimism Bug Bounty Program offers up to [\$2,000,042](https://immunefi.com/bounty/optimism/) for critical vulnerabilities found in the OP Mainnet codebase.
Below you can find information about the various available bug bounty programs and how to report bugs that are not covered by an existing bounty.

### Main bounty page

Optimism has a very detailed [Bug Bounty Page on Immunefi](https://immunefi.com/bounty/optimism/). In the listing you can find all the information relating to components in scope, reporting, and the payout process.

### Unscoped bugs

If you think you have found a significant bug or vulnerability in OP Stack smart contracts, infrastructure, etc., even if that component is not covered by an existing bug bounty, please report it via the [Immunefi program](https://immunefi.com/bounty/optimism/). The impact of any and all reported issues will be considered and the program has previously rewarded security researchers for bugs not within its stated scope.

## Reporting other vulnerabilities

For vulnerabilities in any websites, email servers, or other non-critical infrastructure within the OP Stack, please contact the Foundation's service provider at [security@oplabs.co](mailto:security@oplabs.co) and include detailed instructions for confirming and reproducing the vulnerability.

### Vulnerability disclosure

Each OP Stack component maintainer may determine its own process for vulnerability disclosure. However, the following describes a recommended process for disclosure.

In the event that an OP Stack component maintainer learns of a critical security vulnerability, the maintainer reserves the right to silently fix it without immediately publicly disclosing the existence or nature of the vulnerability.

In such a scenario, the disclosure process used is as follows:

1. Silently fix the vulnerability and include the fix in release X.
2. After 4-8 weeks, disclose that release X contained a security fix.
3. After an additional 4-8 weeks, publish details of the vulnerability, along with credit to the reporter (with express permission from the reporter).

### Rights of maintainers

Alongside this policy, maintainers also reserve the right to:

* Bypass this policy and publish details on a shorter timeline.
* Directly notify a subset of downstream users prior to making a public announcement.

This policy is based on the [Geth](https://geth.ethereum.org/) team's [silent patch policy](https://geth.ethereum.org/docs/developers/geth-developer/disclosures#why-silent-patches).


# Fee vaults
Source: https://docs.optimism.io/op-stack/transactions/fee-vaults

Learn how fee vaults work on OP Stack chains, where transaction fees are collected, and how the withdrawal mechanism operates.

Fee vaults are predeploy contracts on OP Stack L2 chains that collect and hold the different components of transaction fees. Unlike Ethereum where the base fee is burned, OP Stack chains route all fees into dedicated vault contracts, allowing chain operators to withdraw and manage collected revenue.

## Overview

Every OP Stack chain has four fee vaults, each collecting a specific fee component:

| Vault               | Address                                      | Collects                     | Introduced |
| ------------------- | -------------------------------------------- | ---------------------------- | ---------- |
| `SequencerFeeVault` | `0x4200000000000000000000000000000000000011` | Priority fees (tips)         | Legacy     |
| `BaseFeeVault`      | `0x4200000000000000000000000000000000000019` | Base fees (not burned on L2) | Bedrock    |
| `L1FeeVault`        | `0x420000000000000000000000000000000000001A` | L1 data fees                 | Bedrock    |
| `OperatorFeeVault`  | `0x420000000000000000000000000000000000001B` | Operator fees                | Isthmus    |

### How fees flow into vaults

When a transaction is executed on an OP Stack chain, the total fee is split across vaults:

* **Base fee** (`gasUsed × baseFee`) goes to the `BaseFeeVault`
* **Priority fee** (`gasUsed × priorityFee`) goes to the `SequencerFeeVault`
* **L1 data fee** goes to the `L1FeeVault`
* **Operator fee** (`operatorFeeScalar × gasUsed + operatorFeeConstant`) goes to the `OperatorFeeVault`

Each component has its own formula. For the full breakdown, see [Transaction fees](/op-stack/transactions/fees).

## Vault configuration

Each fee vault has three configurable parameters:

| Parameter               | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| **recipient**           | The address that receives withdrawn funds                         |
| **minWithdrawalAmount** | Minimum ETH balance required before a withdrawal can be triggered |
| **withdrawalNetwork**   | Whether funds are withdrawn to an L1 or L2 address                |

### Withdrawal network

The `withdrawalNetwork` parameter determines how funds are routed when withdrawn:

* **L1 (`0`)**: Funds are sent to the recipient on L1 via the `L2ToL1MessagePasser`. This initiates a standard L2-to-L1 withdrawal that must be proven and finalized on L1.
* **L2 (`1`)**: Funds are sent directly to the recipient on L2 via a simple ETH transfer.

## Withdrawal mechanism

Fee vault withdrawals are **permissionless** — anyone can trigger a withdrawal by calling the `withdraw()` function on any vault. This design ensures that collected fees can always be moved to the configured recipient without relying on a specific operator.

### How withdrawals work

1. The caller invokes `withdraw()` on the vault contract.
2. The vault checks that its balance meets the `minWithdrawalAmount` threshold.
3. The entire vault balance is withdrawn (not a partial amount).
4. The `totalProcessed` counter is incremented.
5. Funds are routed based on `withdrawalNetwork`:
   * **L2**: Direct ETH transfer to the recipient.
   * **L1**: A withdrawal is initiated through the `L2ToL1MessagePasser` with a 400,000 gas limit. The withdrawal must then be [proven and finalized](/op-stack/bridging/withdrawal-flow) on L1.

## Next steps

* Learn how to [configure and withdraw from fee vaults](/chain-operators/guides/management/fee-vaults) as a chain operator.
* Understand [transaction fee components](/op-stack/transactions/fees) in detail.
* Review the [smart contracts reference](/op-stack/protocol/smart-contracts) for all predeploy addresses.


# Transaction fees on OP Mainnet
Source: https://docs.optimism.io/op-stack/transactions/fees

Learn how transaction fees work on OP Mainnet.

<Info>
  The OP Stack maintains a distinct gas limit compared to the Ethereum mainnet.
  While both chains use the same underlying transaction formats, Optimism's gas limits are tailored for optimal Layer 2 performance and scalability.
  As a result, transactions on Optimism may behave differently from the mainnet regarding gas usage and fee estimation.
  For a detailed comparison of gas limits between Optimism and Ethereum, see the [Differences between Ethereum and OP Stack Chains](/op-stack/protocol/differences).
</Info>

<Info>
  **Learn the OP Stack — stop 7 of 13.**
  You know how a transaction moves through the stack. This page adds what
  that journey costs: the components of an OP Stack transaction fee and
  what determines each one. When you're done, continue to
  [Deposit flow](/op-stack/bridging/deposit-flow).
</Info>

OP Mainnet is designed to be [EVM equivalent](https://web.archive.org/web/20231127160757/https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306), which means it reuses the same Ethereum code you're already familiar with and behaves as much like Ethereum as possible.
However, transaction fees on all Layer 2 systems need to diverge from Ethereum to some extent for a number of reasons.
This page provides a detailed look at exactly how transaction fees work on OP Mainnet so you can properly account for them in your application.

OP Mainnet transaction fees are composed of an [Execution gas fee](#execution-gas-fee), an [L1 data fee](#l1-data-fee), and after the [Isthmus upgrade](/notices/upgrade-14#operator-fee), an [operator fee](#operator-fee).
The total cost of a transaction is the sum of these fee components:

**Before Isthmus:**

```
totalFee = gasUsed * (baseFee + priorityFee) + l1Fee
```

**After Isthmus:**

```
totalFee = operatorFee + gasUsed * (baseFee + priorityFee) + l1Fee
```

Continue reading to learn more about exactly how each of these fee components are charged.

## Execution gas fee

A transaction's execution gas fee is exactly the same fee that you would pay for the same transaction on Ethereum.
This fee is equal to the amount of gas used by the transaction multiplied by the gas price attached to the transaction.
Like Ethereum, OP Mainnet uses the [EIP-1559](https://eips.ethereum.org/EIPS/eip-1559) mechanism to set the [base fee](https://ethereum.org/en/developers/docs/gas/#base-fee) for transactions.
The total price per unit gas that a transaction pays is the sum of the [base fee](https://ethereum.org/en/developers/docs/gas/#base-fee) and the optional additional [priority fee](https://ethereum.org/en/developers/docs/gas/#priority-fee).

Because OP Mainnet is EVM equivalent, **the gas used by a transaction on OP Mainnet is exactly the same as the gas used by the same transaction on Ethereum**.
If a transaction costs 100,000 gas on Ethereum, it will cost 100,000 gas on OP Mainnet.
The only difference is that the gas price on OP Mainnet is much lower than the gas price on Ethereum so you'll end up paying much less in ETH.

For this component of the fee, you can estimate the total cost of a transaction using the same tools you would use to estimate the cost of a transaction on Ethereum.
You can read more about how Ethereum's gas fees work over on [Ethereum.org](https://ethereum.org/en/developers/docs/gas/).

### Base fee

The [base fee](https://ethereum.org/en/developers/docs/gas/#base-fee) is the minimum price per unit of gas that a transaction must pay to be included in a block.
Transactions must specify a maximum base fee higher than the block base fee to be included.
The actual fee charged is the block base fee, even if the transaction specifies a higher maximum base fee.

The OP Mainnet base fee behaves exactly like the Ethereum base fee, with a few small parameter changes to account for the much shorter block times on OP Mainnet.
None of these parameters should significantly impact your application, but you can read more about each of these parameters on the [OP Mainnet differences](/op-stack/protocol/differences#eip-1559-parameters) page.
Read more about the base fee in the [Ethereum.org documentation](https://ethereum.org/en/developers/docs/gas/#base-fee).

### Priority fee

Just like on Ethereum, OP Mainnet transactions can specify a **priority fee**.
This priority fee is a price per unit of gas that is paid on top of the base fee.
For example, if the block base fee is 1 gwei and the transaction specifies a priority fee of 1 gwei, the total price per unit of gas is 2 gwei.
The priority fee (i.e. tip) is an optional component of the execution gas fee and can technically be set to 0.
However, while EIP-1559 does not define a minimum priority fee, certain wallets and mempool implementations (like Geth) may enforce a minimum value. For instance, Geth typically defaults to a minimum priority fee of 1 gwei, but this can be configured to other values.

**The OP Mainnet sequencer will prioritize transactions with a higher priority fee** and execute them before any transactions with a lower priority fee.
If transaction speed is important to your application, you may want to set a higher priority fee to ensure that your transaction is included more quickly.
The [`eth_maxPriorityFeePerGas`](https://docs.alchemy.com/reference/eth-maxpriorityfeepergas) RPC method can be used to estimate a priority fee that will get your transaction included quickly.

<Info>
  OP Mainnet has run a time-boxed experiment in **stake-based priority ordering**, in which stake held in the `PolicyEngineStaking` contract — not priority fee alone — influenced transaction ordering. The experiment was scheduled to begin on May 26, 2026 and to run for a maximum of four weeks, after which OP Mainnet reverts to the priority-fee ordering described above. Check the [stake-based priority ordering notice](/notices/archive/stake-based-priority-ordering) and the [Governance Proposal](https://gov.optimism.io/t/upgrade-proposal-stake-based-priority-ordering-experiment/10655) before assuming either ordering applies.
</Info>

## L1 data fee

The L1 Data Fee is the only part of the OP Mainnet transaction fee that differs from the Ethereum transaction fee.
This fee arises from the fact that the transaction data for all OP Mainnet transactions is published to Ethereum.
This guarantees that the transaction data is available for nodes to download and execute.
The L1 Data Fee accounts for the cost to publish an OP Mainnet transaction to Ethereum and is primarily determined
by the current base fee on Ethereum. After the Ecotone upgrade, OP Stack chains will have the option of posting
transactions using [`blobs`](https://www.eip4844.com/). For blob-enabled chains, the current Ethereum blob data
gas price will largely determine the L1 Data Fee.

### Mechanism

The L1 Data Fee is automatically charged for any transaction that is included in an OP Mainnet block.
This fee is deducted directly from the address that sent the transaction.
The exact amount paid depends on the estimated size of the transaction in bytes after compression,
the current Ethereum gas price and/or blob gas price, and several small parameters.

The L1 Data Fee is most heavily influenced by the Ethereum base fee that is continuously and trustlessly relayed from Ethereum to
OP Mainnet.  With the Ecotone upgrade, the Ethereum blob base fee also gets relayed to OP Mainnet, and will become the most
important factor for chains configured to use blobs instead of base fee.  The base fee and blob base fee are updated on OP
Mainnet for every Ethereum block, and each fluctuates at most by 12.5% between updates.  As a result, short-term fluctuations of
the L1 Data Fee are generally quite small and should not impact the average transaction.

<Info>
  The L1 Data Fee is charged automatically.
  **It is currently not possible to limit the maximum L1 Data Fee that a transaction is willing to pay.**
  This is the result of limitations in existing Ethereum transaction formats and tradeoffs that the OP Stack makes to retain better EVM equivalence.
  Work is underway to improve this situation with the introduction of a new standardized transaction type.
  For now, you should be aware that the L1 Data Fee can fluctuate with the Ethereum gas price.
</Info>

### Formula

#### Bedrock

<Info>
  The L1 Data Fee formula changed with the Ecotone upgrade.
  Refer to the [Network upgrade overview](/op-stack/protocol/network-upgrades) for network upgrade activation timestamps for OP Sepolia and OP Mainnet.
</Info>

Prior to the Ecotone upgrade, the L1 Data Fee is calculated based on the following parameters:

* The **signed** transaction, serialized according to [the standard Ethereum transaction RLP encoding](https://github.com/ethereum-optimism/op-geth/blob/optimism/core/types/transaction.go#L141-L151).
* The current Ethereum base fee  (trustlessly relayed from Ethereum).
* A fixed overhead cost for publishing a transaction (currently set to 188 gas).
* A dynamic overhead cost which scales with the size of the transaction (currently set to 0.684).

The L1 Data Fee calculation first begins with counting the number of zero bytes and non-zero bytes in the transaction data.
Each zero byte costs 4 gas and each non-zero byte costs 16 gas.
This is the same way that Ethereum calculates the gas cost of transaction data.

```python theme={null}
tx_data_gas = count_zero_bytes(tx_data) * 4 + count_non_zero_bytes(tx_data) * 16
```

After calculating the gas cost of the transaction data, the fixed and dynamic overhead values are applied.

```python theme={null}
tx_total_gas = (tx_data_gas + fixed_overhead) * dynamic_overhead
```

Finally, the total L1 Data Fee is calculated by multiplying the total gas cost by the current Ethereum base fee.

```python theme={null}
l1_data_fee = tx_total_gas * ethereum_base_fee
```

#### Ecotone

<Info>
  The L1 Data Fee formula changed with the Ecotone upgrade.
  Refer to the [Network Upgrade Overview](/op-stack/protocol/network-upgrades) for network upgrade activation timestamps for OP Sepolia and OP Mainnet.
</Info>

The pricing function changes with Ecotone upgrade because of the introduction of the option to
post transaction batches to the L1 using blobs instead of through L1 calldata. This updated
function uses the following parameters:

* The **signed** transaction serialized according to [the standard Ethereum transaction RLP encoding](https://github.com/ethereum-optimism/op-geth/blob/optimism/core/types/transaction.go#L141-L151).
* The current Ethereum base fee and/or blob base fee (trustlessly relayed from Ethereum).
* Two new scalar parameters that independently scale the **base fee** and **blob base fee**.

At the exact point of the Ecotone upgrade, the dynamic overhead parameter value is used to
initialize the Ecotone base fee scalar, and blob base fee is set to 0. The overhead parameter from
the previous function becomes ignored.

The Ecotone L1 Data Fee calculation begins with counting the number of zero bytes and non-zero
bytes in the transaction data.  Each zero byte costs 4 gas and each non-zero byte costs 16
gas. This value, when divided by 16, can be thought of as a rough estimate of the size of the
transaction data after compression.

```python theme={null}
tx_compressed_size = [(count_zero_bytes(tx_data)*4 + count_non_zero_bytes(tx_data)*16)] / 16
```

Next, the two scalars are applied to the base fee and blob base fee parameters to compute a weighted
gas price multiplier.

```python theme={null}
weighted_gas_price = 16*base_fee_scalar*base_fee + blob_base_fee_scalar*blob_base_fee
```

The L1 Data Fee is then:

```python theme={null}
l1_data_fee = tx_compressed_size * weighted_gas_price
```

Recall that base\_fee\_scalar is set to dynamic\_overhead and blob\_base\_fee\_scalar is 0 immediately
following the upgrade. Because the old overhead parameter becomes ignored, new L1 data prices will
be (slightly, since overhead is typically very small) lower than before the fork.  Chain
operators will likely want to retune the parameters appropriately after the fork, particularly if
they plan on [enabling blobs](/chain-operators/guides/features/blobs).
For guidance on choosing scalar values, chain operators can follow [Recover the spend with fee scalars](/use-cases/tune-batcher-costs#step-5-recover-the-spend-with-fee-scalars) in the Tune batcher costs guide.

#### Fjord

<Info>
  The L1 Data Fee formula changed with the Fjord upgrade. Refer to the [Network Upgrade Overview](/op-stack/protocol/network-upgrades) for network upgrade activation timestamps for OP Sepolia and OP Mainnet.
</Info>

The pricing function changes with the Fjord upgrade because of the FastLZ compression estimator, which more accurately charges for L1 data usage on a per-transaction basis.
The updated function uses the following parameters:

* The FastLZ-compressed size of the signed transaction.
* The current Ethereum base fee and/or blob base fee (trustlessly relayed from Ethereum).

The Fjord L1 Data Fee calculation begins with estimating the transaction size using a linear model over the FastLZ-compressed transaction size.

```
estimatedSizeScaled = max(minTransactionSize * 1e6, intercept + fastlzCoef*fastlzSize)
```

The model parameters `intercept` and `fastlzCoef` were determined by performing a linear regression analysis over a dataset of previous L2 transactions minimizing the root mean square error against the change in batch size, when compressed with Brotli, over historical OP mainnet data. These parameters are fixed in Fjord. The `minTransactionSize`, `intercept`, and `fastlzCoef` values are scaled by 1e6.

Next, the two chain parameters **base fee scalar** and **blob base fee scalar** are used to compute a weighted gas price multiplier.

```
l1FeeScaled = baseFeeScalar*l1BaseFee*16 + blobFeeScalar*l1BlobBaseFee
```

Both scalars are scaled by 1e6. The final L1 Data Fee is then

```
l1Cost = estimatedSizeScaled * l1FeeScaled / 1e12
```

The new cost function takes into account the compression ratio, so chain operators will need to adjust their `baseFeeScalar` and `blobFeeScalar`  to account for any previous compression ratios that they encountered on their chains. For guidance on choosing scalar values, chain operators can follow [Recover the spend with fee scalars](/use-cases/tune-batcher-costs#step-5-recover-the-spend-with-fee-scalars) in the Tune batcher costs guide.

## Operator fee

<Info>
  The Operator fee was introduced with the [Isthmus upgrade](/notices/upgrade-14#operator-fee) and modified with the [Jovian upgrade](/notices/upgrade-17#breaking-changes).
  It provides OP Stack chains with more flexible pricing models.
  Refer to the [Network upgrade overview](/op-stack/protocol/network-upgrades) for network upgrade activation timestamps.
</Info>

The Operator fee is a new fee component which enables more customizable fee structures for OP Stack chains. This fee is integrated directly into the EVM alongside the standard gas fee and L1 data fee, allowing chain operators to implement additional revenue models or cover specific operational costs.

### Mechanism

The Operator fee is automatically charged for any transaction that is included in a block after the Isthmus activation. This fee is deducted directly from the address that sent the transaction and follows the same semantics as existing fees charged in the EVM. The collected operator fees are sent to the **Operator Fee Vault**, a new vault similar to existing [fee vaults](/op-stack/transactions/fee-vaults).

<Info>
  **Deposit transactions do not get charged operator fees.** For all deposit transactions, regardless of the operator fee parameter configuration, the operator fee is always zero.
</Info>

### Formula

The Operator fee is calculated using the following formula, depending on the active fork:

**After Isthmus:**

```
operatorFee = operatorFeeConstant + (gasUsed × operatorFeeScalar ÷ 10^6)
```

**After Jovian:**

```
operatorFee = operatorFeeConstant + (gasUsed × operatorFeeScalar × 100)
```

Where:

* `gasUsed` is the amount of gas that the transaction used
* `operatorFeeScalar` is a `uint32` scalar set by the chain operator, scaled by 1e6
* `operatorFeeConstant` is a `uint64` scalar set by the chain operator

### Configuration

The `operatorFeeScalar` and `operatorFeeConstant` parameters can be accessed in two ways:

1. **From deposited L1 attributes** of the current L2 block
2. **From the L1 Block Info contract** (`0x4200000000000000000000000000000000000015`):
   * Using solidity getter functions (`operatorFeeScalar`, `operatorFeeConstant`)
   * Using direct storage reads:
   * Operator fee scalar as big-endian `uint32` in slot `8` at offset `0`
   * Operator fee constant as big-endian `uint64` in slot `8` at offset `4`

### EVM Integration

The Operator fee follows standard EVM fee semantics:

1. **Pre-execution validation**: Account must have enough ETH to cover worst-case gas + L1 data fees + worst-case operator fee
2. **Gas purchase**: Account is charged the worst-case operator fee before execution
3. **Refunds**: After execution, unused operator fee gas is refunded to the account
4. **Fee distribution**: The spent operator fee is sent to the Operator Fee Vault

### Transaction pool impact

Transaction pools must account for the additional operator fee when validating transactions. Transactions without sufficient balance to cover the worst-case total cost (including operator fee) will be rejected.

## Fee vaults

Each fee component is routed to a dedicated [fee vault](/op-stack/transactions/fee-vaults) contract on L2. Unlike Ethereum where the base fee is burned, OP Stack chains collect all fees in these vaults, allowing chain operators to withdraw and manage collected revenue. See the [fee vaults](/op-stack/transactions/fee-vaults) page for details on how vaults work and the [fee vault operations guide](/chain-operators/guides/management/fee-vaults) for managing them.

## Next steps

* Learn how [fee vaults](/op-stack/transactions/fee-vaults) collect and distribute transaction fees.
* Read the [differences between Ethereum and OP Stack Chains](/op-stack/protocol/differences) guide.
* Read the [L2 to L1 Transactions](/app-developers/bridging/messaging#for-l1-to-l2-transactions) guide.


# Forced Transaction
Source: https://docs.optimism.io/op-stack/transactions/forced-transaction

Learn the forced transaction flow during sequencer downtime.

## Forced transaction flow

This guide explains the nuances of forced transactions during sequencer downtime.

In the OP Stack, forced transactions serve as a mechanism to ensure transaction inclusion, even during sequencer downtime.
Users are able to force-include transactions, which can initiate withdrawals, at any time.
A forced transaction is an ordinary [deposit transaction](/op-stack/bridging/deposit-flow) submitted directly on L1; this page focuses on its censorship-resistance role and inclusion timing during sequencer downtime, while the [Deposit flow](/op-stack/bridging/deposit-flow) explainer covers the underlying mechanics.
However, there are important nuances to understand about the chain derivation pipeline and sequencer behavior.

## Key concepts

* **Sequencing Window**: A 12-hour rolling window to include L2 transactions, including native L2 transactions and deposit transactions.
* **Max Time Drift**: 30 minutes, the maximum delay for including a deposit transaction, relative to the L2 chain.
* **Sequencer Downtime**: Period when the sequencer is offline or not producing blocks.
* **Forced Transactions**: Transactions that users can submit directly to the L1 chain, ensuring their inclusion in the L2 chain without sequencer intervention.
  This mechanism is crucial during sequencer downtime.

## Normal operation

Under normal circumstances:

1. Deposit transactions are included within 30 minutes.
2. The sequencer processes transactions and produces blocks regularly.

## Forced transaction mechanism

1. **Submission to L1:**
   Users can send transactions directly to the `OptimismPortal` contract on L1 Ethereum. This bypasses the sequencer, ensuring that the transaction is recorded on L1.

2. **Inclusion in L2:**
   Once submitted to L1, these transactions are automatically included in the L2 chain. The timing of their inclusion depends on the duration of the sequencer's downtime:

   * **Short Downtime (\< 30 minutes):**
     During short downtime `~ 30 minutes`, transactions may still be included within the usual 30-minute maximum time drift if the sequencer resumes operation within that window.

   * **Extended Downtime (30 minutes to 12 hours):**
     During sequencer downtimes lasting between 30 minutes and 12 hours:

     * Deposit Transactions: Users can submit forced transactions directly to the [`OptimismPortal`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol#L684) contract on L1. However, these transactions will only be included in the L2 chain once the sequencer resumes or the 12-hour sequencing window expires.
       Refer to the [Bypassing the Sequencer](/op-stack/protocol/outages#bypassing-the-sequencer) section for more information about this functionality.
     * L2 Chain State: The L2 chain's state remains uncertain until either:
       The sequencer resumes operations and processes pending transactions, or
       the 12-hour sequencing window expires (after which nodes begin generating blocks deterministically, incorporating only the forced-included deposit transactions).

   * **Sequencer Catch-up Phase:**
     If the sequencer is offline for more than 30 minutes but less than 12 hours, it enters a **quick catch-up** phase upon restarting.
     During this phase:
     * The sequencer produces **deposit-only blocks** while moving the L1 origin forward with every block.
     * This continues until the L1 origin is back inside the sequencer drift window.
     * Normally, L2 blocks are produced at a **6:1 ratio** relative to their L1 origin (12s per L2 block vs. 2s per L1 block). However, during the catch-up phase, this ratio **switches to 1:1**, meaning each L2 block corresponds to a new L1 origin.

   * **Prolonged Downtime (> 12 hours):**
     After 12 hours, nodes begin generating blocks deterministically, incorporating only the forced-included transactions. Regular L2 transactions are deferred until the sequencer is back online and has processed enough blocks to be within the last 12 hours of the L1 state.

## Benefits of forced transactions

* **Mitigate censorship:** Forced transactions act as an alternative mechanism so users can ensure their transactions are processed even if the sequencer attempts to censor them.
* **Network Resilience:** The network remains operational, allowing critical transactions to proceed during sequencer downtimes.
* **User Autonomy:** Users are not entirely dependent on the sequencer for transaction inclusion, providing an additional layer of trust and reliability.

## Important considerations

* Forced transactions, through deposits (no need for deposited value), ensure timely execution of actions, mitigating risks like DEX price divergence during sequencer downtime.
* Actions remain speculative for up to 12 hours due to the sequencing window.
* The 12-hour window is a balance between operational reliability and minimizing potential L2 reorganizations.

## Example scenario

If a deposit is initiated after the 30-minute mark but before the sequencing window expires:

1. The deposit will be effective when the sequencing window expires (up to \~11 hours later).
2. Nodes reading data from L1 will produce a block with the deposit after the sequencing window expires.
3. The eventual L2 chain will include the deposit in a block with an onchain timestamp close to the L1 block where the deposit originated.

<Info>
  The sequencing window is a rolling 12-hour delay from when an L1 block is
  first known. This design allows the sequencer a grace period to come back
  online without causing L2 chain reorganizations.
</Info>

## Conclusion

The forced transaction mechanism on OP Stack chains provides a robust way to handle [sequencer downtime](/op-stack/protocol/outages#sequencer-downtime-outages), ensuring that critical transactions are included in a timely manner.
While the 12-hour sequencer window introduces a degree of uncertainty during downtime, the system is designed to guarantee eventual consistency and transaction inclusion.


# Transaction finality
Source: https://docs.optimism.io/op-stack/transactions/transaction-finality

Learn when transactions on OP Stack chains can be considered finalized.

This guide explains when transactions on OP Stack chains are considered final and addresses common misconceptions about transaction finality on the OP Stack. It describes finality in the two stages that matter to most users, **soft finality** and **hard finality**, and maps both onto the protocol's own terms (unsafe, safe, and finalized) that node operators and RPC users work with.

## Basics of finality

Transaction finality refers to the point at which a transaction becomes irreversible under certain assumptions. For example, Ethereum transactions are considered finalized when specific conditions in Ethereum's consensus mechanism are met. Many applications built on Ethereum rely on this property when making decisions, such as crediting a user's account after they deposit funds.

## OP Stack finality

OP Stack chains in the standard configuration are Rollups that use Ethereum's consensus mechanism to order and finalize transactions rather than running a separate consensus protocol. Therefore, OP Stack chains inherit Ethereum's ordering and finality properties.

## Soft and hard finality

From a user's or application's point of view, two moments matter:

* **Soft finality:** The Sequencer has processed your transaction and included it in a block. From this point the transaction's outcome is known and the resulting chain state can be computed, and in practice the Sequencer will not reorder it: reorgs of the Sequencer's own blocks are extremely rare. Applications that trust the Sequencer can act on the transaction immediately, typically within about 2 seconds of submission on OP Mainnet. On chains that stream [Subblocks](/op-stack/features/subblocks), applications can act even earlier on a preconfirmation, 200 milliseconds after submission.
* **Hard finality:** The transaction's data has been published to Ethereum and the Ethereum block containing it has been finalized by Ethereum's consensus mechanism. From this point the transaction is as final as an ordinary Ethereum transaction: reversing it would require breaking Ethereum's own finality guarantees. On OP Mainnet this typically happens within about 15 to 30 minutes of submission.

Soft finality comes with a trust assumption that you should understand: it relies on a single Sequencer, operated by the chain operator. Until the transaction's data lands on Ethereum, the Sequencer is technically able to reorg the transaction away, even though this essentially never happens in practice. If you do not trust the Sequencer, wait until the transaction's data is on Ethereum: from that point the ordering is fixed by Ethereum and no longer depends on the Sequencer.

That in-between moment is worth knowing on its own. Once the transaction's data is included in an Ethereum block, sequencer trust is no longer required for ordering, but the Ethereum block itself can still, in principle, reorg until Ethereum finalizes it. Hard finality removes that last caveat.

## How this maps to protocol terms

Under the hood, OP Stack nodes track three states: **unsafe**, **safe**, and **finalized**. The word "unsafe" can give people pause, but it is simply the protocol's technical term for the soft finality stage described above: the transaction is in a block whose data has not yet been posted to Ethereum. These are the labels that OP Stack nodes expose over JSON-RPC: the unsafe head is served as the `latest` block, and the safe and finalized heads back the `safe` and `finalized` block tags.

| What you see                                                                              | Protocol term (RPC block tag) | Typical time on OP Mainnet | What you are trusting                                                |
| ----------------------------------------------------------------------------------------- | ----------------------------- | -------------------------- | -------------------------------------------------------------------- |
| Subblock preconfirmation, on chains that stream [Subblocks](/op-stack/features/subblocks) | pending state                 | \~200 milliseconds         | The Sequencer                                                        |
| Soft finality: the transaction is in an L2 block                                          | unsafe (`latest`)             | \~2 seconds                | The Sequencer                                                        |
| The transaction's data is in an Ethereum block                                            | safe (`safe`)                 | A few minutes              | Ethereum ordering; the block could still reorg until it is finalized |
| Hard finality: Ethereum finalizes the block containing the data                           | finalized (`finalized`)       | \~15 to 30 minutes         | Ethereum's consensus and finality guarantees                         |

## The journey from soft finality to hard finality

1. A user submits a transaction to the network, which forwards it to the Sequencer.
2. The Sequencer includes the transaction in an L2 block and distributes that block over a public peer-to-peer network. This is **soft finality**, and the protocol marks the block **"unsafe"** because its data has not yet been posted to Ethereum. This typically takes a few seconds from transaction submission (OP Mainnet produces a new block every 2 seconds). On chains that stream [Subblocks](/op-stack/features/subblocks), applications can additionally act on a preconfirmation 200 milliseconds after submission, before the full block is published.
3. The chain's batcher publishes the block's data to Ethereum, either as [blob data](https://www.eip4844.com/) or as calldata attached to a standard Ethereum transaction. Once that data is included in an Ethereum block, the protocol marks the block **"safe"**: the transaction's ordering no longer depends on the Sequencer. How long this takes depends on the chain's batcher configuration and throughput: high-throughput chains such as OP Mainnet fill their batches quickly and post to Ethereum every few minutes, while chains tuned for lower data costs may hold data back for up to their configured maximum channel duration, which can be several hours. The protocol's sequencing window (12 hours in the standard configuration) is the hard upper bound for this step.
4. The Ethereum block containing the batch data is finalized by [Ethereum's consensus mechanism](https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality). This is **hard finality**, the protocol's **"finalized"** state. Ethereum finalizes blocks in epochs of 6.4 minutes, and under normal conditions an Ethereum block is finalized roughly two to three epochs (about 13 to 19 minutes) after it is proposed. Finality can take longer during adverse network conditions on Ethereum. Adding this to the batch submission step, a transaction on OP Mainnet typically reaches the finalized state within about 15 to 30 minutes of submission; on chains that post batches less frequently, the wait is dominated by the batch submission interval.

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Network
    participant Sequencer
    participant Ethereum

    User->>Network: Submit transaction
    Network->>Sequencer: Forward transaction
    Sequencer->>Sequencer: Include transaction in block
    Sequencer->>Network: Distribute block over P2P network
    Note right of Sequencer: Soft finality (protocol term "unsafe")<br/>Data not yet posted to Ethereum<br/>~a few seconds, trusting the Sequencer

    Sequencer->>Ethereum: Batcher publishes block data<br/>(as blob data or calldata)
    Note right of Ethereum: Data on Ethereum (protocol term "safe")<br/>Ordering no longer depends on the Sequencer<br/>minutes on OP Mainnet, depends on batcher configuration

    Ethereum->>Ethereum: Finalize block containing the batch<br/>(~2 to 3 epochs)
    Note right of Ethereum: Hard finality (protocol term "finalized")<br/>~13 to 19 minutes after the batch lands<br/>guaranteed by Ethereum consensus
```

## Common misconceptions

### Transactions take 7 days to finalize

A common misconception is that transactions on OP Stack chains take 7 days to finalize. **This is incorrect.** Transactions on OP Stack chains become finalized when their data is included in a finalized Ethereum block, typically about 15 to 30 minutes after submission on OP Mainnet. To reorg a finalized OP Stack chain transaction, a reorg of the corresponding Ethereum block would be required.

This misconception often arises due to the OP Stack's Standard Bridge, which includes a 7-day delay on *withdrawals* of ETH and ERC-20 tokens. Withdrawing tokens from an OP Stack chain to Ethereum using the Standard Bridge requires a minimum 7-day wait. This delay affects only withdrawals through the Standard Bridge and does not impact transaction finality on the OP Stack chain.

### Challenges in the Standard Bridge can cause a chain reorg

Another misconception related to the belief that [finalization takes 7 days](#transactions-take-7-days-to-finalize) is that **Fault Proof challenges** created in response to withdrawals in the Standard Bridge can reorganize the OP Stack chain. **This is incorrect.** OP Stack transactions are not reorganized in response to Fault Proof challenges.

The [Standard Bridge](/app-developers/guides/bridging/standard-bridge) is a bridge application that is included by default with any OP Stack chain and connects the chain to its "parent" blockchain (usually Ethereum). It offers a high level of security for ETH and ERC-20 tokens moved through the bridge.

When using the Standard Bridge, users who send ETH or ERC-20 tokens to Ethereum must first burn those tokens on the OP Stack chain and then create a **withdrawal claim** on Ethereum.

Because the Standard Bridge cannot immediately verify withdrawal claims, it delays the claim by 7 days to allow the OP Stack Fault Proof system to filter out any invalid claims. Challenges only remove bad claims without affecting the Standard Bridge or the OP Stack chain.

### The Sequencer can always reorg the chain

A common misconception is that the Sequencer can trigger reorganizations of the OP Stack chain at any time. However, while the Sequencer can reorganize **"unsafe"** blocks (not yet published to Ethereum), reorganizations become more challenging once blocks are **"safe"** and become effectively impossible once blocks are **"finalized."** This is the flip side of soft finality's trust assumption: the window in which sequencer trust matters closes as soon as the data lands on Ethereum.

* **Unsafe blocks:** The Sequencer can reorganize these blocks until their data lands on Ethereum. That window is typically minutes on OP Mainnet and can be as long as the batch submission interval on chains that post batches less frequently.
* **Safe blocks:** The Sequencer would need to trigger a reorg on Ethereum itself, which is complex and unlikely.
* **Finalized blocks:** Once blocks are included in a finalized Ethereum block, the Sequencer cannot reorganize them without compromising Ethereum's finality guarantees.

### Ethereum reorgs cause OP Stack chain reorgs

If Ethereum experiences a reorg, OP Stack chains will attempt a graceful recovery. OP Stack nodes will downgrade **"safe"** transactions to **"unsafe"** if needed, while the Sequencer republishes transaction data to maintain chain continuity. Although extreme Ethereum network conditions could potentially affect the OP Stack chain, **"finalized"** OP Stack transactions are protected from reorgs.

## Conclusion

Transaction finality on the OP Stack is simpler than it may seem. Applications that trust the Sequencer get soft finality within seconds, and hard finality follows once Ethereum finalizes the transaction's data. OP Stack chains inherit Ethereum's finality guarantees, so once a transaction is **"finalized,"** it cannot be reversed.


# Transaction flow
Source: https://docs.optimism.io/op-stack/transactions/transaction-flow

Learn the transaction flow process for rollup transactions.

<Info>
  **Learn the OP Stack — stop 6 of 13.**
  You've deployed a chain and started its components. This page replays
  what you just ran as the life of a single transaction, from submission
  to finality on Ethereum. When you're done, continue to
  [Transaction fees on OP Mainnet](/op-stack/transactions/fees).
</Info>

This guide explains the transaction flow process for rollup transactions. The process for a rollup transaction has two requirements.

* The transaction needs to be written to L1 (Ethereum).
  This is typically performed by `op-batcher`, but any user can send an L1 transaction to submit an L2 transaction, in which case `op-batcher` is bypassed.

* The transaction needs to be executed to modify the state (by the execution client, `op-reth` by default).
  Afterwards, `op-proposer` writes a [commitment](https://en.wikipedia.org/wiki/Commitment_scheme) to the post-transaction state to L1.
  Note that `op-proposer` does not need to write a commitment after each transaction to L1; it is OK to commit to the state after a block of transactions.

<img alt="Overall process." />

## Writing the transaction to L1

[`op-batcher`](https://github.com/ethereum-optimism/optimism/tree/develop/op-batcher) has two main jobs:

* Compress transactions into batches.
* Post those batches to L1 to ensure availability and integrity.

### Compression

The batcher aggregates [sequencer batches](https://specs.optimism.io/glossary.html?utm_source=op-docs\&utm_medium=docs#sequencer-batch) into [channels](https://specs.optimism.io/glossary.html?utm_source=op-docs\&utm_medium=docs#channel).
This allows for more data per compression frame, and therefore a better compression ratio.
You can read more about this process [in the specs](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#batch-submission).

When a channel is full or times out it is compressed and written.

The maximum time that a channel can be open, from the first transaction to the last, is specified in units of L1 block time (so a value of 5 means 5\*12=60 seconds).
You can specify it either as an environment variable (`OP_BATCHER_MAX_CHANNEL_DURATION`) or a command line parameter (`--max-channel-duration`).
Alternatively, you can set it to zero (the default) to avoid posting smaller, less cost efficient transactions.

A channel is full when the anticipated compressed size is the target L1 transaction size.
This is controlled by two parameters:

1. The target L1 transaction size, which you can specify in bytes on the command line (`--target-l1-tx-size-bytes`) or as an environment variable (`OP_BATCHER_TARGET_L1_TX_SIZE_BYTES`)

2. The expected compression ratio, which you can specify as a decimal value, again either on the command line (`--approx-compr-ratio`) or as an environment variable (`OP_BATCHER_APPROX_COMPR_RATIO`).

You can see the code that implements this process in [`channel_manager.go`](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/batcher/channel_manager.go) and [`channel_builder.go`](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/batcher/channel_builder.go).

### Posting to L1

When a channel is full it is posted, either as a single transaction or as multiple transactions (depending on data size) to L1.

Writing to L1 is what moves a processed L2 transaction through the protocol's finality states: **unsafe** (processed, but not written to L1 yet), **safe** (written to L1), and **finalized** (the L1 block containing it has been finalized by Ethereum).
For what these states mean and when you can rely on a transaction being irreversible, see [Transaction finality](/op-stack/transactions/transaction-finality).

You can see the code that builds the channels to be written to L1 in [`channel_out.go`](https://github.com/ethereum-optimism/optimism/blob/develop/op-node/rollup/derive/channel_out.go) and [`channel_builder.go`](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/batcher/channel_builder.go).
The transactions themselves are sent in [`op-batcher`'s main loop](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/batcher/driver.go#L489-L520), which calls [`publishStateToL1`](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/batcher/driver.go#L784)

#### Determining the status of a transaction

This is the procedure to see a transaction's status.
The directions here are for [Foundry](https://book.getfoundry.sh/), but the concept is the same regardless of the method you use.

1. Get the number of the L2 block in which the transaction is recorded.

   ```sh theme={null}
   export ETH_RPC_URL=<URL to Optimism network>
   cast tx <transaction hash> blockNumber
   ```

2. Get the number of the latest finalized block.
   If the result is greater than or equal to the block number of the transaction, the transaction is finalized.

   ```sh theme={null}
   cast block finalized --field number
   ```

3. Get the number of the latest safe block.
   If the result is greater than or equal to the block number of the transaction, the transaction is safe.

   ```sh theme={null}
   cast block safe --field number
   ```

4. If the transaction isn't finalized or safe, it's unsafe.

## State processing

State processing can be divided into two steps:

1. Applying the transaction to the old state to produce the new state, which is performed by the execution client (`op-reth` by default).

2. Proposing the new [Merkle root](https://en.wikipedia.org/wiki/Merkle_tree) of the state.
   Merkle roots are used because the actual state is long and would cost too much to write to L1.
   This step is performed by `op-proposer`.

### State changes

The state is stored and modified by the execution client. The default is [`op-reth`](https://github.com/paradigmxyz/reth).

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

### State root proposals

The state root proposals are posted by [`op-proposer`](https://github.com/ethereum-optimism/optimism/tree/develop/op-proposer) to [`L2OutputOracle`](https://github.com/ethereum-optimism/optimism/blob/233ede59d16cb01bdd8e7ff662a153a4c3178bdd/packages/contracts-bedrock/contracts/L1/L2OutputOracle.sol) (as of `233ede5`) on L1.

Output proposals are *not* immediately valid.
They can only be considered authoritative once the fault challenge period has passed; see [Withdrawal flow](/op-stack/bridging/withdrawal-flow) for how output roots are used to prove and finalize withdrawals.


# Releases
Source: https://docs.optimism.io/releases/index

Latest stable releases for all OP Stack components. Select a component to view its full release history.

<Info>
  We always recommend running the latest stable release for each component. Select a component below to view its full release history and changelog.
</Info>

## Latest Releases

<CardGroup>
  <Card title="op-node v1.19.4" href="/releases/op-node" icon="cube">
    Released August 3, 2026
  </Card>

  <Card title="kona-node v1.6.3" href="/releases/kona-node" icon="circle-nodes">
    Released August 3, 2026
  </Card>

  <Card title="op-reth v2.4.1" href="/releases/op-reth" icon="bolt">
    Released July 31, 2026
  </Card>

  <Card title="op-batcher v1.16.12" href="/releases/op-batcher" icon="layer-group">
    Released August 3, 2026
  </Card>

  <Card title="op-proposer v1.16.3" href="/releases/op-proposer" icon="stamp">
    Released May 23, 2026
  </Card>

  <Card title="op-challenger v1.9.4" href="/releases/op-challenger" icon="shield">
    Released July 22, 2026
  </Card>

  <Card title="op-contracts v7.0.0" href="/releases/op-contracts" icon="file-code">
    Released June 25, 2026
  </Card>

  <Card title="op-conductor v0.9.4" href="/releases/op-conductor" icon="sliders">
    Released May 18, 2026
  </Card>

  <Card title="kona-client v1.6.0" href="/releases/kona-client" icon="microchip">
    Released June 19, 2026
  </Card>

  <Card title="kona-host v1.6.0" href="/releases/kona-host" icon="server">
    Released June 19, 2026
  </Card>

  <Card title="op-deployer v0.7.1" href="/releases/op-deployer" icon="rocket">
    Released June 26, 2026
  </Card>

  <Card title="proxyd v4.30.0" href="/releases/proxyd" icon="network-wired">
    Released July 27, 2026
  </Card>

  <Card title="op-acceptor v3.10.2" href="/releases/op-acceptor" icon="circle-check">
    Released March 6, 2026
  </Card>
</CardGroup>


# kona-client Releases
Source: https://docs.optimism.io/releases/kona-client

Release history for kona-client. Rust fault proof client binary.

**kona-client** is the bare-metal fault proof program that executes the OP Stack state transition on a MIPS prover. It is the primary fault proof program for OP Stack chains. See the [fault proof specs](https://specs.optimism.io/fault-proof/index.html).

<Update label="June 19, 2026" description="v1.6.0">
  > ⚠️ **This release is a critical security fix and is a required update for users.**

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-client/v1.6.0)
</Update>

<Update label="May 25, 2026" description="v1.5.2">
  ## Overview

  This is a patch release of kona-client. It bumps FPVM precompile oracle gas for Glamsterdam (EIP-7904), tightens the interop trace-extension boundary to match op-program, and surfaces malformed output-root preimages explicitly. It is required before Glamsterdam activates on L1; otherwise optional.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-client/v1.5.2)
</Update>

<Update label="May 12, 2026" description="v1.5.1">
  ## Overview

  > \[!IMPORTANT]
  > This release assumes MSRV >= 1.94. You may use [https://github.com/ethereum-optimism/optimism/releases/tag/kona-client%2Fv1.2.14](https://github.com/ethereum-optimism/optimism/releases/tag/kona-client%2Fv1.2.14) for users not supporting this rust version yet.

  > \[!CAUTION]
  > ⚠️ This release is a critical security fix and is a required update for users `kona-client`.

  This is a patch release of `kona-client` that includes important bug fixes for state trie handling of destroyed accounts.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-client/v1.5.1)
</Update>

<Update label="May 12, 2026" description="v1.2.14">
  ## Overview

  ⚠️ This release is a critical security fix and is a required update for users of `kona-client/v1.2.13`.

  This is a patch release of kona-client that includes important bug fixes for state trie handling of destroyed accounts.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-client/v1.2.14)
</Update>


# kona-host Releases
Source: https://docs.optimism.io/releases/kona-host

Release history for kona-host. Rust fault proof host binary.

**kona-host** runs natively alongside the prover, serving as the [Preimage Oracle](https://specs.optimism.io/fault-proof/index.html) server that supplies chain data to kona-client during proof execution.

<Update label="June 19, 2026" description="v1.6.0">
  > ⚠️ **This release is a critical security fix and is a required update for users.**

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-host/v1.6.0)
</Update>

<Update label="May 25, 2026" description="v1.5.2">
  ## Overview

  This is a patch release of kona-host that adds defense-in-depth verification of preimage bytes against the requested key. It is an optional upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-host/v1.5.2)
</Update>

<Update label="May 12, 2026" description="v1.5.1">
  ## Overview

  > \[!CAUTION]
  > ⚠️ This release is a critical security fix and is a required update for users `kona-host`.

  This is a minor release of `kona-host` that includes important bug fixes for state trie handling of destroyed accounts.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-host/v1.5.1)
</Update>


# kona-node Releases
Source: https://docs.optimism.io/releases/kona-node

Release history for kona-node. Rust implementation of the OP Stack rollup node.

**kona-node** is a Rust implementation of the [rollup-node spec](https://specs.optimism.io/protocol/rollup-node.html), backed by kona-derive. It is a Rust-native alternative to op-node.

<Update label="August 3, 2026" description="v1.6.3">
  > \[!WARNING]
  > **Security fix — upgrade recommended.** This release closes three unauthenticated attack surfaces ([#21753](https://github.com/ethereum-optimism/optimism/pull/21753))
  > and hardens gossip by binding the message-id to the topic and metering invalid messages ([#21804](https://github.com/ethereum-optimism/optimism/pull/21804)).

  > \[!IMPORTANT]
  > Derivation correctness: span-batch transaction type prefixes are now preserved ([#21808](https://github.com/ethereum-optimism/optimism/pull/21808)).

  > \[!IMPORTANT]
  > **APKO Docker images:** Starting with this release, the Docker URL contains an additional `/nexus` in its path, see full Docker image path below. Our Docker builds are now APKO based and during a transition period, the APKO-based images for any component will be available at `https://us-docker.pkg.dev/oplabs-tools-artifacts/images/nexus/<component>:<version>`. When we migrate to APKO-only images, we may remove the `/nexus` again from our image paths and will give another notice in this case.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.6.3)
</Update>

<Update label="July 20, 2026" description="v1.6.2">
  > \[!NOTE]
  > **Recommended upgrade for fault-proof operators.** Fixes precompile gas accounting in the fpvm provider — gas is fully spent on precompile halt ([#21634](https://github.com/ethereum-optimism/optimism/pull/21634)) and out-of-gas on overspend is handled gracefully ([#21582](https://github.com/ethereum-optimism/optimism/pull/21582)). Registry config decoding is now strict (`deny_unknown_fields`, [#21648](https://github.com/ethereum-optimism/optimism/pull/21648)): unknown keys fail loudly; custom registry data with unmodeled keys will no longer load. Remaining changes are kona-sp1 proof-program scaffolding with no node-facing impact.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.6.2)
</Update>

<Update label="June 26, 2026" description="v1.6.1">
  > \[!Warning]
  > **This is a mandatory release for all node operators.** It includes the [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork. (as of `c90d86d`)
  >
  > The following Mainnet chains will activate on **1783526401 (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder:** op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  > \[!IMPORTANT]
  > **Operators must use op-reth/v2.3.2 with this release.** Prior versions of op-reth will not work with this version of kona-node after Karst due to a new engine API method (`getPayloadV5`) used after Karst. See the [notice page](https://docs.optimism.io/notices/upgrade-19) for more details about recommended versions (including flashblocks components).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.6.1)
</Update>

<Update label="June 2, 2026" description="v1.6.0">
  > \[!WARNING]
  > This is a mandatory release for all node operators. It includes [Sepolia](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/sepolia/op.toml#L25) and [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork.  (as of `c90d86d`)
  >
  > **Operators must upgrade before the scheduled hard fork times.**
  >
  > The following Sepolia chains will activate on **`1781712001` (Wed Jun 17 2026 16:00:01 UTC)**: op, ink, zora, mode, lisk, metal, unichain, soneium-minato, ethernity, creator-chain-testnet
  >
  > The following Mainnet chains will optimistically activate on **`1783526401` (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder**: op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  Besides the Karst hardfork timestamps, this release also includes a few bug fixes.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.6.0)
</Update>

<Update label="May 19, 2026" description="v1.5.2">
  > \[!NOTE]
  > **Optional upgrade.** This upgrade contains some small fixes and improvements to the `kona-protocol` crates.

  Generating release notes for kona-node/v1.5.1..kona-node/v1.5.2

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.5.2)
</Update>

<Update label="May 18, 2026" description="v1.5.1">
  This is a recommended release with bug fixes and stability improvements.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.5.1)
</Update>

<Update label="May 11, 2026" description="v1.5.0">
  This is a bug-fix release of kona-node.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.5.0)
</Update>

<Update label="April 29, 2026" description="v1.4.0">
  This release includes updates to Nut Bundles, version updates, bug fixes, and the removal of deprecated Protocol Versions.

  This version includes Superchain Registry updates for Worldchain and is a required update for that network

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.4.0)
</Update>

<Update label="April 21, 2026" description="v1.3.0">
  > \[!IMPORTANT]
  > This is a strongly recommended release as it fixes various bugs in the derivation pipeline.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.3.0)
</Update>

<Update label="April 13, 2026" description="v1.2.15">
  This is a recommended release containing correctness and stability fixes for kona-node.

  ## What's Changed in kona-node/v1.2.15

  * fix(kona/protocol): add bounds checks in `read_tx_data` for truncated and oversized payloads, preventing malformed payload panics and aligning behavior with op-node
    ([#19904](https://github.com/ethereum-optimism/optimism/pull/19904))
  * fix(kona/derive): reset the indexed traversal pipeline on Holocene activation so interop clients apply required system config updates correctly ([#19905](https://github.com/ethereum-optimism/optimism/pull/19905))
  * fix(kona-node): handle a missing L1 origin block in the sequencer by recovering with an engine reset instead of panicking ([#19945](https://github.com/ethereum-optimism/optimism/pull/19945))
  * fix(kona): use deterministic `BTreeMap` JSON serialization in the interop host to avoid cross-process divergence in serialized preimages ([#19906](https://github.com/ethereum-optimism/optimism/pull/19906))
  * fix(kona): improve interop consolidation by sending the `L2Transactions` hint before trie walks, skipping re-validation of deposit-only replacement blocks, and removing an obsolete replacement deposit transaction
    ([#19850](https://github.com/ethereum-optimism/optimism/pull/19850), [#19890](https://github.com/ethereum-optimism/optimism/pull/19890), [#19894](https://github.com/ethereum-optimism/optimism/pull/19894))
  * feat!(rust): upgrade core Rust dependencies, including alloy-evm and reth, for the kona workspace ([#19854](https://github.com/ethereum-optimism/optimism/pull/19854))
  * refactor(kona): remove native rollup-boost support from kona-node; operators that rely on rollup-boost should run it as a standalone sidecar and point kona-node’s L2 engine URL at it
    ([#19900](https://github.com/ethereum-optimism/optimism/pull/19900))
  * fix(kona-proof-interop): improve rollup config warnings to report only missing chain IDs ([#19729](https://github.com/ethereum-optimism/optimism/pull/19729))

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/kona-node/v1.2.14...kona-node/v1.2.15](https://github.com/ethereum-optimism/optimism/compare/kona-node/v1.2.14...kona-node/v1.2.15)

  🚢 Docker Image: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:v1.2.15](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:v1.2.15)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.2.15)
</Update>

<Update label="April 2, 2026" description="v1.2.14">
  ## What's Changed in kona-node/v1.2.14

  * fix(kona/derive): use walked-back system config on pipeline reset by @sebastianst in [#19792](https://github.com/ethereum-optimism/optimism/pull/19792)
  * fix(op-alloy): resolve `NetworkWallet` conflict with alloy 1.8 by @suchapalaver in [#19756](https://github.com/ethereum-optimism/optimism/pull/19756)
  * feat(op-reth): Drop interop transactions after reorg by @wwared in [#19814](https://github.com/ethereum-optimism/optimism/pull/19814)
  * feat(kona-host): add directory-based kv store compatible with op-program by @ajsutton in [#19803](https://github.com/ethereum-optimism/optimism/pull/19803)
  * chore(kona): remove dead interop\_message\_expiry\_window from RollupConfig by @digorithm in [#19810](https://github.com/ethereum-optimism/optimism/pull/19810)
  * fix(kona): use configurable message expiry window in MessageGraph by @digorithm in [#19765](https://github.com/ethereum-optimism/optimism/pull/19765)
  * fix(kona/proof): several fixes to kona-proof. by @theochap in [#19775](https://github.com/ethereum-optimism/optimism/pull/19775)
  * chore(rust): misc clippy fixes on crates by @mablr in [#19736](https://github.com/ethereum-optimism/optimism/pull/19736)
  * ci: use cargo-auditable for Rust image builds by @falcorocks in [#19770](https://github.com/ethereum-optimism/optimism/pull/19770)
  * feat(op-alloy-evm): add `OpEvm::into_inner` method by @mablr in [#19735](https://github.com/ethereum-optimism/optimism/pull/19735)
  * feat(op-devstack): respect DEVSTACK\_L2EL\_KIND and DEVSTACK\_L2CL\_KIND in all single-chain runtimes by @joshklop in [#19653](https://github.com/ethereum-optimism/optimism/pull/19653)

  Operator note: interop\_message\_expiry\_window was removed from RollupConfig. Any existing serialized configs or fixtures that still include this field may fail to deserialize and should be updated before rollout.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.2.14)
</Update>

<Update label="March 31, 2026" description="v1.2.13">
  This is an optional release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.2.13)
</Update>

<Update label="March 17, 2026" description="v1.2.12">
  ## What's Changed in kona-node/v1.2.12

  > \[!NOTE]
  > This release contains fixes to the derivation pipeline to guard against malicious behavior from the op-batcher

  * chore(cannon): migrate Makefile to justfile by @ajsutton in [#19474](https://github.com/ethereum-optimism/optimism/pull/19474)
  * fix(kona/derive): add over-fill check in BlobSource::load\_blobs by @ajsutton in [#19364](https://github.com/ethereum-optimism/optimism/pull/19364)
  * fix(kona/derive): make syscfg update failure non-fatal in L1Traversal by @ajsutton in [#19358](https://github.com/ethereum-optimism/optimism/pull/19358)
  * fix(kona/derive): return Reset instead of Critical on blob under-fill in BlobData::fill by @ajsutton in [#19362](https://github.com/ethereum-optimism/optimism/pull/19362)
  * fix(kona/derive): copy origin field during Holocene BatchQueue→BatchValidator transition by @ajsutton in [#19360](https://github.com/ethereum-optimism/optimism/pull/19360)
  * fix(kona/protocol): add bounds checks in span batch decode to prevent panics on truncated input by @ajsutton in [#19361](https://github.com/ethereum-optimism/optimism/pull/19361)
  * fix(kona/derive): accept EIP-4844 type-3 batcher txs in CalldataSource by @ajsutton in [#19355](https://github.com/ethereum-optimism/optimism/pull/19355)
  * kona(derive): remove dead EthereumDataSourceVariant file by @ajsutton in [#19341](https://github.com/ethereum-optimism/optimism/pull/19341)
  * feat(kona): add Karst hardfork support by @maurelian in [#19372](https://github.com/ethereum-optimism/optimism/pull/19372)
  * chore(kona): remove deprecated supervisor crates by @theochap in [#19290](https://github.com/ethereum-optimism/optimism/pull/19290)
  * op-reth: bump reth/op-reth to v1.11.1 and MSRV to 1.92 by @theochap in [#19292](https://github.com/ethereum-optimism/optimism/pull/19292)

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/kona-node/v1.2.11-rc.2...kona-node/v1.2.12](https://github.com/ethereum-optimism/optimism/compare/kona-node/v1.2.11-rc.2...kona-node/v1.2.12)

  🚢 Docker Image: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:v1.2.12](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/kona-node:v1.2.12)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.2.12)
</Update>

<Update label="March 6, 2026" description="v1.2.11">
  > \[!TIP]
  > This is an essential release. It fixes two bugs which can cause a safe head stall if there is an L1 re-org.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.2.11)
</Update>

<Update label="March 3, 2026" description="v1.2.10">
  ## Description

  First official release of `kona-node` in the optimism monorepo.

  > \[!NOTE]
  > This is an optional release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/kona-node/v1.2.10)
</Update>


# op-acceptor Releases
Source: https://docs.optimism.io/releases/op-acceptor

Release history for op-acceptor. Network acceptance tester for OP Stack devnets.

**op-acceptor** runs validation checks against a network to determine if it is ready for production, executing standard Go tests against configurable gate-based validation scenarios.

<Update label="March 6, 2026" description="v3.10.2">
  ## Changelog

  * 6b0f7b226475bf0a8b20f76ef92ac170d1b9399a fix(op-acceptor): skip RunAll package when all tests excluded by --exclude-gates (#565)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.10.2)
</Update>

<Update label="March 4, 2026" description="v3.10.1">
  ## Changelog

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.10.1)
</Update>

<Update label="March 3, 2026" description="v3.9.0">
  ## Changelog

  * a8232d28edfda958e324beefccf114b383610527 feat(op-acceptor): add linux/arm64 release binary (#555)
  * 09728d0b284229ca8f73127d7da7685126d5305c feat(op-acceptor): sort tests by previous runtime to front-load longest tests (#557)
  * 383e9df37bc27879d15e4cb5ba3d63bb3a78ff5e fix: op-acceptor base image (#554)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.9.0)
</Update>

<Update label="February 17, 2026" description="v3.9.0-rc.3">
  ## Changelog

  * a170939abdd0e813852023db71862cb09e671795 fix(op-acceptor): improve CI split logging to clarify algorithm selection

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.9.0-rc.3)
</Update>

<Update label="February 17, 2026" description="v3.9.0-rc.2">
  ## Changelog

  * 3c1b265b2934b6aa6c207bf611848acde26b67c6 feat(op-acceptor): add CI parallelism splitting and report-from-events mode
  * 656450a11c291085a6ea0b39780f760a447e71e7 feat(op-acceptor): add timing-based bin-packing for CI test splitting

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.9.0-rc.2)
</Update>

<Update label="February 17, 2026" description="v3.9.0-rc.1">
  ## Changelog

  * 1ec0c4094b9efb10c1e7286d5e9c385cb7a8f778 feat(op-acceptor): add CI parallelism splitting and report-from-events mode

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.9.0-rc.1)
</Update>

<Update label="February 9, 2026" description="v3.8.3">
  ## Changelog

  * b2573048a696ee068ab89947fc1705798af6e22a op-acceptor: Capture logs during test run. (#548)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.8.3)
</Update>

<Update label="January 21, 2026" description="v3.8.2">
  ## Changelog

  * 43f5d14f9c17904c804969feec1f966a5f3288b0 fix(ci): goreleaser; make latest release. (#527)
  * 7d273b35d569a76e6ff12161cced642e13edb84d fix(op-acceptor): ensure logs are written to disk for timeout cases (#540)
  * cd3f7f0be90e97c0fb0e42250d2ad1c4d6cbb933 fix(op-acceptor): tests; TestCLIServiceFlag (#528)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.8.2)
</Update>

<Update label="December 10, 2025" description="v3.8.1">
  ## Changelog

  * 0f0d34fcbe02ac43378edfe1580fbe6ef2957bd9 fix(op-acceptor): subtest logging memory leak (#526)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.8.1)
</Update>

<Update label="December 6, 2025" description="v3.8.0">
  ## Changelog

  * bd1e020c818f23d0a557d6b068c847f51f5555ff fix(op-acceptor): Stream stdout to disk and refactor raw JSON logging (#525)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.8.0)
</Update>

<Update label="December 6, 2025" description="v3.7.0">
  ## Changelog

  * e6c87418f0197bbd4079afd02be031d29cb59fa5 feat(op-acceptor): add multigate and dry-run (#520)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.7.0)
</Update>

<Update label="November 13, 2025" description="v3.6.6">
  ## Changelog

  * 741aecf2c611ad00447f784d8bb5e33bce3a8d3a chore(op-acceptor): v3.6.6 (#509)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.6.6)
</Update>

<Update label="November 12, 2025" description="v3.6.5-rc.2">
  ## Changelog

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.6.5-rc.2)
</Update>

<Update label="October 31, 2025" description="v3.6.2">
  ## Changelog

  * 2256f8a9e6eb5cf2e88defe1dec185bab63720ba feat: metrics improvements to op-acceptor (#503)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.6.2)
</Update>

<Update label="October 30, 2025" description="v3.6.1">
  ## Changelog

  * 2faae1f4365be2f79b3f8ccb3526c7d58f4e8e04 chore(op-acceptor): readme; path semantics (#496)
  * 1721c99cd82edee62621c7c9ba82751f0cc1b307 clean(op-acceptor): subtest timeouts refactor (#500)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.6.1)
</Update>

<Update label="October 13, 2025" description="v3.6.0">
  ## Changelog

  * 723f94a33a04058bbbe4f388705f426e5785ca28 feat(op-acceptor): max concurrency & log tweaks (#489)
  * 837051041f9a3c620644c6721e7b5e189f4257ff feat(op-acceptor): stricter exclude-gates. (#490)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.6.0)
</Update>

<Update label="October 6, 2025" description="v3.5.0">
  ## Changelog

  * dcb7a577c65c381ad6aeeb6ba35bfda1fbde9e73 chore: fix comment (#486)
  * 9912ef0fc2083594ce2a88f1353a65083cfac7a3 chore: remove unused min func (#476)
  * 0ef294beca024a689069fb0cbc8e31cda830ac6b feat(op-acceptor): logging; improved ansi stripping (#478)
  * 9c6ea48d2f50f5dd5024ec020eef20a2c33b5808 feat(op-acceptor): skip gates. (#485)
  * e9cfcec8df8dc279cbaa358640da8098758fb97d feat(op-acceptor): test; env passthrough. (#483)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.5.0)
</Update>

<Update label="September 25, 2025" description="v3.4.2">
  ## Changelog

  * 11a139c36ec7a57497b4dc7d515a0157a430d25c feat(op-acceptor): flake shake (#475)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.4.2)
</Update>

<Update label="September 24, 2025" description="v3.3.2">
  ## Changelog

  * 6165b5165151278f1e3936ab0de56033e1002e96 feat(acceptance-tests): adds simple acceptance tests (#470)
  * 7acba90c271a3f4edbdb6a5ecc96952ef7c424bc fix(op-acceptor): logging improvements (#474)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.3.2)
</Update>

<Update label="September 18, 2025" description="v3.3.1">
  ## Changelog

  * e349f0f3ca8574cdc4f85623b5a74b9688a186bd fix(op-acceptor): package timeouts. (#468)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/op-acceptor/v3.3.1)
</Update>


# op-batcher Releases
Source: https://docs.optimism.io/releases/op-batcher

Release history for op-batcher. L2 batch submitter.

**op-batcher** is responsible for data availability — it reads unsafe blocks from the sequencer and posts transaction batches to the DA layer (L1 or Alt DA). See the [batcher spec](https://specs.optimism.io/protocol/batcher.html).

<Update label="August 3, 2026" description="v1.16.12">
  > \[!NOTE]
  > **Optional upgrade — no functional changes.** This release contains no behavioural changes to op-batcher.
  > It is published to keep op-batcher aligned with the rest of the op-stack release, and carries only a
  > refactor moving shared `DepositTx` and transaction helpers into `op-core`.

  > \[!IMPORTANT]
  > **APKO Docker images:** Starting with this release, the Docker URL contains an additional `/nexus` in its path, see full Docker image path below. Our Docker builds are now APKO based and during a transition period, the APKO-based images for any component will be available at `https://us-docker.pkg.dev/oplabs-tools-artifacts/images/nexus/<component>:<version>`. When we migrate to APKO-only images, we may remove the `/nexus` again from our image paths and will give another notice in this case.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.12)
</Update>

<Update label="July 20, 2026" description="v1.16.11">
  > \[!NOTE]
  > **Optional upgrade.** No op-batcher-specific changes — this release refreshes shared dependencies: Go 1.26.4 + dependency bumps for image CVE fixes ([#21452](https://github.com/ethereum-optimism/optimism/pull/21452), [#21450](https://github.com/ethereum-optimism/optimism/pull/21450)), a txmgr fix suppressing a spurious receipt-missing log after successful sends ([#21317](https://github.com/ethereum-optimism/optimism/pull/21317)), and Karst/Lagoon hardfork plumbing in shared packages. Recommended to pick up the CVE-motivated image refresh.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.11)
</Update>

<Update label="June 5, 2026" description="v1.16.10">
  Generating release notes for op-batcher/v1.16.9..op-batcher/v1.16.10

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.10)
</Update>

<Update label="May 18, 2026" description="v1.16.9">
  This is an optional release containing only logging changes.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.9)
</Update>

<Update label="May 11, 2026" description="v1.16.8">
  This is a maintenance release of op-batcher.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.8)
</Update>

<Update label="April 13, 2026" description="v1.16.7">
  This release is optional.

  ## What's Changed in op-batcher/v1.16.7

  * all: upgrade op-geth, including shared tx-submission compatibility updates used by the batcher ([#19844](https://github.com/ethereum-optimism/optimism/pull/19844))
  * chore(deps): bump op-geth again to `v1.101702.1-rc.1` for this release candidate ([#19992](https://github.com/ethereum-optimism/optimism/pull/19992))
  * chore(deps): bump `google.golang.org/grpc` to `v1.79.3` ([#19749](https://github.com/ethereum-optimism/optimism/pull/19749))

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/op-batcher/v1.16.6...op-batcher/v1.16.7](https://github.com/ethereum-optimism/optimism/compare/op-batcher/v1.16.6...op-batcher/v1.16.7)

  🚢 Docker Image: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-batcher:v1.16.7](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-batcher:v1.16.7)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.7)
</Update>

<Update label="March 31, 2026" description="v1.16.6">
  This release is optional; however, we recommend updating as it includes a Go version upgrade addressing security fixes, along with enhanced container image hardening.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.6)
</Update>

<Update label="March 9, 2026" description="v1.16.5">
  This is an optional release that contains a metric bug fix.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.5)
</Update>

<Update label="February 13, 2026" description="v1.16.4">
  This is a recommended release containing:

  * A feature where the batcher can choose a smarter, dynamic blob tip cap to use, based on recent market activity on L1.
    The feature can be enabled by setting `OP_BATCHER_TXMGR_BLOB_TIP_CAP_DYNAMIC=true`. By default, the existing static blob tip cap will be used. For more details, see [https://github.com/ethereum-optimism/optimism/pull/18981](https://github.com/ethereum-optimism/optimism/pull/18981) and [https://github.com/ethereum-optimism/optimism/pull/18386](https://github.com/ethereum-optimism/optimism/pull/18386).
  * Several bugfixes and stability improvements.

  > \[!TIP]
  > If you use proxyd for the batcher's L1 connection, we recommend upgrading to [proxyd/v4.25.0](https://github.com/ethereum-optimism/infra/releases/tag/proxyd%2Fv4.25.0) (this contains a non-critical bugfix and avoids noisy warning logs being emitted by the batcher).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.4)
</Update>

<Update label="December 19, 2025" description="v1.16.3">
  This is an optional `op-batcher` release containing:

  * a new module for suggesting blob priority fee based on past blob transactions included in recent blocks. The new module is not active yet, currently it is only emitting logs comparing suggested fees with the configured fees for blob transactions.
  * a fix for `MaxChannelDuration` tracking for large block backlogs.
  * a fix for fully exiting the `op-batcher` process on critical throttling RPC errors.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.3)
</Update>

<Update label="November 6, 2025" description="v1.16.2">
  This update adds Jovian and Fusaka support to the batcher.

  The batcher needs to switch from submitting blob transactions with blob proofs to submitting blob transactions with cell proofs after the L1 activates the Fusaka fork. With this release the switchover moment can be set ahead of time with the `--txmgr.cell-proof-time` flag (removing the need for live operations around the Fusaka activation time).  See #17649 for details. For chains batching to Ethereum mainnet, the appropriate time to switch to cell proofs is inferred automatically and no flag needs to be set.

  > \[!NOTE]
  > **Please ensure the batcher is restarted at least once after op-node is upgraded, so it can load the latest rollup config at startup.**

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.2)
</Update>

<Update label="October 7, 2025" description="v1.16.0">
  > \[!WARNING]
  > **This is an essential release to prepare for the L1 Fusaka fork on Sepolia.**

  > \[!IMPORTANT]
  > The new flag`OP_BATCHER_TXMGR_ENABLE_CELL_PROOFS` must be set to "true" immediately after the Fusaka activation on L1.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.16.0)
</Update>

<Update label="August 21, 2025" description="v1.15.0">
  > \[!IMPORTANT]
  > **All chain operators are strongly encouraged to upgrade their batchers to improve throttling behavior and mitigate worst-case spam attack scenarios.**

  # Overview

  This release includes a major reworking of the batcher-sequencer DA throttling feature (allowing for smoother control of transaction and block size limits), a new admin RPC method to flush the batcher (causing it to submit a transaction as soon as possible) as well as several performance enhancements and bugfixes.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.15.0)
</Update>

<Update label="June 26, 2025" description="v1.14.0">
  This release contains:

  * a transaction rebroadcasting feature which helps batcher transactions get included with less delay and lower cost.
  * changes in the way the batcher interprets the sync status reported by the `op-node`
  * other small bugfixes

  > \[!WARNING]
  > Operators should upgrade sequencers to at least [op-node/v1.13.4](https://github.com/ethereum-optimism/optimism/releases/tag/op-node%2Fv1.13.4) when updating to this version of the batcher. See [#16413](https://github.com/ethereum-optimism/optimism/pull/16413).

  > \[!WARNING]
  > The transaction rebroadcasting feature is enabled by default. To disable this feature, set `TXMGR_REBROADCAST_INTERVAL` to `0`. See [#16310](https://github.com/ethereum-optimism/optimism/pull/16310).

  > \[!WARNING]
  > Rebroadcasting transactions can make memory spikes more likely. We recommend at least 4GB of memory for production deployments.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.14.0)
</Update>

<Update label="May 27, 2025" description="v1.13.2">
  This release contains an improvement to retry certain transaction submission errors more rapidly. It is an optional upgrade which improves the performance of the batcher.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.13.2)
</Update>

<Update label="May 14, 2025" description="v1.13.1">
  > \[!WARNING]
  > This release replaces `op-batcher/v1.13.0`

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.13.1)
</Update>

<Update label="May 12, 2025" description="v1.13.0">
  > \[!WARNING]
  > This release contained a CLI bug where the additional endpoints DA behavior would not activate. Please use [op-batcher/v1.13.1](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher%2Fv1.13.1)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.13.0)
</Update>

<Update label="April 3, 2025" description="v1.12.0">
  # Isthmus

  > \[!IMPORTANT]
  > Chain operators need to upgrade their batchers before Isthmus activates on their chains. It is an optional upgrade until then.

  This release adds support for `SetCode` transactions in (span) batches, which is a requirement for batching Isthmus chains.

  The Sepolia Superchain will activate Isthmus on Apr 17, so those chain operators need to upgrade their batchers by then. See the [`op-node/v1.13.0`](https://github.com/ethereum-optimism/optimism/releases/tag/op-node%2Fv1.13.0) release notes for more details on the Isthmus Sepolia activation.

  > \[!NOTE]
  > The Isthmus activation date for the Mainnet Superchain isn't set yet. It won't be before Ethereum Mainnet activates Pectra, so not before May 7, which is the current tentative Pectra activation date.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.12.0)
</Update>

<Update label="March 11, 2025" description="v1.11.5">
  ❗ This release fixes a bug where the batcher would potentially needlessly throttle the sequencer if it were to perform automatic reset following a backlog of data and transaction submission failures.

  It is recommended for all users to upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.11.5)
</Update>

<Update label="March 4, 2025" description="v1.11.4">
  ❗ We have had some reports of the batcher failing to post batches at all from version `v1.11.2` -- this is caused by the sequencer incorrectly reporting the `LocalSafeL2` field. This batcher release works around that issue.

  This is a recommended release for all users to upgrade to.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.11.4)
</Update>

<Update label="February 28, 2025" description="v1.11.3">
  🐞 **This version of the batcher uses the LocalSafeL2 field of the Sequencer's SyncStatus response, which is sometimes incorrectly reported as `0`, causing the batcher to behave incorrectly and fail to post fresh batches. Please upgrade to at least [`v1.11.4`](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher%2Fv1.11.4) to avoid this issue.**

  ‼️ This release contains a critical fix for the batcher's throttling feature, and it is recommended for all to upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.11.3)
</Update>

<Update label="March 13, 2024" description="v1.7.2-rc.3">
  # 🔴✨  Multi-Blob Batcher Pre-Release

  The op-batcher in this release candidate has the capabilities to send multiple blobs per single blob transaction. This is accomplished by the use of multi-frame channels, see the [specs](https://specs.optimism.io/protocol/derivation.html#frame-format) for more technical details on channels and frames.

  A minimal batcher configuration (with env vars) to enable 6-blob batcher transactions is:

  ```
        - OP_BATCHER_BATCH_TYPE=1 # span batches, optional
        - OP_BATCHER_DATA_AVAILABILITY_TYPE=blobs
        - OP_BATCHER_TARGET_NUM_FRAMES=6 # 6 blobs per tx
        - OP_BATCHER_TXMGR_MIN_BASEFEE=2.0 # 2 gwei, might need to tweak, depending on gas market
        - OP_BATCHER_TXMGR_MIN_TIP_CAP=2.0 # 2 gwei, might need to tweak, depending on gas market
        - OP_BATCHER_RESUBMISSION_TIMEOUT=240s # wait 4 min before bumping fees
  ```

  This enables blob transactions and sets the target number of frames to 6, which translates to 6 blobs per transaction. The min. tip cap and base fee are also lifted to 2 gwei because it is uncertain how easy it will be to get 6-blob transactions included and slightly higher priority fees should help. The resubmission timeout is increased to a few minutes to give more time for inclusion before bumping the fees, because current txpool implementations require a *doubling* of fees for blob transaction replacements.

  Multi-blob transactions are particularly interesting for medium to high-throughput chains, where enough transaction volume exists to fill up 6 blobs in a reasonable amount of time. You can use [the Tune batcher costs guide](/use-cases/tune-batcher-costs) for your chain to determine what number of blobs are right for you, and what gas scalar configuration to use. Please also refer to our [documentation](/chain-operators/guides/features/blobs) on Blobs for chain operators.

  🚢 **Docker image**: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-batcher:v1.7.2-rc.3](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-batcher:v1.7.2-rc.3)

  *A full `v1.7.2` release of the op-stack follows soon.*

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-batcher/v1.7.2-rc.3)
</Update>


# op-challenger Releases
Source: https://docs.optimism.io/releases/op-challenger

Release history for op-challenger. Dispute game challenger.

**op-challenger** is a modular dispute game agent that monitors and challenges invalid fault proof games on-chain. See the [fault proof specs](https://specs.optimism.io/fault-proof/index.html).

<Update label="July 22, 2026" description="v1.9.4">
  ## Overview

  This is a patch release of op-challenger containing new features and bug fixes. It is an optional but recommended upgrade for all users.

  Note: ZK dispute games and super dispute games (interop) are not yet live in production. Changes to those code paths in this release are preparation for future functionality and do not affect operators today.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.9.4)
</Update>

<Update label="May 26, 2026" description="v1.9.3">
  ## Overview

  This is release of op-challenger is required for [Upgrade 19](https://docs.optimism.io/notices/upgrade-19). It contains bug fixes, new features, and the removal of deprecated functionality.

  Note: ZK dispute games and super dispute games (interop) are not yet live in production. Changes to those code paths in this release are preparation for future functionality and do not affect operators today.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.9.3)
</Update>

<Update label="April 15, 2026" description="v1.9.1">
  ## Overview

  This is a patch release of op-challenger that includes important security fixes for chains running permissionless fault proofs, along with other bug fixes. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.9.1)
</Update>

<Update label="January 21, 2026" description="v1.9.0">
  ## Overview

  This is a minor release of op-challenger that includes important bug fixes. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.9.0)
</Update>

<Update label="January 9, 2026" description="v1.8.0">
  ## Overview

  This release of op-challenger includes support for Upgrade 18, plus minor bug fixes and improvements. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.8.0)
</Update>

<Update label="November 6, 2025" description="v1.7.0">
  ## Overview

  This is a minor release of op-challenger, it's an optional upgrade preparing for for [an upcoming refactor of the dispute game contracts to be reusable across chains](https://github.com/ethereum-optimism/optimism/issues/12421)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.7.0)
</Update>

<Update label="October 8, 2025" description="v1.6.0">
  ## Overview

  This release of `op-challenger` adds support for the [Ethereum Fusaka upgrade](https://forkcast.org/upgrade/fusaka/). It's a required upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.6.0)
</Update>

<Update label="June 12, 2025" description="v1.5.1">
  ## Overview

  This is a minor release of op-challenger that includes important bug fixes. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.5.1)
</Update>

<Update label="June 4, 2025" description="v1.5.0">
  ## Overview

  This release of `op-challenger` adds support for a new version of Cannon that is compatible with Go 1.23. It is a **required** upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.5.0)
</Update>

<Update label="April 15, 2025" description="v1.4.0">
  ## Overview

  This release of `op-challenger` fixes a medium severity bug related to EIP-4844 blob data handling. It is a **required** upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.4.0)
</Update>

<Update label="March 20, 2025" description="v1.3.3">
  ## Overview

  This is a minor release of op-challenger that includes a fix to improve stability.  It is an optional upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.3.3)
</Update>

<Update label="March 3, 2025" description="v1.3.2">
  ## Overview

  This is a minor release of op-challenger that includes important bug fixes. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.3.2)
</Update>

<Update label="February 13, 2025" description="v1.3.1">
  ## Overview

  This is a minor release of op-challenger includes support for the Pectra hard fork on L1. It is a **required** upgrade for all users prior to Pectra activating on the L1 chain.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.3.1)
</Update>

<Update label="December 10, 2024" description="v1.3.0">
  ## Overview

  This is a minor release of op-challenger that includes minor new features and bug fixes. It is an optional upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.3.0)
</Update>

<Update label="November 5, 2024" description="v1.2.0">
  ## Overview

  This is a minor release of op-challenger that includes minor new features and bug fixes. It is an optional upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.2.0)
</Update>

<Update label="September 27, 2024" description="v1.1.2">
  ## Overview

  This is a minor release of op-challenger with minor new features.  It is an optional upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.1.2)
</Update>

<Update label="September 11, 2024" description="v1.1.0">
  ## Overview

  This is a minor release of op-challenger that includes support for the Granite hard fork changes and bug fixes. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.1.0)
</Update>

<Update label="June 15, 2024" description="v1.0.1">
  ## Overview

  This is a minor release of op-challenger that includes minor new features. It is an optional upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.0.1)
</Update>

<Update label="June 10, 2024" description="v1.0.0">
  ## Overview

  This is the 1.0 release of op-challenger, an implementation of the honest actor algorithm for fault dispute games. To learn more about dispute games, visit the [fault proof specs](https://specs.optimism.io/fault-proof/index.html).

  **🚢 Docker Image:**

  * [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v1.0.0](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:v1.0.0)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-challenger/v1.0.0)
</Update>


# op-conductor Releases
Source: https://docs.optimism.io/releases/op-conductor

Release history for op-conductor. High-availability sequencer coordination service.

**op-conductor** manages sequencer high-availability using Raft consensus, coordinating a multi-node sequencer cluster to ensure no unsafe reorgs and continuous uptime with up to one node failure.

<Update label="May 18, 2026" description="v0.9.4">
  This release includes bug fixes for cluster stability and leader failover, a new round-robin leadership transfer feature, and
  removal of the deprecated op-supervisor health check integration. It also ensures that the version label is filled with build info from CI.

  What's Changed in op-conductor/v0.9.4

  * [CI build bug ](https://github.com/ethereum-optimism/optimism/pull/19809)has been fixed to ensure `version` label is filled
  * fix(op-conductor): disable raft ShutdownOnRemove to prevent zombie nodes by @KyrinCode in
    [https://github.com/ethereum-optimism/optimism/pull/18699](https://github.com/ethereum-optimism/optimism/pull/18699)
  * feat(conductor): fix leader loop switch by adding round-robin leadership transfer by @KyrinCode in
    [https://github.com/ethereum-optimism/optimism/pull/18697](https://github.com/ethereum-optimism/optimism/pull/18697)
  * chore: replace deprecated deps with stdlib equivalents by @sebastianst in [https://github.com/ethereum-optimism/optimism/pull/20014](https://github.com/ethereum-optimism/optimism/pull/20014)
  * op-node: remove deprecated ProtocolVersions watching by @sebastianst in [https://github.com/ethereum-optimism/optimism/pull/20311](https://github.com/ethereum-optimism/optimism/pull/20311)
  * chore(op-conductor): remove op-supervisor support by @ajsutton in [https://github.com/ethereum-optimism/optimism/pull/20781](https://github.com/ethereum-optimism/optimism/pull/20781)

  Full Changelog: [https://github.com/ethereum-optimism/optimism/compare/op-conductor/v0.9.3...op-conductor/v0.9.4](https://github.com/ethereum-optimism/optimism/compare/op-conductor/v0.9.3...op-conductor/v0.9.4)

  🚢 Docker Image: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-conductor:v0.9.4](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-conductor:v0.9.4)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.9.4)
</Update>

<Update label="March 31, 2026" description="v0.9.3">
  This release is optional; however, we recommend updating as it includes a Go version upgrade addressing security fixes, along with enhanced container image hardening.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.9.3)
</Update>

<Update label="October 30, 2025" description="v0.9.0">
  This release supports deserialisation of rollup configs, passed at the command line, which contain fields introduced with the Jovian hardfork (which can appear in the rollup config even before Jovian is active).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.9.0)
</Update>

<Update label="October 6, 2025" description="v0.8.0">
  ## What's Changed

  * feat(op-conductor): rollup-boost partial unhealthiness tolerance by @yashvardhan-kukreja in [https://github.com/ethereum-optimism/optimism/pull/17633](https://github.com/ethereum-optimism/optimism/pull/17633)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.8.0)
</Update>

<Update label="September 10, 2025" description="v0.7.3">
  ## What's Changed

  * op-conductor: p2p healthcheck fix and execution\_p2p\_healthcheck\_api\_type by @yashvardhan-kukreja in [https://github.com/ethereum-optimism/optimism/pull/17294](https://github.com/ethereum-optimism/optimism/pull/17294)

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/op-conductor/v0.7.2...op-conductor/v0.7.3](https://github.com/ethereum-optimism/optimism/compare/op-conductor/v0.7.2...op-conductor/v0.7.3)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.7.3)
</Update>

<Update label="June 10, 2025" description="v0.7.0">
  ## What's Changed

  * add conductor support for flashblocks websocket by @angel-ding-cb in [https://github.com/ethereum-optimism/optimism/pull/15681](https://github.com/ethereum-optimism/optimism/pull/15681)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.7.0)
</Update>

<Update label="May 12, 2025" description="v0.5.1-rc.3">
  ## Transparent and unconditional proxy for throttling messages

  In this release the conductor is updated to forward `miner_setMaxDASize` API calls

  * transparently -- that is, returning an error if the origin sequencer returns an error, and
  * unconditionally -- that is, proxying the call even if the origin sequencers is not currently the leader

  > \[!IMPORTANT]
  > It is strongly recommended to upgrade. If updating to the latest op-batcher release, it is required to upgrade to this version of op-conductor too, because starting with this batcher release, all endpoints are always throttled, not only the active sequencer.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-conductor/v0.5.1-rc.3)
</Update>


# op-contracts Releases
Source: https://docs.optimism.io/releases/op-contracts

Release history for op-contracts. OP Stack L1 and L2 smart contracts.

**op-contracts** contains the L1 and L2 smart contracts for the OP Stack. See the [contract reference](https://devdocs.optimism.io/contracts-bedrock) for interface documentation and architecture details.

<Update label="August 2, 2026" description="v8.0.0-rc.2">
  This is a release candidate of the OP Stack smart contracts for Upgrade 20 (U20). Note that U20 does not include a hard fork so L2 predeploy changes will not be deployed.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v8.0.0-rc.2)
</Update>

<Update label="June 25, 2026" description="v7.0.0">
  This is the op-contracts release associated with [Upgrade 19](https://gov.optimism.io/t/upgrade-19b-karst-hardfork/10713).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v7.0.0)
</Update>

<Update label="May 29, 2026" description="v7.0.0-rc.4">
  ## What's Changed in op-contracts/v7.0.0-rc.4

  * feat(contracts-bedrock): scale ResourceConfig to fit smaller gasLimits (v7.0.0)
  * Merge pull request #20981 from ethereum-optimism/jm/revert-xlayer-layout-fix
  * Revert "fix(l2cm): preserve XLayer LiquidityController minters across upgrade "
  * fix(l2cm): preserve XLayer LiquidityController minters across upgrade
  * fix: filter prerelease OPCM release tags (cherry-pick of #20617)
  * feat: make l2cm default path in devfeature bitmap
  * chore(ci): clean up contracts CI and RPC secrets
  * fix(contracts): reject oz v5 initializable in opcm
  * chore(rust/scr): update superchain registry for rust crates
  * feat: zk go deployer
  * fix(contracts): fail closed resolving semver target branch
  * chore(contracts-bedrock): drop v1 mention from \_decodeDisputeGameImpl natspec
  * interop: add OPContractsManagerMigrationValidator for post-migration validation
  * fix(op-fetcher): guard against zero mipsImpl before calling oracle()
  * chore(contracts-bedrock): fix contract typos
  * Revert "chore(rust): bump revm to 38 "
  * Revert "Delete .circleci/Untitled "
  * docs(opcm): acknowledge Initializable upgrade limitations
  * test(contracts): cover VerifyOPCM runSingle lazy setup
  * fix: ZK Game Quality Review Fixes
  * chore(rust): bump revm to 38
  * test: add ZKDisputeGame unit and integration test coverage
  * fix(contracts-bedrock): skip lint fix during CI
  * Delete .circleci/Untitled
  * feat(contracts): enforce EIP-7825 gas cap in NUT bundle validation
  * feat(l2cm): support X Layer LiquidityController in L2CM upgrade path
  * feat: add SP1Adapter
  * fix: add intrinsic gas deduction to l2 fork tests
  * chore(contracts): remove 7 unreferenced interfaces
  * test(contracts): skip VerifyOPCM\_Run\_Test on coverage only, not unoptimized
  * chore(contracts): remove unused SchemaResolver abstract base
  * fix(contracts): skip ZKDisputeGame in VerifyOPCM when feature disabled
  * refactor: revenue share cleanup
  * fix: l2cm fma followup
  * feat: opcm zk roots
  * chore(deployer): remove OPCMv1 migration, upgrade, and dev feature code
  * contracts: delete unused interop contracts
  * fix(l2cm): guard CGT feature activation and liquidity controller renounce ownership

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v7.0.0-rc.4)
</Update>

<Update label="March 16, 2026" description="v6.0.0">
  This is the contracts release for [Upgrade 18](https://gov.optimism.io/t/upgrade-18-custom-gas-token-v2-and-kona-proofs/10576). The main changes in this release are:

  * Custom Gas Token v2: gated behind the CUSTOM\_GAS\_TOKEN feature flag in SystemConfig and is intended for new chains that enable it at deployment.
  * Creator Pattern Dispute Game Refactor: efficient deployment of dispute game contracts, allowing one single implementation to be used for all chains (which is then cloned and configured separately for each chain).
  * Cannon + Kona: This upgrade adds a [new game type](https://github.com/ethereum-optimism/optimism/blob/b9dc5808f61c160de048fb7db39a04fe4fba4574/packages/contracts-bedrock/src/dispute/lib/Types.sol#L76-L77) to use [Kona Proof](https://github.com/ethereum-optimism/optimism/tree/develop/kona/crates/proof/proof) with the Cannon [Fault Proof VM](https://specs.optimism.io/fault-proof/index.html#fault-proof-vm). It does not change the respected game type. (as of `b9dc580`)

  The audit results [are published here](https://github.com/ethereum-optimism/optimism/blob/develop/docs/security-reviews/2026_01-U18-Cantina.pdf).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v6.0.0)
</Update>

<Update label="January 16, 2026" description="v6.0.0-rc.2">
  Refer to [`op-contracts/v6.0.0`](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv6.0.0) for full release notes for this release (it's the "finalized" version tag on the same commit).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v6.0.0-rc.2)
</Update>

<Update label="December 19, 2025" description="v5.0.0+l2-rev-share-contracts">
  ## Overview

  This release introduces **Revenue Sharing**, an opt-in mechanism for configurable distribution of L2 transaction fees between Optimism and chain operators.

  ***

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v5.0.0%2Bl2-rev-share-contracts)
</Update>

<Update label="October 28, 2025" description="v5.0.0">
  > \[!WARNING]
  > The `op-deployer/justfile` file in this release MUST NOT be used for deployments, as it will result in you deploying with an old MIPS version. Please use the latest `op-deployer/v*` release instead to deploy contracts contained in this commit

  This release adds support for configuring the minimum base fee and DA footprint gas scalar variables, which affect features activating with the Jovian hardfork.

  Cannon has been updated to support versions of op-program that are compiled with Go 1.24.

  The OPCM version includes changes to prepare for supporting the [Kona](https://github.com/op-rs/kona) fault proof program in a future release and the `CANNON_KONA` game type has been added.

  For details of individual contract versions and standard deployments, please see the below links in the superchain registry:

  * [Sepolia](https://github.com/ethereum-optimism/superchain-registry/blob/80818cd29c28a37be79e2f31fe5cd2a8254fc58c/validation/standard/standard-versions-sepolia.toml#L6-L25) (as of `80818cd`)
  * [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/80818cd29c28a37be79e2f31fe5cd2a8254fc58c/validation/standard/standard-versions-mainnet.toml#L6-L25) (as of `80818cd`)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v5.0.0)
</Update>

<Update label="October 27, 2025" description="v5.0.0-rc.2">
  This release adds support for configuring the minimum base fee and DA footprint gas scalar variables, which affect features activating with the Jovian hardfork. It also includes support for Go 1.24 in the Cannon fault proof VM.

  For details of individual contract versions and standard deployments, please see the below links in the superchain registry:

  * [Sepolia](https://github.com/ethereum-optimism/superchain-registry/blob/0cc526c0acdfffac5b1966bf7465406e41f33b00/validation/standard/standard-versions-sepolia.toml#L6-L25) (as of `0cc526c`)
  * [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/0cc526c0acdfffac5b1966bf7465406e41f33b00/validation/standard/standard-versions-mainnet.toml#L6-L25) (as of `0cc526c`)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v5.0.0-rc.2)
</Update>

<Update label="October 2, 2025" description="v4.1.0">
  This is the `op-contracts` release associated with the [Upgrade 16a protocol upgrade](https://docs.optimism.io/notices/upgrade-16a).

  For contract versions and implementation addresses in this release, please refer to the superchain-registry:

  [Sepolia versions](https://github.com/ethereum-optimism/superchain-registry/blob/df4e953b384b7fb6dad14676fc5d9a9a994e5748/validation/standard/standard-versions-sepolia.toml#L7) (as of `df4e953`)
  [Mainnet versions](https://github.com/ethereum-optimism/superchain-registry/blob/df4e953b384b7fb6dad14676fc5d9a9a994e5748/validation/standard/standard-versions-mainnet.toml#L7) (as of `df4e953`)

  The associated governance proposal can be found [here](https://gov.optimism.io/t/maintenance-upgrade-proposal-u16a/10288). Deployment operations should be executed using the associated op-deployer release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v4.1.0)
</Update>

<Update label="August 15, 2025" description="v2.2.0">
  This `op-contracts` release modifies the `op-contracts/v2.0.0` OPCM.

  It removes the conditional upgrades of the SuperchainConfig and protocol versions proxies which currently prevents chains that are at `op-contracts/v1.8.0` from upgrading their contracts via the `v2.0.0` OPCM.

  Chains which use their own SuperchainConfig, rather than sharing it with OP Mainnet or OP Sepolia, should continue to use the OPCM  from `op-contracts/v2.0.0`.

  For contract versions and implementation addresses in this release; please refer to the superchain-registry:

  * [Sepolia versions](https://github.com/ethereum-optimism/superchain-registry/blob/802e9b18739ae1a674fc609ca3a51e556b128b97/validation/standard/standard-versions-mainnet.toml#L145) (as of `802e9b1`)
  * [Mainnet versions](https://github.com/ethereum-optimism/superchain-registry/blob/802e9b18739ae1a674fc609ca3a51e556b128b97/validation/standard/standard-versions-sepolia.toml#L145) (as of `802e9b1`)

  Deployment operations should be executed using the associated `op-deployer` release.

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/op-contracts/v2.0.0...op-contracts/v2.2.0](https://github.com/ethereum-optimism/optimism/compare/op-contracts/v2.0.0...op-contracts/v2.2.0)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v2.2.0)
</Update>

<Update label="June 19, 2025" description="v4.0.0-rc.8">
  This is the op-contracts release intended for the forthcoming [Upgrade 16 protocol upgrade](https://docs.optimism.io/notices/upgrade-16).

  For contract versions and implementation addresses in this release; please refer to the superchain-registry:

  * [Sepolia versions](https://github.com/ethereum-optimism/superchain-registry/blob/6b65f330434d46e24abc9ef78852ac3fa1cba4ec/validation/standard/standard-versions-sepolia.toml#L7) (as of `6b65f33`)
  * [Mainnet versions](https://github.com/ethereum-optimism/superchain-registry/blob/6b65f330434d46e24abc9ef78852ac3fa1cba4ec/validation/standard/standard-versions-mainnet.toml#L7) (as of `6b65f33`)

  The associated governance proposal can be found [here](https://gov.optimism.io/t/upgrade-16-proposal-interop-contracts-stage-1-and-go-1-23-support-in-cannon/10037).

  Deployment and upgrade operations should be executed using the associated op-deployer release (link to be updated after [this PR](https://github.com/ethereum-optimism/superchain-registry/pull/1079) is merged)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v4.0.0-rc.8)
</Update>

<Update label="July 21, 2025" description="v4.0.0">
  This is the op-contracts release associated with the recently passed [Upgrade 16 protocol upgrade](https://docs.optimism.io/notices/upgrade-16).

  For contract versions and implementation addresses in this release; please refer to the superchain-registry:

  * [Sepolia versions](https://github.com/ethereum-optimism/superchain-registry/blob/6b65f330434d46e24abc9ef78852ac3fa1cba4ec/validation/standard/standard-versions-sepolia.toml#L7) (as of `6b65f33`)
  * [Mainnet versions](https://github.com/ethereum-optimism/superchain-registry/blob/6b65f330434d46e24abc9ef78852ac3fa1cba4ec/validation/standard/standard-versions-mainnet.toml#L7) (as of `6b65f33`)
    The associated governance proposal can be found [here](https://gov.optimism.io/t/upgrade-16-proposal-interop-contracts-stage-1-and-go-1-23-support-in-cannon/10037).

  Deployment operations should be executed using the associated `op-deployer` release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v4.0.0)
</Update>

<Update label="May 8, 2025" description="v3.0.0">
  # Overview

  This release upgrades the fault proof to use multithreaded Cannon64 and introduces operator fee pricing. It updates the addresses for the EIP-2935 predeploys.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v3.0.0)
</Update>

<Update label="March 7, 2025" description="v3.0.0-rc.1">
  # Overview

  This release candidate upgrades the fault proof to use multithreaded Cannon64 and introduces operator fee pricing.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v3.0.0-rc.1)
</Update>

<Update label="April 2, 2025" description="v2.0.0">
  # Overview

  This contracts release updates all of the L1 contracts as part of [Upgrade 13](https://gov.optimism.io/t/upgrade-proposal-13-opcm-and-incident-response-improvements/9739), the first OP Contracts Manager upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v2.0.0)
</Update>

<Update label="February 25, 2025" description="v2.0.0-rc.1">
  # Overview

  This release candidates updates all of the L1 contracts as part of the first OP Contracts Manager upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v2.0.0-rc.1)
</Update>

<Update label="January 10, 2025" description="v1.8.0">
  # Overview

  This release is suitable for the L1 contracts as part of the Holocene network upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v1.8.0)
</Update>

<Update label="November 25, 2024" description="v1.8.0-rc.3">
  # Overview

  This release is suitable for the L1 contracts as part of the Holocene network upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v1.8.0-rc.3)
</Update>

<Update label="November 19, 2024" description="v1.8.0-rc.2">
  # Overview

  This release is suitable for the L1 contracts as part of the Holocene network upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v1.8.0-rc.2)
</Update>

<Update label="November 7, 2024" description="v1.8.0-rc.1">
  # Overview

  This release is suitable for the L1 contracts as part of the Holocene network upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v1.8.0-rc.1)
</Update>

<Update label="September 16, 2024" description="v.1.7.0-beta.1+l2-contracts">
  # Overview

  This release is suitable for generating L2 genesis. The L1 contract deployments should be done with another release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts/v.1.7.0-beta.1%2Bl2-contracts)
</Update>


# op-deployer Releases
Source: https://docs.optimism.io/releases/op-deployer

Release history for op-deployer. OP Stack chain deployment and upgrade tool.

**op-deployer** automates deploying and upgrading OP Stack smart contracts. See the [usage docs](https://docs.optimism.io/chain-operators/tools/op-deployer/overview) for full configuration reference.

<Update label="June 26, 2026" description="v0.7.1">
  ## Changelog

  * 6a1240e9974e87b390cb72a15b16bfd85bb8a2ff chore(opd): update SCR dep for op-contracts/v7.0.0-rc.3 tag (#20989)
  * 7525482253bdc076548840638cde165c9004349f chore(opd): update SCR dep for op-contracts/v7.0.0-rc.4 tag (#21045)
  * d210865edde5f2c9a6b84dd26f08fe8b3fa562b3 fix(op-deployer): hydrate OpcmUtilsImpl and OpcmMigratorImpl in state (#20403)
  * 35121b586aa3e6359782f900c09fc6e35dd372e1 refactor: remove ProtocolVersions Go plumbing (#20441)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.7.1)
</Update>

<Update label="June 25, 2026" description="v0.7.0">
  This is the op-deployer release associate with [op-contracts/v7.0.0](https://github.com/ethereum-optimism/optimism/releases/tag/op-contracts%2Fv7.0.0) and [Upgrade 19](https://gov.optimism.io/t/upgrade-19b-karst-hardfork/10713).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.7.0)
</Update>

<Update label="May 27, 2026" description="v0.7.0-rc.1">
  ## Changelog

  * 6a1240e9974e87b390cb72a15b16bfd85bb8a2ff chore(opd): update SCR dep for op-contracts/v7.0.0-rc.3 tag (#20989)
  * 7525482253bdc076548840638cde165c9004349f chore(opd): update SCR dep for op-contracts/v7.0.0-rc.4 tag (#21045)
  * d210865edde5f2c9a6b84dd26f08fe8b3fa562b3 fix(op-deployer): hydrate OpcmUtilsImpl and OpcmMigratorImpl in state (#20403)
  * 35121b586aa3e6359782f900c09fc6e35dd372e1 refactor: remove ProtocolVersions Go plumbing (#20441)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.7.0-rc.1)
</Update>

<Update label="April 28, 2026" description="v0.7.0-alpha.2">
  ## Changelog

  * a0a2a9289095df35d57d6c8f9039a56c207ee70e  feat: Improve Game Args interface (#18952)
  * e5b137f52d7014b98b4448e9f5adc01886bdba32 (cherry-pick) feat: op-validator v6.0.0 support (#18915)
  * 45927332696d9ecc6d2e881e748a9c1fd83cff31 Add Karst hard fork activation (#19250)
  * ddfa07a6c7a2cb23b0712e0813db642028609c28 Delete `OptimismPortalInterop` contract and all references (#19956)
  * 06eabb1f308b182d713c01abc5408aaa90256af7 Enable UInt64 lint check and fix remaining violations (#18948)
  * 881dd74bfd383637a5406aeb9f7543287f91fea4 Improve docs and invocation on just deploy-opcm (#16421)
  * 5e38a4fdbcb3e87e06555701d269aa74cd5bdc89 Remove upgrade controller from OPCM (#17660)
  * a820ae0039781be8999ac079108ab4a050be5202 Revert "feat(op-deployer): build contracts in docker (#19088)" (#19106)
  * f2292430add42a71f8f27c9868b9f59b219a2174 Update version (#16829)
  * 06a14a05781285e6fe8a5679eb69a03bfd3628e5 add TestEndToEndBootstrapApplyWithUpgrade and UpgradeSuperchainConfig scripts (#17826)
  * 3c82c3f7618b98e161ce0aff4a1901bed3a4abb9 all: Add DA footprint configurability via SystemConfig (#17466)
  * bf196f97c4105fc94c3e92e198dbcb46da70c776 all: Move fork names into new op-core/forks package (#18121)
  * d9a6c32f76849d68937e15cae381ccd7b1cb1126 all: Move package predeploys from op-service to op-core (#18145)
  * e7cc17166daf1c55bb3ba138018444de7d29f3c3 all: Remove cannon-kona dgv2 feature flags (#18208)
  * 3549f7137693d5d7dbc334521ccc35fac859c89e asterisc: Remove asterisc contracts (#18689)
  * c72a9ce2d032d5840bd582868afb43da3566266c cannon: Deploy Cannon with Go 1.24 support (#17155)
  * 131ae1b372377988b17e7ad825744ac53e5c29de chore(deployer): remove OPCMv1 migration, upgrade, and dev feature code (#20064)
  * a9898820c86c2ef2ccdc3bc9c9fb728da46e4218 chore: Add SafeRename ioutil utility (#18610)
  * 17552791acf8b8863bbc0181bd15085a78f6ca33 chore: Stabilize & simplify docker build (#18013)
  * aff5fbe0569173991af31d49fc4dffee0530e5bb chore: op-deployer prestate generation log change (#17058)
  * 03d824bbb6208123c3106f2b6901b68374b82c6c chore: remove OpcmImpl compat shim, ReadSuperchainDeployment v1 fields, CI, docs (#19919)
  * 32fe33bb381811116f4f58547e3fab59e58c2f15 chore: remove devnet-sdk and kurtosis-devnet (#19506)
  * 822f616c9d4bc182e468c43fd25b5abf0a9ccfd4 chore: replace deprecated deps with stdlib equivalents (#20014)
  * d555dc438248d524030e34263f0867f8443d282a chore: return migrator address on ReadImplementationAddresses output (#19076)
  * c59e981f8c2f875dfd749808a333719ac7c28a94 chore: update fees depositor address and min withdrawal amount on genesis (#18490)
  * e30097bd16d86ff6483876da9aa85245ee9f8ac1 chore: update op-deployer docs (#17204)
  * 5a6ed1605ea23525684ad96077bf3a05042391c1 ci: Move linter configuration to .golangci.yaml (#16935)
  * d4e5c26b9dab5ff6ebe9be8d1f1595b91edd48b8 ci: migrate op-deployer Docker build from CircleCI to GitHub Actions#19329 (#19530)
  * f2c294d9276a1f1950e5ef46bcc88b64abe229fd contracts: ReadImplementations output include AnchorStateRegistry + Opcm components (#18241)
  * 6de21d0f81036bc76f14a7bdec89304c60c97f14 contracts: delete unused interop contracts (#19999)
  * d24cf93fed41b1f4ba912ef8ccf58c250d1cd75c ctb,op-deployer: Remove isRC() and L1\_CONTRACTS\_RELEASE (#17028)
  * 3425078321ddcf444ccb0fb363a48fae1b2b6a95 devstack: Enable individual dev features instead of replacing the whole bitmap (#17994)
  * 355fdcbb68310e70ffa6eb8a7635a4d9cea7935a feat(op-acceptance-tests): port fjord (holocene) tests to devstack (#16920)
  * c65dd1d227b4db9f10509beacddbcae8e73db170 feat(op-deployer): Add a command for OPCM.migrate call (#16710)
  * 42bb95f6b7f0f8b4b8ec80dbe627d8ec00ad0215 feat(op-deployer): add docker and github binary to the op-deployer test script (#18551)
  * 8ae8e80e1db2bd9f2e357449c399c4861a80d754 feat(op-deployer): add feature flag to enable forge scripts (#18881)
  * 233a6ff6dac9ad4b5c61cd2e920a5639e336bef1 feat(op-deployer): add forge flag to bootstrap + apply (#18913)
  * 513eca1766d7a9746ab66eaf6990d0daf8b17795 feat(op-deployer): build contracts in docker (#19088)
  * fd5f8e332c7516cdc01cdb23cfe986598b7b0958 feat(op-deployer): cli based integration tests (#17511)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.7.0-alpha.2)
</Update>

<Update label="April 28, 2026" description="v0.7.0-alpha.1">
  > \[!IMPORTANT]
  > This is a development/alpha release, not intended for usage in production environments, no binaries have been attached to this please see op-deployer/v0.7.0-alpha.2

  # What's Changed in op-deployer/v0.7.0-alpha.1

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.7.0-alpha.1)
</Update>

<Update label="April 2, 2026" description="v0.6.0">
  # Overview

  `op-deployer/v0.6.0` supports deploying, upgrading to, and producing calldata for `op-contracts/v6.0.0` (u18). This release supports all of the following:

  ```
  op-deployer bootstrap [options] // deploy superchain|implementations contracts at op-contracts/v4.1.0
  op-deployer apply [options] // deploy new OPChain contracts at op-contracts/4.1.0
  op-deployer upgrade v2.0.0 // upgrade from op-contracts/v1.8.0 -> op-contracts/v2.0.0
  op-deployer upgrade v3.0.0 // upgrade from op-contracts/v2.0.0 -> op-contracts/v3.0.0
  op-deployer upgrade v4.0.0 // upgrade from op-contracts/v3.0.0 -> op-contracts/v4.0.0 (not recommended, should upgrade straight to op-contracts/v4.1.0 instead)
  op-deployer upgrade v4.1.0 // upgrade from op-contracts/v3.0.0|v4.0.0 -> op-contracts/v4.1.0
  op-deployer upgrade v5.0.0 // upgrade from op-contracts/v4.1.0 -> op-contracts/v5.0.0
  op-deployer upgrade v6.0.0 // upgrade from op-contracts/v5.0.0 -> op-contracts/v6.0.0
  ```

  All other commands are only guaranteed to work with `op-contracts/v6.0.0`. So you must upgrade to `op-contracts/v6.0.0` before doing the following:

  ```
  op-deployer manage [options]
  op-deployer verify [options]
  ```

  # Details

  Additional changes outside of `op-contracts/v6.0.0` support include:

  * opDeployerVersion is now recorded in the intent and state files
  * ongoing OPCMv2 work
  * fixed Windows builds

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.6.0)
</Update>

<Update label="January 15, 2026" description="v0.6.0-rc.3">
  ## Changelog

  * 79f8ed110b29db79a85b882d3eed5c2b8570eff4 feat(op-deployer): Update for op-contracts/v6.0.0-rc.2

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.6.0-rc.3)
</Update>

<Update label="January 15, 2026" description="v0.6.0+rc.3">
  ## Changelog

  * 79f8ed110b29db79a85b882d3eed5c2b8570eff4 feat(op-deployer): Update for op-contracts/v6.0.0-rc.2

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.6.0%2Brc.3)
</Update>

<Update label="January 14, 2026" description="v0.6.0+l2-rev-share-contracts">
  ## Changelog

  * 018f5ae926ec3277746b56a1c4ddb715c568603d chore: update fees depositor address and min withdrawal amounts (#18736)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.6.0%2Bl2-rev-share-contracts)
</Update>

<Update label="December 24, 2025" description="v0.6.0-rc.2">
  # Overview

  `op-deployer/v0.6.0-rc.2` supports deploying, upgrading to, and producing calldata for `op-contracts/v6.0.0-rc.1` (u18). This release supports all of the following:

  ```
  op-deployer bootstrap [options] // deploy superchain|implementations contracts at op-contracts/v4.1.0
  op-deployer apply [options] // deploy new OPChain contracts at op-contracts/4.1.0
  op-deployer upgrade v2.0.0 // upgrade from op-contracts/v1.8.0 -> op-contracts/v2.0.0
  op-deployer upgrade v3.0.0 // upgrade from op-contracts/v2.0.0 -> op-contracts/v3.0.0
  op-deployer upgrade v4.0.0 // upgrade from op-contracts/v3.0.0 -> op-contracts/v4.0.0 (not recommended, should upgrade straight to op-contracts/v4.1.0 instead)
  op-deployer upgrade v4.1.0 // upgrade from op-contracts/v3.0.0|v4.0.0 -> op-contracts/v4.1.0
  op-deployer upgrade v5.0.0 // upgrade from op-contracts/v4.1.0 -> op-contracts/v5.0.0
  op-deployer upgrade v6.0.0-rc.1 // upgrade from op-contracts/v5.0.0 -> op-contracts/v6.0.0-rc.1
  ```

  All other commands are only guaranteed to work with `op-contracts/v6.0.0-rc.1`. So you must upgrade to `op-contracts/v6.0.0` before doing the following:

  ```
  op-deployer manage [options]
  op-deployer verify [options]
  ```

  # Details

  Additional changes outside of `op-contracts/v6.0.0` support include:

  * opDeployerVersion is now recorded in the intent and state files
  * ongoing OPCMv2 work
  * fixed Windows builds

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.6.0-rc.2)
</Update>

<Update label="December 12, 2025" description="v0.5.2">
  ## Changelog

  * e0299c7c3044fe8e6706a9d8e2776e2479067d43 feat(op-validator): add v5.0.0 contracts support (#18299)
  * 2dac8b448463d8fc64e840abcb42d4edd407c30a op-deployer: Fix error handling in add\_game\_type CLI parsing. (#18026)
  * be34fe2765b653098982883d1ca7d5928673f96a op-deployer: support op-contracts/v5.0.0 upgrade (#18154) (#18580)
  * 0a1a5e0fa4f20ff9fd646c44383ca9eaa048e865 proposal/op contracts/v5.0.0 rc.1+l2 fee splitter contracts (#18474)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.5.2)
</Update>

<Update label="December 8, 2025" description="v0.5.1">
  ## Changelog

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.5.1)
</Update>

<Update label="December 8, 2025" description="v0.5.0">
  # Overview

  `op-deployer/v0.5.0` supports deploying, upgrading to, and producing calldata for `op-contracts/v4.5.0` (u17). This release supports all of the following:

  ```
  op-deployer bootstrap [options] // deploy superchain|implementations contracts at op-contracts/v4.1.0
  op-deployer apply [options] // deploy new OPChain contracts at op-contracts/4.1.0
  op-deployer upgrade v2.0.0 // upgrade from op-contracts/v1.8.0 -> op-contracts/v2.0.0
  op-deployer upgrade v3.0.0 // upgrade from op-contracts/v2.0.0 -> op-contracts/v3.0.0
  op-deployer upgrade v4.0.0 // upgrade from op-contracts/v3.0.0 -> op-contracts/v4.0.0 (not recommended, should upgrade straight to op-contracts/v4.1.0 instead)
  op-deployer upgrade v4.1.0 // upgrade from op-contracts/v3.0.0|v4.0.0 -> op-contracts/v4.1.0
  op-deployer upgrade v5.0.0 // upgrade from op-contracts/v4.1.0 -> op-contracts/v5.0.0
  ```

  All other commands are only guaranteed to work with `op-contracts/v5.0.0`. So you must upgrade to `op-contracts/v5.0.0` before doing the following:

  ```
  op-deployer manage [options]
  op-deployer verify [options]
  ```

  # Details

  Additional changes outside of `op-contracts/v5.0.0` support include:

  * enables jovian at genesis by default
  * embeds artifacts in a zstd format reducing the overall filesize
  * updates SuperchainConfigImpl address
  * restores contract verification functionality by leveraging forge, currently etherscan and blockscout are supported

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.5.0)
</Update>

<Update label="December 9, 2025" description="v0.4.7">
  Introduces a fix for a bug that caused the `--initial-bond` CLI argument for `manage add-game-type` command to parse incorrectly.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.4.7)
</Update>

<Update label="November 4, 2025" description="v0.5.0-rc.2">
  ## Changelog

  * 32eb970da5911ca82ef14adb36479cc7f9fe77de fix(op-deployer): update justfile to use current CLI flags (#18142)
  * 4b888c83fa497e85c4e1e59c576d931515653252 fix: use default mips version and use local op-deployer (#18129) (#18132)
  * 77f31c359f9b3608bf48a8b0981e79b67bd95cb4 op-deployer: support op-contracts/v5.0.0-rc.2 upgrade (#18154)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.5.0-rc.2)
</Update>

<Update label="October 24, 2025" description="v0.5.0-rc.1">
  ## Changelog

  * 881dd74bfd383637a5406aeb9f7543287f91fea4 Improve docs and invocation on just deploy-opcm (#16421)
  * 5e38a4fdbcb3e87e06555701d269aa74cd5bdc89 Remove upgrade controller from OPCM (#17660)
  * f2292430add42a71f8f27c9868b9f59b219a2174 Update version (#16829)
  * 3c82c3f7618b98e161ce0aff4a1901bed3a4abb9 all: Add DA footprint configurability via SystemConfig (#17466)
  * c72a9ce2d032d5840bd582868afb43da3566266c cannon: Deploy Cannon with Go 1.24 support (#17155)
  * aff5fbe0569173991af31d49fc4dffee0530e5bb chore: op-deployer prestate generation log change (#17058)
  * e30097bd16d86ff6483876da9aa85245ee9f8ac1 chore: update op-deployer docs (#17204)
  * 5a6ed1605ea23525684ad96077bf3a05042391c1 ci: Move linter configuration to .golangci.yaml (#16935)
  * d24cf93fed41b1f4ba912ef8ccf58c250d1cd75c ctb,op-deployer: Remove isRC() and L1\_CONTRACTS\_RELEASE (#17028)
  * 355fdcbb68310e70ffa6eb8a7635a4d9cea7935a feat(op-acceptance-tests): port fjord (holocene) tests to devstack (#16920)
  * c65dd1d227b4db9f10509beacddbcae8e73db170 feat(op-deployer): Add a command for OPCM.migrate call (#16710)
  * fd5f8e332c7516cdc01cdb23cfe986598b7b0958 feat(op-deployer): cli based integration tests (#17511)
  * 7eedfced77eb30ae72cc8d0e7c793dd2d1b6f161 feat(txmgr / batcher): Rebroadcast transactions without bumping fees (#16310)
  * c09c867e49c3fcee6d5a21bd04594d77a419e8d4 feat: dev feature flagging in OPCM (#17268)
  * 1c71340c02977d5447ed0b0d1df5507decd2dd7f feat: integrate creator pattern implementations in DeployImplementations.s.sol (#17329)
  * b1b911f49c4874c0931105701864722a89057a9e fix(op-deployer): EnsureDefaultCacheDir (#17411)
  * 7b6a9582b70383b173fa491273e326943a6dfba6 fix: bug blocking op-deployer verify (#17478)
  * ba50c0dbec18940daefa33df572f1ec99528f5a4 integrate Standard Validator into OPCM (#16237)
  * ee73dba91abebfc79503fb8c0543983745f744af min-base-fee: bring in op-geth code (#17307)
  * 90134998ca40c5e4c45e8a49aa23c766b5221675 op-acceptance-tests: Add smoke tests for disputegamev2 (#17775)
  * 2717a0dd8467ffb2223acef5297d0d493e185378 op-contracts: DeployOPChain.s.sol conform to input/output struct pattern (#17657)
  * cedc4e94f648e9e995c2bb50d6c541434c8aff65 op-deployer: Add docs on custom superchains (#16309)
  * e4352fe24a1dc887c16182add190e6dfcf2247dc op-deployer: Add forge CLI wrapper (#17231)
  * f6e0e8873404d02b6e7257bdeccc2b3a4c933b08 op-deployer: Add forge autodiscovery (#17152)
  * 187a61e56409c69b3f2839edaf0c0ad3fc7ddf63 op-deployer: Add support for upgrading and validating v4.0.0 (#16048)
  * c7605f467ebd685c439077229915804a3b7701b9 op-deployer: Add test for contract artifact integrity (#16568)
  * e0c891748d9c2c5f05c07a6eae9cbc19aad802ce op-deployer: Add tests for end-to-end bootstrap (#16575)
  * 34a1ff9dd9045e892abc0fa3d917a4ede759cd3f op-deployer: Bundle artifacts inside binary (#16777)
  * 6b402806ea341a4eefdb39bd6e20d4372b3c0a18 op-deployer: Do not create cache directory on import (#17776)
  * 51cb1a7523ac45e3c3703a1a2c6794b378f27cba op-deployer: Fix l1 contracts release flag (#16316)
  * 456a4cbaa4c77f39aa4262f6204781981acad401 op-deployer: Fix test that broke with U16 (#16657)
  * 9d95e2f07a3282943b95a50da781949060c4d08d op-deployer: Improve add-game-type (#16373)
  * 1ebc5f5a3c98311afe63f1ae1ff77835cc69f3bb op-deployer: StandardBin enforces specific forge version (#17242)
  * 1667684dd4563b325d34bcfd54feb09b43b44f2b op-deployer: add cli-level bootstrap integration tests (#17803)
  * d97e8aff735e2781efc5933d6c918cdde6f77568 op-deployer: add configurable chainIntent.GasLimit field (#17271)
  * 206a409e6aa091bb5a0dd36c4f4e60289440245d op-deployer: create generic forge.BytesScriptEncoder (#17524)
  * 2850953d58334025b2159a0b1cd946c0c34a72af op-deployer: enable embedded artifacts integration test (#17276)
  * 464752ff544695580851cfbe52794b44bfbbed14 op-deployer: ensure standard forge version matches mise (#17670)
  * a87c898d3cd559aa640a4f00f8baf79f4b01014b op-deployer: fix bootstrap implementations flags (#17090)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.5.0-rc.1)
</Update>

<Update label="October 14, 2025" description="v0.4.5">
  # Overview

  `op-deployer/v0.4.5` supports deploying, upgrading to, and producing calldata for `op-contracts/v4.1.0` (u16a). This release supports all of the following:

  ```
  op-deployer bootstrap [options] // deploy superchain|implementations contracts at op-contracts/v4.1.0
  op-deployer apply [options] // deploy new OPChain contracts at op-contracts/4.1.0
  op-deployer upgrade v2.0.0 // upgrade from op-contracts/v1.8.0 -> op-contracts/v2.0.0
  op-deployer upgrade v3.0.0 // upgrade from op-contracts/v2.0.0 -> op-contracts/v3.0.0
  op-deployer upgrade v4.0.0 // upgrade from op-contracts/v3.0.0 -> op-contracts/v4.0.0 (not recommended, should upgrade straight to op-contracts/v4.1.0 instead)
  op-deployer upgrade v4.1.0 // upgrade from op-contracts/v3.0.0|v4.0.0 -> op-contracts/v4.1.0
  ```

  All other commands are only guaranteed to work with `op-contracts/v4.1.0`. So you must upgrade to `op-contracts/v4.1.0` before doing the following:

  ```
  op-deployer manage [options]
  op-deployer verify [options]
  ```

  # Details

  Additional changes outside of `op-contracts/v4.1.0` support include:

  * ability to specify a custom block GasLimit when deploying a new OPChain via the chainIntent.GasLimit field
  * fusaka defense via reduction of default `tx.GasPadFactor` from 2.0 -> 1.2 (to allow `opcm.deploy` to work)
  * modified contracts locator in intent.toml (deprecated `tag://` locator in favor of `embedded`)
    1. `embedded` (default) - embeds artifacts.tgz file containing contracts artifacts from same branch as op-deployer, ensuring compatibility
    2. `https://` - download artifacts.tgz from remote server
    3. `file://` - point to local filepath of contract artifacts

  # Diff compared to `op-deployer/v0.4.4`

  * fixes bug in `op-deployer upgrade` related to contracts locator
  * adds full cli based integration test suite

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.4.5)
</Update>

<Update label="October 10, 2025" description="v0.4.4">
  # Overview

  `op-deployer/v0.4.4` supports deploying, upgrading to, and producing calldata for `op-contracts/v4.1.0` (u16a).

  # Details

  Additional changes outside of `op-contracts/v4.1.0` support include:

  * ability to specify a custom block GasLimit when deploying a new OPChain via the chainIntent.GasLimit field
  * fusaka defense via reduction of default `tx.GasPadFactor` from 2.0 -> 1.2 (to allow `opcm.deploy` to work)
  * modified contracts locator in intent.toml (deprecated `tag://` locator in favor of `embedded`)
    1. `embedded` (default) - embeds artifacts.tgz file containing contracts artifacts from same branch as op-deployer, ensuring compatibility
    2. `https://` - download artifacts.tgz from remote server
    3. `file://` - point to local filepath of contract artifacts

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.4.4)
</Update>

<Update label="October 9, 2025" description="v0.4.4-rc.2">
  ## Changelog

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.4.4-rc.2)
</Update>

<Update label="October 9, 2025" description="v0.4.4-rc.1">
  ## Changelog

  * 35bb3786c19162bd0fc8d8a49d025c8b3992709c op-deployer: add upgrade v4\_1\_0 command (#17790)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-deployer/v0.4.4-rc.1)
</Update>


# op-node Releases
Source: https://docs.optimism.io/releases/op-node

Release history for op-node. OP Stack consensus-layer client.

**op-node** implements the [rollup-node spec](https://specs.optimism.io/protocol/rollup-node.html), functioning as the consensus layer (CL) client of an OP Stack chain. It builds, relays, and verifies the canonical L2 chain, working alongside an execution layer client such as op-reth.

<Update label="August 3, 2026" description="v1.19.4">
  > \[!NOTE]
  > **Optional upgrade.** Sequencer and interop correctness fixes, plus an operator-facing compatibility improvement.

  > \[!IMPORTANT]
  > **APKO Docker images:** Starting with this release, the Docker URL contains an additional `/nexus` in its path, see full Docker image path below. Our Docker builds are now APKO based and during a transition period, the APKO-based images for any component will be available at `https://us-docker.pkg.dev/oplabs-tools-artifacts/images/nexus/<component>:<version>`. When we migrate to APKO-only images, we may remove the `/nexus` again from our image paths and will give another notice in this case.

  > \[!IMPORTANT]
  > The SuperAuthority deny-list check is now applied on the consolidation path ([#21970](https://github.com/ethereum-optimism/optimism/pull/21970)),
  > and stale sequencer build starts are rejected ([#21913](https://github.com/ethereum-optimism/optimism/pull/21913)).
  > op-node no longer requires the beacon node `version` endpoint ([#21915](https://github.com/ethereum-optimism/optimism/pull/21915)), which unblocks operators running restricted beacon endpoints.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.19.4)
</Update>

<Update label="July 20, 2026" description="v1.19.3">
  > \[!CAUTION]
  > **Mandatory upgrade for operators of Mode, Metal, and Zora using the built-in `--network` configs.** The previously embedded registry data set `keep_karst_upgrade_gas=true` for these chains, but their sequencers activated Karst with `false` — an op-node on v1.19.2 or earlier can derive a different post-Karst gas limit and halt safe-head progression. This release syncs the embedded configs to the canonical behavior ([#21674](https://github.com/ethereum-optimism/optimism/pull/21674)), so explicit overrides are no longer needed. OP Mainnet is unaffected (`true` remains correct). Recommended for all other operators.

  ### Breaking / behavior changes

  * **Strict registry decoding** ([#21648](https://github.com/ethereum-optimism/optimism/pull/21648)): unknown keys in superchain-registry TOML now fail loudly at startup instead of being silently dropped. No change with the embedded registry, but custom registry data carrying unmodeled keys will no longer load.
  * **Sequencer stop race fixed** ([#21690](https://github.com/ethereum-optimism/optimism/pull/21690)): a sequencer action armed before `Stop()` can no longer fire afterwards; a stopped sequencer previously could rebuild on a stale cached head and reorg the EL back onto it.
  * **Go API move** ([#21650](https://github.com/ethereum-optimism/optimism/pull/21650)): `LoadOPStackRollupConfig` moved from `op-node/rollup` to `op-node/superchain`. Downstream Go importers must update their import path; no operator-facing change.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.19.3)
</Update>

<Update label="July 7, 2026" description="v1.19.2">
  > \[!WARNING]
  > **All node operators must upgrade to op-node/v1.19.1 or later**. See the [op-node/v1.19.1 release notes](https://github.com/ethereum-optimism/optimism/releases/tag/op-node%2Fv1.19.1) for more information about Karst activation and its incompatibility with older versions of op-reth. All of the callouts on that release page apply.

  This release fixes an issue encountered when using op-node with an EL that prunes historical bodies (e.g., when using op-reth with `--minimal` or `--prune.bodies.distance`).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.19.2)
</Update>

<Update label="June 26, 2026" description="v1.19.1">
  > \[!Warning]
  > **This is a mandatory release for all node operators.** It includes the [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork. (as of `c90d86d`)
  >
  > The following Mainnet chains will activate on **1783526401 (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder:** op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  > \[!IMPORTANT]
  > **Operators must use op-reth/v2.3.2 with this release.** Prior versions of op-reth will not work with this version of op-node after Karst due to a new engine API method (`getPayloadV5`) used after Karst. See the [notice page](https://docs.optimism.io/notices/upgrade-19) for more details about recommended versions (including flashblocks components).

  > \[!IMPORTANT]
  > **This release removes the request-response p2p sync client** in [#21498](https://github.com/ethereum-optimism/optimism/pull/21498). See this notice [https://docs.optimism.io/notices/req-resp-cl-sync-deprecation](https://docs.optimism.io/notices/req-resp-cl-sync-deprecation).

  Note that some chains have a new `keep_karst_upgrade_gas` boolean field in their superchain registry configuration. Chains with this value set to `true` are encouraged to manually reset their gas limit after Karst activates on Sepolia and Mainnet. See the [notice page](https://docs.optimism.io/notices/upgrade-19) for more information.

  **Update:** op-node contains a [known issue](https://github.com/ethereum-optimism/optimism/issues/21584) that impacts CL-syncing op-reth nodes that prune block bodies (when `--minimal` or `--prune.bodies.distance` are set). A fix is in the works. In the meantime, the recommendation is to enable EL syncing or disable pruning (the latter requires a resync). **Update 2:** the fix is available in [op-node/v1.19.2](https://github.com/ethereum-optimism/optimism/releases/tag/op-node%2Fv1.19.2).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.19.1)
</Update>

<Update label="June 2, 2026" description="v1.19.0">
  > \[!WARNING]
  > This is a mandatory release for all node operators. It includes [Sepolia](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/sepolia/op.toml#L25) and [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork.  (as of `c90d86d`)
  >
  > **Operators must upgrade before the scheduled hard fork times.**
  >
  > The following Sepolia chains will activate on **`1781712001` (Wed Jun 17 2026 16:00:01 UTC)**: op, ink, zora, mode, lisk, metal, unichain, soneium-minato, ethernity, creator-chain-testnet
  >
  > The following Mainnet chains will optimistically activate on **`1783526401` (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder**: op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  > \[!IMPORTANT]
  >
  > `--syncmode.offset-el-safe` now defaults to `12h` for execution-layer sync. This keeps safe and finalized heads behind the synced tip after EL sync completes, matching the OP Mainnet sequencing window. Operators who need the previous behavior can set `--syncmode.offset-el-safe=0`.

  When `--syncmode.offset-el-safe` is configured outside `--syncmode=execution-layer`, op-node now logs a warning and ignores the value instead of failing startup.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.19.0)
</Update>

<Update label="May 19, 2026" description="v1.18.2">
  > \[!NOTE]
  > **Optional upgrade.** This upgrade bumps op-geth and contains a few QOL improvements to op-node.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.18.2)
</Update>

<Update label="May 18, 2026" description="v1.18.1">
  This is an optional release containing only metrics changes.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.18.1)
</Update>

<Update label="May 11, 2026" description="v1.18.0">
  > \[!NOTE]
  > This release removes flags and environment variables related to protocol versions: `--rollup.halt` and `--rollup.load-protocol-versions`.

  🤝 The corresponding op-geth release is [v1.101702.2](https://github.com/ethereum-optimism/op-geth/releases/tag/op-geth%2Fv1.101702.2).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.18.0)
</Update>

<Update label="April 29, 2026" description="v1.17.0">
  This release includes new NUT bundle updates for Karst, improvements to signer rotation, removes/relaxes deprecated ProtocolVersions code and fixes bugs in engine-controller management.

  This version includes Superchain Registry updates for Worldchain and is a required update for that network

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.17.0)
</Update>

<Update label="April 21, 2026" description="v1.16.13">
  > \[!NOTE]
  > This is an optional release that only contains changes for in-development features.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.13)
</Update>

<Update label="April 13, 2026" description="v1.16.12">
  This release is optional, however we recommend updating as it includes stability fixes.

  ⚠️  **Req/Res CL P2P Sync — By Default Is Disabled**

  As previously communicated, we are deprecating the Req/Res CL P2P sync protocol in op-node.

  `--syncmode.req-resp` flag now defaults to `false`, meaning Req/Res CL P2P sync is **disabled by default**.

  Operators that rely on Req/Resp sync should explicitly set the flag to `true` and also update their infrastructure with a healthy EL p2p network.

  🤝 The corresponding op-geth version is `v1.101702.1`.

  ## What's Changed in op-node/v1.16.12

  * op-node: disable Req/Resp p2p sync by default (`--syncmode.req-resp=false`). Operators that rely on Req/Resp sync should explicitly set the flag to `true` ([#18088](https://github.com/ethereum-optimism/optimism/pull/18088))
  * all: upgrade the bundled op-geth dependency for this release candidate ([#19844](https://github.com/ethereum-optimism/optimism/pull/19844))
  * supernode: use denylist output when computing `OptimisticOutputRoot`, improving optimistic output behavior around invalidated blocks ([#19880](https://github.com/ethereum-optimism/optimism/pull/19880))
  * op-service / flashblocks: refactor flashblocks coverage and fix a shutdown race in the flashblock client ([#19942](https://github.com/ethereum-optimism/optimism/pull/19942),
    [#19950](https://github.com/ethereum-optimism/optimism/pull/19950))
  * feat(nuts): add `update-nuts` and `verify-nuts` commands for bundle snapshotting and provenance verification ([#19463](https://github.com/ethereum-optimism/optimism/pull/19463))
  * fault proof test infra: migrate end-to-end fault proof coverage from `CANNON` to `CANNON_KONA` ([#19791](https://github.com/ethereum-optimism/optimism/pull/19791))
  * contracts / dev tooling: remove legacy OPCMv1 Solidity paths and align related deployer/devstack code with OPCMv2-only flows ([#19795](https://github.com/ethereum-optimism/optimism/pull/19795))

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/op-node/v1.16.11...op-node/v1.16.12](https://github.com/ethereum-optimism/optimism/compare/op-node/v1.16.11...op-node/v1.16.12)

  🚢 Docker Image: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.16.12](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.16.12)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.12)
</Update>

<Update label="April 2, 2026" description="v1.16.11">
  This release is optional, however we recommend updating as it includes stability fixes.

  The corresponding op-geth version is v1.101701.0.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.11)
</Update>

<Update label="March 31, 2026" description="v1.16.10">
  This release is optional; however, we recommend updating as it includes a Go version upgrade addressing security fixes, along with enhanced container image hardening.

  🤝 The corresponding op-geth version is [v1.101701.0](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101701.0).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.10)
</Update>

<Update label="March 20, 2026" description="v1.16.9">
  > \[!WARNING]
  > **This is an essential release due to security fixes in op-geth.**

  🤝 The corresponding op-geth version is [v1.101701.0](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101701.0).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.9)
</Update>

<Update label="March 9, 2026" description="v1.16.8">
  > \[!WARNING]
  > **This is an essential release due to security fixes in op-geth.**

  🤝 The corresponding op-geth version is [v1.101609.2](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101609.2).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.8)
</Update>

<Update label="February 26, 2026" description="v1.16.7">
  This is an optional release containing minor optimizations and refactors.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.7)
</Update>

<Update label="February 2, 2026" description="v1.16.6">
  This is a maintenance release.

  🤝 The corresponding op-geth release is [v1.101608.0](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101608.0).

  ## What's Changed in op-node/v1.16.6

  * all: upgrade op-geth (upstream v1.16.8) by @joshklop in [#18338](https://github.com/ethereum-optimism/optimism/pull/18338)
  * op-supernode: multiplex metrics by chain\_id label and serve at a single endpoint by @geoknee in [#18750](https://github.com/ethereum-optimism/optimism/pull/18750)

  **Full Changelog**: [https://github.com/ethereum-optimism/optimism/compare/op-node/v1.16.5...op-node/v1.16.6](https://github.com/ethereum-optimism/optimism/compare/op-node/v1.16.5...op-node/v1.16.6)

  🚢 Docker Image: [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.16.6](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.16.6)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.6)
</Update>

<Update label="January 13, 2026" description="v1.16.5">
  > \[!WARNING]
  > **The corresponding release for op-geth includes security fixes and thus this an essential release for all chains.**

  🤝 The corresponding op-geth release is [v1.101605.0](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101605.0).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.5)
</Update>

<Update label="December 20, 2025" description="v1.16.4">
  > \[!WARNING]
  > **This is an essential release for chains impacted by recent superchain registry updates: [Cyber](https://github.com/ethereum-optimism/superchain-registry/commit/8fadc870f1da03dd176cde2f618ba4d1d424d423), [Funki](https://github.com/ethereum-optimism/superchain-registry/commit/d317982f8a46d385d94dcbd57aa88ffc78cbfa3e)**

  🤝 The corresponding op-geth release is [v1.101604.0](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101604.0) (required for the chains impacted by superchain registry changes).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.4)
</Update>

<Update label="December 4, 2025" description="v1.16.3">
  > \[!IMPORTANT]
  > **This is an essential release for all OP stack chains**

  This release contains an important fix of the blob fetching logic to handle the case where multiple blobs with the same content (but different indices in the block) are requested. Without this fix, a *safe head stall* is possible, due to an error triggered if the batcher submits multiple blobs with the same content (#18492).

  Another edge case in the derivation pipeline is fixed where an overlapping span batch has a first singular batch after the current safe head with an outdated origin. This can happen if a large span batch is posted which overlaps with an auto-derived chain (due to sequencing window elapse). Such a span batch should be dropped, but the derivation pipeline stalled instead. This was recently triggered on an OP Stack testnet and hasn't been observed before (#18283).

  The sequencer's L1 origin selection got fixed to properly handle L1 reorgs (#18233).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.3)
</Update>

<Update label="November 14, 2025" description="v1.16.2">
  > \[!WARNING]
  > **This is an essential release for the following chains due to [Jovian timestamp changes](https://github.com/ethereum-optimism/superchain-registry/commit/59e22d265b7a423b7f51a67a722471a6f3c3cc39): Bob, Lyra, Mint, Orderly, and Polynomial**

  > \[!NOTE]
  > This release also contains World Chain Mainnet's [Isthmus activation timestamp](https://github.com/ethereum-optimism/superchain-registry/pull/1149)

  This release updates Jovian timestamps for the chains listed above. It is optional for all other chains.

  🤝 The corresponding op-geth release is [v1.101603.5](https://github.com/ethereum-optimism/op-geth/releases/tag/v1.101603.5).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.16.2)
</Update>

<Update label="May 24, 2024" description="v1.7.7-rc.1">
  # `op-node` Fjord override flag rc

  This is a release candidate on top of [`op-node/v1.7.6`](https://github.com/ethereum-optimism/optimism/releases/tag/v1.7.6) that adds the missing fjord override flag `--override.fjord` (or env var `OP_NODE_OVERRIDE_FJORD`) to `op-node`. [https://github.com/ethereum-optimism/optimism/pull/10648](https://github.com/ethereum-optimism/optimism/pull/10648)

  🚢 Docker Image [https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.7.7-rc.1](https://us-docker.pkg.dev/oplabs-tools-artifacts/images/op-node:v1.7.7-rc.1)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-node/v1.7.7-rc.1)
</Update>


# op-proposer Releases
Source: https://docs.optimism.io/releases/op-proposer

Release history for op-proposer. L2 output root proposer.

**op-proposer** automates output-root proposal transactions on L1 at a regular interval, submitting claims of L2 state that enable withdrawals. See the [proposals spec](https://specs.optimism.io/protocol/proposals.html).

<Update label="May 23, 2026" description="v1.16.3">
  ## Overview

  This is a patch release of op-proposer. The bulk of the changes are preparation for a future interop release; for non-interop deployments the main change is a bump of the underlying op-geth dependency. It is an optional upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.16.3)
</Update>

<Update label="March 31, 2026" description="v1.16.2">
  This release is optional; however, we recommend updating as it includes a Go version upgrade addressing security fixes, along with enhanced container image hardening.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.16.2)
</Update>

<Update label="March 9, 2026" description="v1.16.1">
  This is an optional release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.16.1)
</Update>

<Update label="February 26, 2026" description="v1.16.0">
  > \[!WARNING]
  > The previous version is v1.10.2. An erroneous tag v1.15.1 got created and this release skips past that faulty tag to ensure proper ordering of public tags is restored.

  > \[!NOTE]
  > This is an optional release. An upgrade is only necessary if you need the new support to fetch proposals via the supernode rpc (#18940)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.16.0)
</Update>

<Update label="January 9, 2026" description="v1.10.2">
  ## Overview

  This is a minor release of op-proposer that includes important bug fixes. It is a required upgrade for all users.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.10.2)
</Update>

<Update label="March 4, 2025" description="v1.10.0">
  This is a recommended release for all users to upgrade.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.10.0)
</Update>

<Update label="March 27, 2023" description="v1.0.1">
  This finalizes op-proposer v1.0.0-rc.2

  * Better handling of underpriced transaction in Tx Manager (#5141)
  * Lots of logging improvements
  * Increased timeouts for sending transactions (#5142)
  * Logger now is log-format by default if it does not detect a terminal (i.e. running in docker) (#5085)
    * Can specify `terminal`, `logfmt`, `json`. `text` means `terminal` if it detects a terminal other it means `logfmt`
    * `color` still defaults to true if it detects a terminal. Only relevant for `terminal` logging.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.0.1)
</Update>

<Update label="March 20, 2023" description="v1.0.0-rc.2">
  * Better handling of underpriced transaction in Tx Manager (#5141)
  * Lots of logging improvements
  * Increased timeouts for sending transactions (#5142)
  * Logger now is log-format by default if it does not detect a terminal (i.e. running in docker) (#5085)
    * Can specify `terminal`, `logfmt`, `json`. `text` means `terminal` if it detects a terminal other it means `logfmt`
    * `color` still defaults to true if it detects a terminal. Only relevant for `terminal` logging.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-proposer/v1.0.0-rc.2)
</Update>


# op-reth Releases
Source: https://docs.optimism.io/releases/op-reth

Release history for op-reth. OP Stack execution layer built on Reth.

**op-reth** is the OP Stack execution layer (EL) built on [Reth](https://reth.rs), a modular, high-performance Rust Ethereum node. It is the recommended execution client for OP Stack chains, replacing op-geth.

<Update label="July 31, 2026" description="v2.4.1">
  > \[!CAUTION]
  > **Breaking change — forwarded txpool admission is now opt-in** ([#22053](https://github.com/ethereum-optimism/optimism/pull/22053)).
  > Nodes that relied on forwarded transactions being admitted to the pool must now enable this explicitly, or they will silently stop accepting them.

  > \[!CAUTION]
  > The historical proofs v1 database format will be deprecated by Aug 31st. Start migrating all your proof nodes to the new v2 format (it is also much more efficient) by regenerating the proofs db at v2 for the required block range.

  > \[!CAUTION]
  > The `import-op` + `import-receipts-op` commands will be deprecated by Aug 31st. If you need continued support for these, please reach out to us.

  > \[!IMPORTANT]
  > Two further transaction-pool admission changes affect which transactions are accepted:
  > L1-info deposit gas is now reserved in the pool gas limit for op-geth parity ([#21548](https://github.com/ethereum-optimism/optimism/pull/21548)),
  > and the Isthmus operator fee is reserved in the pool balance check ([#21609](https://github.com/ethereum-optimism/optimism/pull/21609)).
  > Secure (`wss://`) flashblocks endpoints now work — previously any `wss://` flashblocks URL panicked on the first TLS handshake ([#21898](https://github.com/ethereum-optimism/optimism/pull/21898)).

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.4.1)
</Update>

<Update label="July 20, 2026" description="v2.4.0">
  > \[!NOTE]
  > **Optional upgrade.** New extension points: `OpPoolBuilder` transaction ordering and validator are now injectable ([#21531](https://github.com/ethereum-optimism/optimism/pull/21531)), and `op-alloy-network` makes its reqwest dependency opt-in ([#21175](https://github.com/ethereum-optimism/optimism/pull/21175)). Also fixes Prometheus metric-bucket draining in the op-proofs CLI ([#21596](https://github.com/ethereum-optimism/optimism/pull/21596)). No consensus or operator-facing behavior changes.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.4.0)
</Update>

<Update label="June 26, 2026" description="v2.3.3">
  > \[!Warning]
  > **This is a mandatory release for all node operators.** It includes the [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork. (as of `c90d86d`)
  >
  > The following Mainnet chains will activate on **1783526401 (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder:** op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  > \[!IMPORTANT]
  > **Operators must use op-node/v1.19.1+ with this release.** Prior versions of op-node will not work with this version of op-reth after Karst due to a new engine API method (`getPayloadV5`) used after Karst. See the [notice page](https://docs.optimism.io/notices/upgrade-19) for more details about recommended versions (including flashblocks components).

  op-reth can now load OP Sepolia and OP Mainnet timestamps from the superchain registry. If you are a node operator for either of those chains, you do not need to specify a custom genesis file with the `--chain` flag.

  > \[!CAUTION]
  > **Mandatory upgrade.** Fixes eth\_estimateGas after the Karst hardfork.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.3.3)
</Update>

<Update label="June 26, 2026" description="v2.3.2">
  ### Please use [op-reth v2.3.3](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth%2Fv2.3.3) instead. It contains a bug fix for `eth_estimateGas`.

  ***

  > \[!Warning]
  > **This is a mandatory release for all node operators.** It includes the [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork. (as of `c90d86d`)
  >
  > The following Mainnet chains will activate on **1783526401 (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder:** op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  > \[!IMPORTANT]
  > **Operators must use op-node/v1.19.1+ with this release.** Prior versions of op-node will not work with this version of op-reth after Karst due to a new engine API method (`getPayloadV5`) used after Karst. See the [notice page](https://docs.optimism.io/notices/upgrade-19) for more details about recommended versions (including flashblocks components).

  op-reth can now load OP Sepolia and OP Mainnet timestamps from the superchain registry. If you are a node operator for either of those chains, you do not need to specify a custom genesis file with the `--chain` flag.

  **Update**: we are aware of an issue impacting calls to `eth_estimateGas` after Karst has activated. We have a fix that will be released in op-reth/v2.3.3 prior to mainnet activation. The [notice page](https://docs.optimism.io/notices/upgrade-19#for-app-developers) has more details.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.3.2)
</Update>

<Update label="June 5, 2026" description="v2.3.1">
  > \[!IMPORTANT]
  >
  > This release fixes a deadlock bug that would cause a node to stall, and supersedes the v2.2.5 and v2.3.0 releases.

  > \[!WARNING]
  > This is a mandatory release for all node operators. It includes [Sepolia](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/sepolia/op.toml#L25) and [Mainnet](https://github.com/ethereum-optimism/superchain-registry/blob/c90d86d2ed13541f16daf5ce8707c688723ca039/superchain/configs/mainnet/op.toml#L24) timestamps for the Karst hardfork.  (as of `c90d86d`)
  >
  > **Operators must upgrade before the scheduled hard fork times.**
  >
  > The following Sepolia chains will activate on **`1781712001` (Wed Jun 17 2026 16:00:01 UTC)**: op, ink, zora, mode, lisk, metal, unichain, soneium-minato, ethernity, creator-chain-testnet
  >
  > The following Mainnet chains will optimistically activate on **`1783526401` (Wed Jul 8 2026 16:00:01 UTC)**, pending governance approval: op, ink, zora, mode, lisk, metal, unichain, soneium, ethernity, tbn
  >
  > **Reminder**: op-geth has reached [end of support](https://docs.optimism.io/notices/op-geth-deprecation), so you must be running op-reth to support the karst activation. For more details on this network upgrade see our [notice page](https://docs.optimism.io/notices/upgrade-19).

  **OP Sepolia:**

  * Due to a bug in op-reth, the Karst activation timestamp is **not** loaded from the Superchain Registry for `op-sepolia` and `op`. You must configure it manually by providing a genesis file passed via `--chain `. Download the pre-built genesis file and pass it directly — do not edit the file.
  * [Download genesis.json](https://storage.googleapis.com/oplabs-opc-artifacts/chains/op-sepolia/genesis-karst.json).
  * The genesis file must **not** include an `osakaTime` field. The pre-built file linked above is compatible with `op-reth v2.3.1` as-is. Both the SCR loading bug and this restriction will be fixed in a following op-reth release so this won't be necessary for OP Mainnet.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.3.1)
</Update>

<Update label="May 18, 2026" description="v2.2.3">
  > \[!IMPORTANT]
  > This release contains support for historical proofs storage format v2. It can be enabled by setting `--proofs-history.storage-version=v2`. Note that the proofs data has to be reinitialized if switching to the new storage version format. See [the docs](https://docs.optimism.io/node-operators/reference/op-reth-historical-proof-config#op-reth-historical-proof-configuration) for further details.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.2.3)
</Update>

<Update label="May 11, 2026" description="v2.2.2">
  This is a bug fix release of op-reth.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.2.2)
</Update>

<Update label="May 4, 2026" description="v2.2.1">
  > \[!CAUTION]
  > **Recomended upgrade for operators running op-reth v2.0.0 and above with historical proofs activated**
  > This upgrade fixes some errors in op-reth for historical proofs computation and bumps reth to v2.2.0.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.2.1)
</Update>

<Update label="April 29, 2026" description="v2.2.0">
  This release includes bug fixes, updates to NUT bundle types, and removes deprecated ProtocolVersions support.

  This version includes Superchain Registry updates for Worldchain and is a required update for that network

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.2.0)
</Update>

<Update label="April 21, 2026" description="v2.1.0">
  > \[!IMPORTANT]
  > This is a strongly recommended release as it bumps the underlying reth dependency to its official 2.0.0 release.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.1.0)
</Update>

<Update label="April 15, 2026" description="v2.0.0">
  ## Description

  This release ports most of the changes from `reth 2.0` into `op-reth`. It also ports `op-revm` to `ethereum-optimism/optimism`, completing the migration of the op-variants of paradigm/tempo crates to `ethereum-optimism/optimism`.

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v2.0.0)
</Update>

<Update label="April 2, 2026" description="v1.11.5">
  ## What's Changed in op-reth/v1.11.5

  * fix(proofs-exex): error if state unavailable instead of falling back to historical provider by @dhyaniarun1993 in [#19855](https://github.com/ethereum-optimism/optimism/pull/19855)
  * fix(op-alloy): resolve `NetworkWallet` conflict with alloy 1.8 by @suchapalaver in [#19756](https://github.com/ethereum-optimism/optimism/pull/19756)
  * feat(op-reth): Drop interop transactions after reorg by @wwared in [#19814](https://github.com/ethereum-optimism/optimism/pull/19814)

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v1.11.5)
</Update>

<Update label="March 17, 2026" description="v1.11.3">
  > \[!WARNING]
  > **This is an essential bug fix release for all chains. See the upstream release notes ([https://github.com/paradigmxyz/reth/releases/tag/v1.11.1](https://github.com/paradigmxyz/reth/releases/tag/v1.11.1), [https://github.com/paradigmxyz/reth/releases/tag/v1.11.2](https://github.com/paradigmxyz/reth/releases/tag/v1.11.2) and [https://github.com/paradigmxyz/reth/releases/tag/v1.11.3](https://github.com/paradigmxyz/reth/releases/tag/v1.11.3)) for guidance regarding backwards compatibility.**

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v1.11.3)
</Update>

<Update label="February 20, 2026" description="v1.11.0">
  ## Description

  First `op-reth` release from the optimism monorepo.

  Major changes:

  * Imports historical proofs generation tooling to `op-reth`

  [View full release on GitHub →](https://github.com/ethereum-optimism/optimism/releases/tag/op-reth/v1.11.0)
</Update>


# proxyd Releases
Source: https://docs.optimism.io/releases/proxyd

Release history for proxyd. RPC request router and proxy.

**proxyd** is an RPC request router and proxy with method whitelisting, backend load balancing, automatic retries, and consensus state tracking across multiple backend nodes.

<Update label="July 27, 2026" description="v4.30.0">
  ## Changelog

  * 42098f9fc1e690cc1ff57f141cc88fbc434b8041 chore(docker): migrate infra Dockerfiles to Chainguard wolfi-base (#671)
  * 07357cbbfe95f815826b2f612821685b9bff6739 chore: bump vulnerable dependencies to remediate CVEs (Go, yarn, poetry) (#670)
  * 95d27e324eb6c558a269d051e7d34f746c8a87a5 proxyd: add per-RPC-call metrics for usage and error-rate SLO (#676)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.30.0)
</Update>

<Update label="July 17, 2026" description="v4.29.1">
  ## Changelog

  * 1f4e368306dadfc7ccdee3e57e3a56107b235d36 fix(proxyd): fix tx\_validation\_middleware RPC error when failing close against a failing screening-service/provider (#669)
  * be5330115c4f3bc1651dd5d82245015f4e30c2d2 fix(proxyd): log unexpected block tags as decimal not hex (#661)
  * 151d922565a09208bdd86341001db0bd5c957c04 fix(proxyd): tighten interop access-list descriptor timestamp (#662)
  * a82c8a58b988872a4e6dd34d06a1c4c9b1c0f75b proxyd: Fix a race between reading results and draining discarded ones (#663)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.29.1)
</Update>

<Update label="June 15, 2026" description="v4.29.0">
  ## Changelog

  * d698adc9486b710db485fc8686e904ecbbb1f318 fix(proxyd): route websocket txs through filters (#655)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.29.0)
</Update>

<Update label="June 12, 2026" description="v4.28.1">
  ## Changelog

  * 5a090ab3309c610c054bb65568a900713359b1a0 fix(proxyd): instrumentation of unserviceable requests metric (#657)
  * c0182548795f5ff8f4d79aaece2281e6c0f1f0c4 fix(proxyd): parse ipv6 remote addresses (#656)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.28.1)
</Update>

<Update label="June 11, 2026" description="v4.28.0">
  ## Changelog

  * ac43a3cc9b2f9af79aadefe55c7bba7137e560f1 chore(proxyd): run golangci-lint in make lint target to match CI (#650)
  * 327f5f5412f55413f13cbe4321232b7b9021ce61 feat(proxyd): fail-closed-by-default interop filtering (#649)
  * a2097d08e8fe3b82ff1630e7e894341d4390103d fix(proxyd): synchronize AvgSlidingWindow access (#653)
  * a6db36e7e601ca104bbe3d3296407bb440f472e3 refactor(proxyd): rename supervisor terminology to interop-filter (#648)
  * 8b84dab92db7e20d843e482190db528592324811 refactor(proxyd): unified transaction filter on the submission path (#654)
  * 0341b6abe5bbcde18985a1e1b58f7824fb8d311a test(proxyd): fix race in TestMulticall request-count assertion (#652)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.28.0)
</Update>

<Update label="June 8, 2026" description="v4.27.5">
  ## Changelog

  * 1311f2a834de36a980180414fa5f093714050c44 feat(proxyd): add agreement interop validation strategy (#640)
  * f8ff4e4069bd00f1099d748a161e8b9ba45bf8ac feat(proxyd): add metrics for interop validation outcomes (#643)
  * f803573ccd27d0c906b0b162219b278919e917be feat(proxyd): halt CL consensus on unresolvable output root split (#646)
  * bbb05429712bafdd7be4849951820eca25795abe fix(proxyd): allow CL backends at network genesis (block 0 with valid hash) (#645)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.27.5)
</Update>

<Update label="May 27, 2026" description="v4.27.4">
  ## Changelog

  * 7d6b7b2de084d458f0199f3ee23502f10e1120e1 feat(proxyd): switch to InteropFilterClient (interop\_checkAccessList) (#635)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.27.4)
</Update>

<Update label="April 16, 2026" description="v4.27.1">
  ## Changelog

  * c6fd4aa9f40b3ff1190a36b012fc780f3fb7ca26 feat(proxyd): add proxyd\_up metric with build info at startup (#604)
  * 89ca421d0f7c8fe7c16b0a2d08673b43749071c1 fix: make consensus\_layer\_consensus\_aware logging more verbose (#606)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.27.1)
</Update>

<Update label="April 14, 2026" description="v4.27.0">
  ## Changelog

  * 0ad43f8f512820a4f1418a2e401fdef7acdd9f49 feat: proxyd consensus-layer consensus aware mode (#597)
  * 52d51039dbaf2258e0f96f3c9c08f5174a7d22e3 refactor(proxyd): extract updateELBackend from UpdateBackend (#595)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.27.0)
</Update>

<Update label="April 1, 2026" description="v4.26.1">
  ## Changelog

  * 3b8b517fe7faf050c59c11f6bc5a8ebcac4c7231 feat(proxyd): track block hashes in consensus state (#591)
  * 2a15d48816b28554f77a17b9e4b718e5118a3a8b refactor(proxyd): collapse ConsensusTracker interface and introduce backendState (#588)
  * 96745260ec481be61a6b8bb41494083ee344b386 refactor(proxyd): extract findConsensusBlock walk-back into reusable function (#590)
  * 497f5751d04f14e41ec82b97534f6365759fc5b2 refactor(proxyd): rename EL-specific functions and fix type assertion panics (#592)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.26.1)
</Update>

<Update label="March 12, 2026" description="v4.25.1">
  ## Changelog

  * f46da0df2e91e013cb19ff6aa7a2e8d5def7b98f fix(proxyd): pass chain ID to interop access list validation (#564)
  * 10ba4dd73d44dc6c19c8b8d027ee1fe8a033d3e9 fix(proxyd): separate context for tx validation  middleware (#567)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.25.1)
</Update>

<Update label="February 12, 2026" description="v4.25.0">
  ## Changelog

  * 9e3b5d01d23a198afda1b750d649601ac911a91d feat: proxyd update consensus mode out of range requests to be api-spec compliant (#552)
  * de49cc1875db352b3623a2404b277a468094f162 fix: FIx windows build (#549)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.25.0)
</Update>

<Update label="November 20, 2025" description="v4.23.0">
  ## Changelog

  * 96e6b6ad391c8916ea63293af941dae5ac9b28af proxyd: security oriented fixes (#493)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.23.0)
</Update>

<Update label="October 28, 2025" description="v4.22.0">
  ## Changelog

  * 65745cb2cf9f16432e5ba8c401dc8912cc936a53 feat(proxyd): max block range config (#494)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.22.0)
</Update>

<Update label="October 1, 2025" description="v4.21.0">
  ## Changelog

  * 30983b621f3d8e365d5ab3b2b2688f41ead24a2a Add transaction hash logging for sendRawTransaction methods (#481)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.21.0)
</Update>

<Update label="September 30, 2025" description="v4.20.0">
  ## What's Changed

  * Enable public access and authentication by @cody-wang-cb in [https://github.com/ethereum-optimism/infra/pull/424](https://github.com/ethereum-optimism/infra/pull/424)

  **Full Changelog**: [https://github.com/ethereum-optimism/infra/compare/proxyd/v4.19.0...proxyd/v4.20.0](https://github.com/ethereum-optimism/infra/compare/proxyd/v4.19.0...proxyd/v4.20.0)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.20.0)
</Update>

<Update label="September 30, 2025" description="v4.19.0">
  ## What's Changed

  * proxyd: Add fusaka blob transaction support by @mslipper in [https://github.com/ethereum-optimism/infra/pull/464](https://github.com/ethereum-optimism/infra/pull/464)
  * fix: improve rpc metric from unknown to method\_not\_allowed by @jelias2 in [https://github.com/ethereum-optimism/infra/pull/465](https://github.com/ethereum-optimism/infra/pull/465)

  **Full Changelog**: [https://github.com/ethereum-optimism/infra/compare/proxyd/v4.18.0...proxyd/v4.19.0](https://github.com/ethereum-optimism/infra/compare/proxyd/v4.18.0...proxyd/v4.19.0)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.19.0)
</Update>

<Update label="July 30, 2025" description="v4.18.0">
  ## Changelog

  * b543e5e14b157ee408e558bf0dbf688dd63dfb43 Proxyd: Allow backend ResponseTimeout to be set in ms + to be configurable per backend (#436)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.18.0)
</Update>

<Update label="July 8, 2025" description="v4.17.1">
  ## What's Changed

  * feat(proxyd): 499 error code for context canceled by @charlesma4 in [https://github.com/ethereum-optimism/infra/pull/420](https://github.com/ethereum-optimism/infra/pull/420)

  **Full Changelog**: [https://github.com/ethereum-optimism/infra/compare/proxyd/v4.17.0...proxyd/v4.17.1](https://github.com/ethereum-optimism/infra/compare/proxyd/v4.17.0...proxyd/v4.17.1)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.17.1)
</Update>

<Update label="July 8, 2025" description="v4.17.0">
  ## Changelog

  * 2d72a874e59bbf7038e1f3f2868a02377f9f9561 proxyd: adds conditional support for sender rate limiting (#421)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.17.0)
</Update>

<Update label="June 12, 2025" description="v4.16.2">
  ## What's Changed

  * fix: shift the req size limit check to happen only upon the interop transaction recognition by @yashvardhan-kukreja in [https://github.com/ethereum-optimism/infra/pull/407](https://github.com/ethereum-optimism/infra/pull/407)

  * Bug fix: The interop max payload and rate limit were being applied to all eth\_sendRawTransactions, this release fixes that bug

  **Full Changelog**: [https://github.com/ethereum-optimism/infra/compare/op-acceptor/v0.4.1...proxyd/v4.16.2](https://github.com/ethereum-optimism/infra/compare/op-acceptor/v0.4.1...proxyd/v4.16.2)

  [View full release on GitHub →](https://github.com/ethereum-optimism/infra/releases/tag/proxyd/v4.16.2)
</Update>


# Choose your node stack
Source: https://docs.optimism.io/use-cases/choose-your-node-stack

Pick the consensus and execution clients for an OP Stack node based on what the node is for, with review-dated support facts.

This guide takes an operator who is about to run an OP Stack node and turns
"which client software?" into a sequenced decision: fix the two-client
shape, rule out end-of-support software, choose the execution and consensus
clients, and match the pairing to the job the node does. It centers on the
software Optimism maintains: `op-node` and `kona-node` on the consensus
layer, `op-reth` on the execution layer, and the special-purpose
`op-supernode` and legacy Geth. Support status changes over time; the
facts on this page are stated as of the `last-reviewed` date above, and
each exit links where to re-check them.

## Is this guide for you?

Use this guide if:

* You are choosing software for a new node on an OP Stack chain (OP
  Mainnet, another OP Stack chain, or your own chain), or re-evaluating
  an existing node after the op-geth end of support.
* You want the selection reasoning, not the setup commands.

If you already know your stack and want to run it, go straight to the
[Docker node tutorial](/node-operators/tutorials/node-from-docker) or the
[from-source tutorial](/node-operators/tutorials/run-node-from-source). If
you are choosing infrastructure for a whole chain launch, sequencers
included, see
[Launch a chain with fault proofs and HA sequencing](/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing).
If your node runs but misbehaves, use the
[troubleshooting guide](/node-operators/guides/troubleshooting).

## Before you start

You should already know:

* Which network the node serves, and whether it is in the
  [superchain-registry](/op-stack/protocol/superchain-registry) (registry
  chains can be selected by name in both consensus clients; custom chains
  supply their own configuration).
* The job the node does: public RPC, personal verifier, sequencer,
  fault-proof infrastructure, or archive/analytics. Step 5 keys on this.
* Your hardware envelope. Read the
  [system requirements](/node-operators/overview#system-requirements) and
  take away the 16 GB RAM baseline for OP Mainnet and that archive nodes
  need multiple terabytes of NVMe and grow much faster than full nodes.

## Step 1: Fix the shape: one consensus client, one execution client

Every OP Stack node is two processes: a consensus client (rollup node) that
derives and relays the canonical chain, and an execution client that runs
the EVM and holds state, connected 1:1 over the authenticated Engine API.
Read the [node architecture overview](/node-operators/reference/architecture)
and take away:

* The two-client split and which RPCs live on which side; you are making
  two client choices, not one.
* The 1:1 rule: never multiple execution clients behind one consensus
  client or vice versa. Both client configuration guides (the Step 3 and
  Step 4 reads) open with this warning.

## Step 2: Rule out end-of-support software

<Warning>
  **op-geth has reached end-of-support (2026-05-31) and does not support the now-active Karst hardfork, so op-geth nodes can no longer follow the canonical chain.** Migrate to op-reth, the primary supported execution client. See the [op-geth deprecation notice](/notices/archive/op-geth-deprecation) for the full migration plan.
</Warning>

Read the [end-of-support notice](/notices/archive/op-geth-deprecation) and take
away, as of 2026-07-21:

* **op-geth is not a candidate for any new node**; see the warning above.
* **op-program has also reached end of support**, replaced by kona-client
  for fault proofs. This affects Step 5's fault-proof row, not your
  ordinary node choice.
* **op-node is not deprecated**, and kona-node is not required for
  anything: the fault-proof migration to kona-client works with an
  ordinary op-node.

One more retirement outside that notice: **op-erigon, a third-party
execution client, has also been deprecated** by its maintainer; see the
[sunsetting announcement](https://www.sunnyside.io/blogs/sunsetting-op-erigon).
It is not a candidate for any new node either.

## Step 3: Choose the execution client

Read the [execution client configuration guide](/node-operators/guides/configuration/execution-clients)
and take away each client's minimal configuration and where its full
reference lives. The selection logic:

| If ...                                     | Choose ...           | Because ...                                                                                                                                                                                      |
| ------------------------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| You want the default, for any node role    | op-reth              | It is the primary supported execution client, and the implementation maintained by Optimism: new OP Stack feature development, including hardfork support, happens on op-reth. As of 2026-07-21. |
| The node is an existing op-geth deployment | Migration to op-reth | op-geth is end-of-support; the [notice](/notices/archive/op-geth-deprecation) carries the migration plan.                                                                                        |

Third-party execution clients maintained outside Optimism also exist, such
as Nethermind; they are configured and supported through their own
documentation, not these docs.

Two op-reth follow-on decisions to make now rather than after sync:

* **Archive or full**: op-reth is an archive node by default; pass
  `--full` for a pruned full node. Body pruning is unsupported. See
  [pruning op-reth](/node-operators/guides/management/archive-node#pruning-op-reth).
* **Historical proofs**: infrastructure that serves withdrawal proving on
  permissionless fault-proof chains needs the historical-proofs store
  (op-reth v2.2.3 or later); follow the
  [historical proofs tutorial](/node-operators/tutorials/reth-historical-proofs).
  The store only fills forward from the moment you enable it, so a node
  that turns it on late cannot serve the full retention window until it
  has run that long; decide per node role in Step 5.

## Step 4: Choose the consensus client

Read the [consensus client configuration guide](/node-operators/guides/configuration/consensus-clients)
and take away each client's minimal flags and sequencer additions. The
selection logic:

| If ...                                                        | Choose ...   | Because ...                                                                                                                                                                                                                                                      |
| ------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You want the default, for any node role                       | op-node      | It is the reference implementation, is explicitly not deprecated, and its default engine kind (`--l2.enginekind=reth`) already matches the Step 3 default.                                                                                                       |
| You want to try the in-development Rust consensus node        | kona-node    | It ships tagged releases, superchain-registry support, and sequencer/conductor integration, but it is not yet production ready: its documentation marks it experimental and in active development, so give it a role where that is acceptable. As of 2026-07-21. |
| The node must follow every chain in an interop dependency set | op-supernode | It hosts a virtual op-node per chain in one process and adds cross-chain message verification; it is in active development, tracking a v0.2.x release candidate. As of 2026-07-21.                                                                               |

One pairing note: op-node's `--l2.enginekind` flag tunes its Engine API
behavior to the execution client, and its default is `reth`, so the Step 3
default needs no extra flag; the
[consensus client guide](/node-operators/guides/configuration/consensus-clients#l2-enginekind)
covers the other values.

## Step 5: Match the pairing to the node's job

The connective logic across both choices, by node role:

| If the node is ...                                       | Choose ...                                                                             | Because ...                                                                                                                                                                                                                                        |
| -------------------------------------------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A public RPC or analytics node                           | op-node + op-reth archive (the default, no pruning flags)                              | Historical state queries need archive data, and op-reth is archive by default; front it per the [network design example](/chain-operators/guides/management/network-architecture#public-rpc).                                                      |
| A personal verifier or app-team node                     | op-node + op-reth with `--full`                                                        | A pruned full node is hundreds of gigabytes instead of terabytes, and trustless verification does not need historical state.                                                                                                                       |
| A sequencer                                              | op-node + op-reth, with op-conductor for high availability                             | Sequencer flags and conductor integration are the documented production path; the [launch guide](/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing) covers the topology.                                                               |
| Fault-proof infrastructure (backing op-challenger)       | op-node with SafeDB + op-reth archive with historical proofs                           | The challenger requires a SafeDB-enabled rollup node and an archive execution client with the proofs store seeded; the [challenger guide](/use-cases/run-a-fault-proof-challenger#step-4-provision-the-four-endpoints) details all four endpoints. |
| A complete OP Mainnet archive including pre-Bedrock data | The Step 3/4 pair plus [legacy Geth](/node-operators/guides/configuration/legacy-geth) | Pre-Bedrock (2023) historical queries on OP Mainnet are served by a separate legacy node; nothing else needs it.                                                                                                                                   |
| Following an interop dependency set                      | op-supernode + one execution client per chain                                          | One process replaces an op-node per chain and shares the L1 client and beacon plumbing; see the [supernode guide](/node-operators/guides/configuration/supernode).                                                                                 |

## Step 6: Deploy and verify the choice

Stand the pair up with the
[Docker node tutorial](/node-operators/tutorials/node-from-docker) (op-reth +
op-node in one compose file) or the
[from-source tutorial](/node-operators/tutorials/run-node-from-source), then
confirm the choice behaves like the row you picked:

* **Versions**: the running versions match the latest stable releases on
  the [releases page](/releases); the page is regenerated from the release
  feed, so it is the freshness check for this guide's dated claims.
* **Sync**: `optimism_syncStatus` on the consensus client (see the
  [op-node JSON-RPC reference](/node-operators/reference/op-node-json-rpc#optimism_syncstatus))
  shows the unsafe head tracking the chain head you see on a public
  explorer, and the execution client reports sync complete.
* **Disk shape**: an archive node's disk grows like an archive node's; if
  you meant to run full and the datadir is heading toward terabytes,
  revisit the pruning flags from Step 3 before the disk fills.
* **Role checks**: whatever Step 5 row you picked, exercise its defining
  feature once: a historical state query on an archive node, a
  `debug`-namespace proof call on challenger infrastructure, or a
  cross-chain message check on a supernode.

## Next steps

* [op-node configuration reference](/node-operators/reference/op-node-config):
  the full flag catalogue, generated from the op-node flag definitions at
  the release tag named on the page and regenerated when a new finalized
  release is published.
* [op-reth configuration reference](/node-operators/reference/op-reth-config):
  routes to the imported op-reth CLI reference (versioned with the op-reth
  source tree) and the historical-proofs configuration pages.
* [kona-node documentation](/node-operators/kona-node/install/overview): the
  install-and-run book for the Rust consensus client, in the Node
  Operators section of these docs.
* [Consensus-layer sync](/node-operators/reference/consensus-layer-sync):
  why execution-layer (snap) sync is the recommended mode and what
  consensus-layer sync is for, when you tune how the pair syncs.
* [reth.rs OP Stack chapter](https://reth.rs/run/opstack): upstream
  op-reth operational documentation. External book maintained with reth
  releases, as of 2026-07-21.


# Implement a custom deposit flow
Source: https://docs.optimism.io/use-cases/implement-a-custom-deposit-flow

Build an L1 to L2 deposit path for your application, choosing the right contract entry point and handling gas, aliasing, and failed messages.

This guide takes an app developer whose contracts need to trigger effects on
an OP Stack chain from Ethereum and walks the deposit path in one pass: how a
deposit travels from L1 to L2, which of the three contract entry points fits
your use case, and the safety details (gas limits, address aliasing, failed
messages) that custom integrations get wrong. It involves the `StandardBridge`,
the `CrossDomainMessenger` pair, and the `OptimismPortal` contract.

## Is this guide for you?

Use this guide if:

* You are building contracts or backend infrastructure that initiate L2
  actions from L1: a custom token bridge, an L1-controlled L2 contract, or
  a protocol that must be able to force transactions into the L2.
* You need to choose *which* contract interface to build against, not just
  follow one path.

If you only need to move ETH or a standard ERC-20 between layers, use the
[Standard Bridge](/app-developers/guides/bridging/standard-bridge) as is. If
your goal is L2 to L1 (withdrawals), read the
[withdrawal flow explanation](/op-stack/bridging/withdrawal-flow) instead; the
7-day challenge period makes it a different problem. For messaging between two
OP Stack chains rather than L1 and L2, see
[interop explainer](/op-stack/interop/explainer). This guide covers the L1 to
L2 direction only.

## Before you start

You should already have:

* A Solidity development environment and a funded account on Sepolia and
  OP Sepolia (or another OP Stack testnet).
* Basic familiarity with how contracts call each other on a single chain;
  the [bridging basics guide](/app-developers/guides/bridging/basics) sets
  the baseline vocabulary.

## Step 1: Map the deposit path

Every L1 to L2 write, whatever interface you use, ends as a call to the
`OptimismPortal` contract's `depositTransaction` function, which emits a
`TransactionDeposited` event that the rollup node derives into an L2
transaction. Read the [deposit flow explanation](/op-stack/bridging/deposit-flow)
and take away:

* The encapsulation chain: your contract calls a messenger, the messenger
  calls the portal, the portal emits the event, and `op-node` turns the
  event into an L2 transaction. Each layer you use adds convenience and
  safety on top of the one below it.
* That deposits are included by derivation, not by the sequencer's grace:
  once the L1 transaction is confirmed, the L2 transaction will happen.

Then skim [Sending data between L1 and L2](/app-developers/guides/bridging/messaging)
and take away the `sendMessage(target, message, minGasLimit)` interface shape,
the 1 to 3 minute L1 to L2 delivery time, and how the portal charges for L2
execution by burning L1 gas.

## Step 2: Choose your entry layer

This is the decision that shapes everything downstream. Work down the table
and stop at the first row that fits:

| If ...                                                                                                               | Choose ...                                           | Because ...                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You are moving ETH or ERC-20 tokens and standard lock-and-mint accounting fits                                       | `StandardBridge`, extended if necessary              | It is the audited path, it is compatible with the Superchain Bridges UI and the token list, and [building a custom bridged token](/app-developers/tutorials/bridging/standard-bridge-standard-token) covers most "the standard token doesn't fit" cases without a new bridge. |
| You are calling an L2 contract and want delivery guarantees                                                          | `L1CrossDomainMessenger.sendMessage`                 | The messenger records messages that fail on L2 and lets anyone replay them with more gas, and the target can authenticate the L1 sender via `xDomainMessageSender`.                                                                                                           |
| You need raw deposited transactions: forced inclusion when the sequencer censors you, or full control of the L2 call | `OptimismPortal.depositTransaction`, called directly | Nothing sits between you and derivation. But you give up the messenger's replay safety net and sender authentication, and address aliasing applies to your contract (Step 3).                                                                                                 |

For the current contract interfaces, use the
[contracts-bedrock reference](https://devdocs.optimism.io/contracts-bedrock)
or the source on `develop`:
[`StandardBridge.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/StandardBridge.sol),
[`CrossDomainMessenger.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/universal/CrossDomainMessenger.sol),
and [`OptimismPortal2.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol).
Deployed addresses for OP Mainnet and OP Sepolia are on the
[contract addresses page](/op-mainnet/network-information/op-addresses).

If you concluded you need a custom bridge, read the
[custom bridges guide](/app-developers/guides/bridging/custom-bridge) and take
away the recommendation to extend `StandardBridge` rather than start from
scratch, and the requirement to register bridged tokens in the Superchain
Token List.

## Step 3: Get the safety details right

Three properties of the deposit path surprise custom integrations. Check each
against your design before writing code:

* **Address aliasing.** When a *contract* (not an EOA) initiates a deposit,
  the `from` address on L2 is the L1 contract's address plus a constant
  offset. If your L2 contract checks `msg.sender` against an L1 contract
  address, it must check the aliased form. Read
  [address aliasing in the deposits spec](https://specs.optimism.io/protocol/deposits.html?utm_source=op-docs\&utm_medium=docs#address-aliasing)
  and take away the offset constant and the reason it exists. The messenger
  abstracts this away; portal-direct integrations must handle it themselves.
* **Gas limits are minimums with real floors.** The `minGasLimit` you pass
  to `sendMessage` is a minimum for the L2 execution, and the portal
  enforces its own data-size-scaled minimum on every deposit (see
  `minimumGasLimit` in
  [`OptimismPortal2.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol))
  plus a hard cap on deposit calldata size. The L1 gas burned to pay for L2
  gas is dynamic, so follow the
  [fee guidance in the messaging guide](/app-developers/guides/bridging/messaging#fees-for-sending-data-between-l1-and-l2)
  and take away the recommendation to buffer your gas limit by at least 20%.
* **Sender authentication.** On the receiving side, `msg.sender` is the L2
  messenger, not your L1 contract. Read
  [accessing msg.sender](/app-developers/guides/bridging/messaging#accessing-msgsender)
  and take away the `xDomainMessageSender` check pattern. Portal-direct
  deposits do not get this: the L2 target sees only the (aliased) `from`.

## Step 4: Build against the pattern

Each entry layer has a worked, runnable path. Follow the one matching your
Step 2 decision; each is a tutorial, so it includes environment setup this
guide skips:

* **Standard Bridge with a custom token**: follow the custom-token path of
  [Create an L2 token for the Standard Bridge](/app-developers/tutorials/bridging/standard-bridge-standard-token)
  to deploy an `OptimismMintableERC20` variant with custom logic.
* **Messenger-based contract calls**: follow
  [Communicating between contracts on L1 and L2](/app-developers/tutorials/bridging/cross-dom-solidity)
  for the full send, relay, and authenticate loop in Solidity.
* **Portal-direct deposits**: there is no dedicated tutorial; work from the
  `depositTransaction` interface in
  [`OptimismPortal2.sol`](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol)
  and the
  [deposits spec](https://specs.optimism.io/protocol/deposits.html?utm_source=op-docs\&utm_medium=docs#user-deposited-transactions),
  and keep Step 3's aliasing and gas rules in front of you.

## Step 5: Test the flow locally

Deposits cross two chains, so test against a local multi-chain environment
before testnet. Follow the
[supersim deposit transactions tutorial](/app-developers/tutorials/bridging/deposit-transactions)
and take away how supersim surfaces the `OptimismPortal`,
`L1CrossDomainMessenger`, and `L1StandardBridge` addresses for each local
chain, and how to watch a deposit land on the L2 without running a full
derivation pipeline.

## Step 6: Plan for failed deposits

An L2 execution can fail (usually out-of-gas), and your design must decide in
advance who notices and who pays for the retry:

| If ...                                              | Choose ...                                         | Because ...                                                                                  |
| --------------------------------------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| You went through the messenger (or Standard Bridge) | A monitoring-and-replay runbook                    | Failed messages are recorded on L2 and anyone can replay them later with a higher gas limit. |
| You went portal-direct                              | Conservative gas limits and idempotent L2 handlers | There is no recorded-message safety net; a failed deposited transaction is final.            |

For the messenger path, follow the
[replaying a failed deposit tutorial](/app-developers/tutorials/bridging/replay-failed-deposit)
and take away how a failed message is detected and the replay call that
retries it with more gas.

## Step 7: Verify the outcome

Run your flow end to end on testnet and confirm each link of the chain:

* **The L1 side**: your transaction emits a `TransactionDeposited` event
  from the `OptimismPortal` (directly or via the messenger). This event is
  the canonical proof the deposit entered the system.
* **The L2 side**: the corresponding L2 transaction appears within a few
  minutes, and the target contract observed the sender it expected
  (`xDomainMessageSender` for messenger flows, the aliased address for
  portal-direct flows).
* **The failure drill** (messenger flows): force one deposit to fail with an
  undersized `minGasLimit`, confirm it is recorded as a failed message, and
  replay it successfully per Step 6.
* **Token accounting** (bridge flows): amounts locked on L1 match amounts
  minted on L2, and the round trip back burns and releases correctly.

## Next steps

* [Deposits in the protocol specs](https://specs.optimism.io/protocol/deposits.html?utm_source=op-docs\&utm_medium=docs):
  the normative definition of deposited transactions, the deposit contract,
  and address aliasing.
* [contracts-bedrock reference](https://devdocs.optimism.io/contracts-bedrock):
  generated interface documentation for the current contracts, for when you
  need the exact function and event signatures.
* [`OptimismPortal2.sol` on develop](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L1/OptimismPortal2.sol):
  the deposit entry point's source, including `minimumGasLimit` and the
  calldata cap. Tracks the `develop` branch, so read it alongside the
  release your chain actually runs.
* [Superchain Token List](/app-developers/reference/tokens/tokenlist):
  where custom-bridged tokens must be registered before users can find
  them.


# Solution guides
Source: https://docs.optimism.io/use-cases/index

Solution guides that sequence the OP Stack documentation into one paved path per real operator or developer goal.

Each page in this section is a **solution guide**: one goal that in practice
spans several components, sequenced as a single in-site path. A solution
guide links each stop to its canonical page and states what to take from it,
adds the decision logic that no single component page can own, and leaves
the site only through curated, working exits. If your goal is listed here,
start here instead of assembling the path yourself.

<CardGroup>
  <Card title="Tune batcher costs" href="/use-cases/tune-batcher-costs">
    Cut what your chain spends posting data to L1, and recover what you do
    spend through your fee parameters.
  </Card>

  <Card title="Run a fault-proof challenger" href="/use-cases/run-a-fault-proof-challenger">
    Stand up an op-challenger that defends your chain, from bond budgeting
    through configuration and monitoring.
  </Card>

  <Card title="Implement a custom deposit flow" href="/use-cases/implement-a-custom-deposit-flow">
    Build an L1 to L2 deposit path, choosing the right contract entry point
    and handling gas, aliasing, and failures.
  </Card>

  <Card title="Launch a chain with fault proofs and HA sequencing" href="/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing">
    Take a chain to production with withdrawals secured by fault proofs and
    a sequencer cluster that survives node failures.
  </Card>

  <Card title="Choose your node stack" href="/use-cases/choose-your-node-stack">
    Pick the consensus and execution clients for a node based on the job it
    does, with review-dated support facts.
  </Card>

  <Card title="Looking for something else?" href="/">
    Browse the documentation by role — app developers, chain operators, node
    operators, and protocol readers.
  </Card>

  <Card title="Rather run less of this yourself?" href="https://optimism.io/op-enterprise?utm_source=docs&utm_medium=docs&utm_campaign=op-enterprise">
    <OpEnterpriseCalloutBody />
  </Card>
</CardGroup>


# Launch a chain with fault proofs and HA sequencing
Source: https://docs.optimism.io/use-cases/launch-a-chain-with-fault-proofs-and-ha-sequencing

Take an OP Stack chain to production with a working fault-proof system and a high-availability sequencer cluster, from contract deployment through failover drills.

This guide takes a chain operator from "my testnet deployment works" to a
production launch with the two properties that are hard to retrofit: a
fault-proof system that secures withdrawals from day one, and a sequencer
topology with no single point of failure. It involves `op-deployer` and your
chain's dispute game contracts on L1, a cluster of `op-node` + `op-reth`
sequencers managed by `op-conductor`, and the L1-facing services
(`op-batcher`, `op-proposer`, `op-challenger`, `op-dispute-mon`) that keep
the chain posting, proposing, and defended.

## Is this guide for you?

Use this guide if:

* You are planning a production OP Stack chain launch: real users will
  depend on its uptime and withdraw real value through its fault-proof
  system.
* You control the deployment (the `op-deployer` intent and the resulting
  contracts) and the infrastructure the chain's services run on.

If you are deploying an OP Stack chain for the first time, run the
[create L2 rollup tutorial](/chain-operators/tutorials/create-l2-rollup)
on a testnet first; this guide assumes that experience and adds the
production decisions on top. If your chain is already live and you only want
to add sequencer high availability, skip to Step 4 and the
[op-conductor setup guide](/chain-operators/tools/op-conductor/setup). If
your chain is already live on permissioned fault proofs and you want to go
permissionless, go straight to the
[permissionless migration tutorial](/chain-operators/tutorials/migrating-permissionless).

If you want these properties without operating them, or with OP Labs
engineering supporting your team, see
[OP Enterprise](https://optimism.io/op-enterprise?utm_source=docs\&utm_medium=docs\&utm_campaign=op-enterprise);
this guide is the reference for what a production launch involves either way.

## Before you start

You should already have:

* A completed testnet deployment, so the `op-deployer` intent-and-apply
  workflow and the per-service setup steps are familiar.
* Funded L1 accounts for the batcher, proposer, and challenger, managed
  under the signing posture from the
  [key management guide](/chain-operators/guides/management/key-management).
* Infrastructure that can run three sequencer nodes in separate failure
  domains (regions or availability zones) on a private network, plus the
  supporting services. op-conductor's RPC does no authentication, so the
  cluster must not be publicly reachable.

## Step 1: Understand what launch day ships

A chain launched today starts with fault proofs, but not the fully
permissionless form. Read the
[fault proofs explainer](/op-stack/fault-proofs/explainer) and take away:

* Proposals about your chain's state settle through dispute games created
  via the `DisputeGameFactory`, and withdrawals are proven against those
  proposals.
* The safety net behind the games: the Guardian can blacklist a bad game
  or change the respected game type, and bonds sit in `DelayedWETH` so
  incorrect payouts can be recovered.

Then read the note in
[deploying new dispute games with OPCM](/chain-operators/tutorials/dispute-games#understanding-dispute-games)
and take away the launch-day reality: chains deployed with `op-deployer`
initially include only the **permissioned** dispute game, in which the
proposer and challenger are specific addresses holding
[privileged roles](/op-stack/protocol/privileged-roles). Permissionless
fault proofs are a post-launch switch you schedule in Step 7, not a box you
tick at deployment.

## Step 2: Deploy the contracts with standard proof parameters

Deploy with [op-deployer](/chain-operators/tools/op-deployer/overview),
which encodes the intent-file workflow your testnet run used. Before you
apply, review the fault-proof entries your intent controls, catalogued in the
[rollup deployment configuration reference](/chain-operators/reference/rollup-deployment-configuration):
the respected game type (`respectedGameType`, which a standard deployment
sets to the permissioned game, type `1`), the absolute prestate
(`faultGameAbsolutePrestate`), and the game depth and clock parameters.

The decision this step adds: keep the standard values. The dispute
parameters are consensus-critical to how games are played and resolved,
which is why overriding them requires setting an intent field named
`dangerouslyAllowCustomDisputeParameters`. Do not change them without a
dedicated security review.

Record the addresses `op-deployer` produces, in particular the
`DisputeGameFactory` proxy: the proposer, the challenger, and your
monitoring all take it as configuration.

## Step 3: Design the sequencer topology

A single sequencer is a single point of failure for the whole chain: when
it stops, no new unsafe blocks exist for anyone. The OP Stack's
high-availability answer is `op-conductor`. Read the
[OP Conductor explainer](/chain-operators/tools/op-conductor) and take away:

* Each sequencer runs a conductor alongside it; the conductors form a Raft
  cluster, and the Raft leader is the one sequencer allowed to produce and
  gossip unsafe blocks.
* The three guarantees of the design: no unsafe reorgs, no unsafe-head
  stall during a network partition, and 100% uptime with no more than one
  node failure in the standard three-node setup.
* The design is not Byzantine fault tolerant: it assumes every node in the
  cluster is honest and operated by you. It protects against crashes and
  partitions, not against a malicious cluster member.

Then read the
[network design example](/chain-operators/guides/management/network-architecture)
and take away where sequencers sit relative to transaction-ingress nodes,
archive nodes, and public RPC, and that the conductor RPC can act as a
leader-aware proxy for services that must always talk to the active
sequencer.

| If ...                                                           | Choose ...                                            | Because ...                                                                                                                           |
| ---------------------------------------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| This launch is a testnet or downtime is acceptable               | A single sequencer, no conductor                      | You avoid running three sequencer stacks; conductor can be added to a live network later without downtime via the setup guide.        |
| Production launch with an uptime commitment                      | A three-node conductor cluster across failure domains | It survives any single node failure with no unsafe reorg; Raft needs a quorum, so two of the three nodes must stay reachable.         |
| You need protection against a compromised or malicious sequencer | More than conductor                                   | Conductor is explicitly not BFT; it manages availability among nodes you trust, and cannot defend against a dishonest cluster member. |

## Step 4: Bootstrap the conductor cluster

Stand up the three sequencers (each an `op-node` + `op-reth` pair with a
conductor beside it), then form the cluster. The
[op-conductor setup guide](/chain-operators/tools/op-conductor/setup) is the
canonical stop; follow it end to end and take away:

* The bootstrap shape: exactly one conductor starts with
  `OP_CONDUCTOR_RAFT_BOOTSTRAP=true` (and `OP_CONDUCTOR_PAUSED=true`), the
  others join via `conductor_addServerAsVoter` against the leader, and the
  bootstrap flag must be removed after the cluster exists so a redeploy
  cannot re-bootstrap it.
* The op-node side: every sequencer's op-node runs with
  `OP_NODE_CONDUCTOR_ENABLED=true`, which is what commits unsafe blocks to
  the Raft log, and the `OP_NODE_RPC_ADMIN_STATE` flag cannot be used with
  conductor.
* The health-check settings that decide when leadership moves:
  `OP_CONDUCTOR_HEALTHCHECK_MIN_PEER_COUNT` sized to your internal peer
  count, and `OP_CONDUCTOR_HEALTHCHECK_UNSAFE_INTERVAL` at a small
  multiple of your block time so a brief hiccup does not trigger failover.
* The pause/resume/transfer-leadership RPCs, which are also your manual
  override during incidents.

The setup guide is written for adding conductor to an already-running
network with a blue/green deployment; for a chain that is not live yet, the
same sequence applies without the zero-downtime choreography, and the
[op-conductor runbook](https://github.com/ethereum-optimism/optimism/blob/develop/op-conductor/RUNBOOK.md)
covers bootstrapping a cluster from scratch (in-repo document on `develop`,
as of 2026-07-21).

## Step 5: Wire the L1-facing services to the leader

The batcher and proposer must follow whichever sequencer is currently
leading, not a fixed node:

* **op-batcher**: point it at the conductor RPC, whose leader-aware proxy
  mode (`OP_CONDUCTOR_RPC_ENABLE_PROXY`, on by default) serves the
  necessary op-node and execution RPCs only while its node leads, per the
  [network design example](/chain-operators/guides/management/network-architecture#sequencers).
  Then configure it per the
  [batcher configuration guide](/chain-operators/guides/configuration/batcher);
  once the chain is live, cost tuning has
  [its own guide](/use-cases/tune-batcher-costs).
* **op-proposer**: configure it per the
  [proposer configuration guide](/chain-operators/guides/configuration/proposer),
  with `--game-factory-address` from Step 2 and `--game-type` set to your
  chain's respected game type, which is `1` (permissioned) for a standard
  launch. Only proposals made as the respected game type can be used to
  prove withdrawals, and on a permissioned chain the proposer must sign
  with the designated proposer address from your intent.

## Step 6: Stand up the defense

Even while the chain is permissioned, run the full defense stack: the
challenger and monitoring you battle-test now are a precondition for the
permissionless switch. Follow the
[run a fault-proof challenger guide](/use-cases/run-a-fault-proof-challenger),
which covers bond budgeting, prestate selection, the four infrastructure
endpoints, and monitoring with `op-dispute-mon`, and take away one
launch-specific point: in the permissioned game, only addresses holding the
proposer or challenger role can participate in disputes, so the challenger
must sign with the challenger role address from your Step 2 intent. For the
full flag catalogue behind that setup, the
[challenger configuration reference](/chain-operators/reference/challenger-configuration)
is generated from the op-challenger flag definitions at each finalized
release.

### Give every service a consistent view of L1

Everything in this guide consumes L1: each sequencer's op-node derives the
chain from an L1 RPC and an L1 beacon endpoint, and the batcher, proposer,
and challenger read and transact against L1. Redundant L1 nodes are the
right instinct for a high-availability chain; a generic load balancer in
front of them is not:

* Two L1 nodes are never at exactly the same head at the same moment. A
  service whose consecutive requests round-robin between them watches
  blocks appear, disappear, and reappear, which reads as L1 reorgs that
  never happened.
* The challenger is the least tolerant consumer, and one behind a normal
  load balancer can malfunction. It reacts to new L1 heads from a
  subscription on its L1 RPC, then reads the dispute game contracts with
  calls pinned to that head's block hash, so a follow-up request served
  by a node that has not imported the block yet fails. Its progress
  gauge (`op_challenger_highest_acted_l1_block`) reports the lowest L1
  block processed across all games, so a single game stalled on an
  inconsistent endpoint flat-lines the challenger's measured progress.
  Give it one trusted endpoint that fails over deliberately, not per
  request, per the
  [challenger guide's endpoint requirements](/use-cases/run-a-fault-proof-challenger#step-4-provision-the-four-endpoints).
* Where you do want balancing, make it consensus-aware. For beacon
  endpoints, a beacon-chain-aware proxy such as
  [dugtrio](https://github.com/ethpandaops/dugtrio) monitors its
  upstream nodes to route around forked-off or unsynced clients and
  keeps subsequent requests on the same endpoint where possible, which
  is exactly the property a generic round-robin balancer lacks. As of
  2026-07-22.

## Step 7: Schedule the switch to permissionless proofs

Permissionless fault proofs are the security upgrade the system exists for:
anyone can propose and anyone can challenge, so users no longer depend on
your proposer being honest and available. Read the
[permissionless migration tutorial](/chain-operators/tutorials/migrating-permissionless)
and take away the four phases: configure the dispute components, deploy the
permissionless game contracts through OPCM's `addGameType` (detailed in the
[dispute games tutorial](/chain-operators/tutorials/dispute-games)), test the
off-chain agents against the new game type, and only then switch the
respected game type. Since the Karst upgrade the permissionless game to
enable is `cannon-kona` (kona-client run inside the Cannon VM); the legacy
op-program path has reached
[end of support](/notices/archive/op-geth-deprecation).

| If ...                                                         | Choose ...              | Because ...                                                                                                                                |
| -------------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Launch day                                                     | Stay permissioned       | The dispute stack has never seen your production traffic; the Guardian and your monitoring cover the gap while you build evidence.         |
| Challenger and dispute-mon have run cleanly against live games | Schedule the migration  | The migration's testing phase assumes working agents; proving them first makes the respected-game-type switch a config change, not a leap. |
| Your contracts predate op-contracts v5.0.0                     | Upgrade contracts first | The migration tutorial's minimum supported contracts version is v5.0.0.                                                                    |

## Step 8: Verify the launch

Confirm each property you paid for, before users depend on it:

* **Cluster health**: query `conductor_leader` (or use `op-conductor-ops`)
  and confirm exactly one leader, with the other two conductors as
  followers and their sequencers stopped.
* **Failover**: run a leadership-transfer drill with
  `conductor_transferLeaderToServer` and confirm the unsafe head keeps
  advancing without a gap or reorg; then repeat by stopping the leading
  sequencer outright and watching leadership move on its own.
* **Posting and proposing**: batcher transactions land on L1 at the
  expected cadence and the safe head advances; the `DisputeGameFactory`
  shows new games from your proposer address at the proposal interval.
* **Defense**: `op-dispute-mon` tracks the games your proposer creates,
  and the challenger's logs show it monitoring them (the
  [challenger guide's verification step](/use-cases/run-a-fault-proof-challenger#step-7-verify-the-challenger-is-defending)
  has the full checklist).
* **The user path**: complete one withdrawal end to end (prove against a
  proposal, wait out the delays, finalize) before real users need to.

## Next steps

* [op-conductor runbook](https://github.com/ethereum-optimism/optimism/blob/develop/op-conductor/RUNBOOK.md):
  disaster-recovery procedures and manual overrides for every failure mode
  the cluster can enter. In-repo document on `develop`, as of 2026-07-21.
* [op-conductor configuration and RPC reference](/chain-operators/tools/op-conductor/reference):
  the flag and RPC catalogue behind Steps 4 and 8.
* [op-conductor-ops](https://github.com/ethereum-optimism/infra/tree/main/op-conductor-ops):
  the operational CLI for inspecting and driving a conductor cluster, and
  op-conductor-mon for metrics, in the infra repository. As of 2026-07-21.
* [Fault dispute game specification](https://specs.optimism.io/fault-proof/stage-one/fault-dispute-game.html?utm_source=op-docs\&utm_medium=docs):
  the normative game semantics, for when you need to reason about what
  your proposer and challenger are participating in.
* [Chain operator best practices](/chain-operators/guides/management/best-practices):
  the wider operational posture (release versions, incremental upgrade
  rollouts, sequencer isolation, runbooks) around the launch this guide
  covered.
* [Tune batcher costs](/use-cases/tune-batcher-costs): the cost loop to
  work through once the chain has real traffic.


# Run a fault-proof challenger
Source: https://docs.optimism.io/use-cases/run-a-fault-proof-challenger

Stand up an op-challenger that defends your OP Stack chain, from bond budgeting and prestate selection through infrastructure, configuration, and monitoring.

This guide takes an operator who wants an honest challenger defending an OP
Stack chain and walks the whole path in one pass: what the challenger does and
spends, the version and prestate choices that decide whether it can win games,
the four pieces of infrastructure it depends on, and how to confirm it is
actually defending the chain. It involves `op-challenger`, the Cannon VM with
a kona-client prestate, an `op-node` with SafeDB, an `op-reth` archive node,
and your chain's dispute game contracts on L1.

## Is this guide for you?

Use this guide if:

* Your chain runs the fault proof system: a `DisputeGameFactory` is deployed
  and proposals are settled by dispute games.
* You are responsible for the chain's defense (chain operator) or you are an
  independent participant willing to put funds at stake to help secure it.

If you are creating a new chain and setting up the challenger as one step of
that, follow the
[challenger step of the create L2 rollup tutorial](/chain-operators/tutorials/create-l2-rollup/op-challenger-setup)
inside that series instead. If you want to understand how dispute games work
before operating anything, start with the
[fault proofs explainer](/op-stack/fault-proofs/explainer). If you are
investigating one specific game rather than running a standing service, use
[monitoring tooling](/chain-operators/tools/chain-monitoring#dispute-mon).

If you want this role staffed without running it yourself, or with OP Labs
engineering supporting your team, see
[OP Enterprise](https://optimism.io/op-enterprise?utm_source=docs\&utm_medium=docs\&utm_campaign=op-enterprise);
this guide is the reference for what defending a chain involves either way.

## Before you start

You should already have:

* Your chain's contract addresses, in particular the `DisputeGameFactory`
  proxy address (automatic in Step 3 if your chain is in the
  superchain-registry).
* An L1 account you can fund with enough ETH to post bonds (sized in
  Step 2), and infrastructure to run several services with persistent
  storage.
* Your chain's `rollup.json` and L2 genesis file if the chain is not in the
  superchain-registry.

## Step 1: Understand the role you are staffing

The challenger is the honest actor in the dispute system: an autonomous agent
that monitors every game, defends valid proposals, challenges invalid ones,
and resolves games so bonds pay out. Read the
[op-challenger explainer](/op-stack/fault-proofs/challenger) and take away:

* The five responsibilities (monitor, defend, challenge, resolve, claim
  bonds), and that the challenger acts on whatever its trusted `op-node`
  reports, so the integrity of your rollup node is the integrity of your
  challenger.
* That the respected game type is `cannon-kona` (run with kona-host), and
  that the legacy `cannon` / op-program game type has reached
  [end of support](/notices/archive/op-geth-deprecation): op-program does not
  support the now-active Karst hardfork, so the kona variants are the only
  maintained option.

Then read the
[fault proofs security model](/op-stack/fault-proofs/fp-security) and take
away what happens when games go wrong anyway: the Guardian can blacklist a
bad game or change the respected game type, and bonds sit in `DelayedWETH`
with a delay so incorrect payouts can be recovered. Your challenger is the
first line of defense, not the only one.

## Step 2: Budget your bonds and fees

Every claim your challenger posts carries a bond, sent as transaction value,
and correct claims are refunded while incorrect ones pay the counter-claimer.
Read the [bond FAQs in the explainer](/op-stack/fault-proofs/challenger#faqs)
and take away:

* The sizing logic: honest actors combined must be able to outspend an
  attacker, so there is no fixed safe number. Playing a single game chain to
  maximum depth costs about 315.6 ETH per side, and a well-funded operator
  keeps significant funds available at short notice rather than pre-funding
  everything.
* The cash-flow shape: bonds from won games pay out only after a 7-day
  delay, so budget for capital being locked while games resolve.
* The backstop: attackers who try to outspend honest actors lose their
  bonds to Guardian intervention, which is the disincentive that keeps the
  realistic spend far below the worst case.

Decide now how much ETH the challenger's account holds and how quickly you
can top it up during an active dispute; that operational answer matters more
than the exact starting balance.

## Step 3: Pin your versions and prestate

The challenger refuses to interact with games whose absolute prestate it does
not have, and playing with the wrong prestate loses games, so version
selection is a correctness decision, not housekeeping. Check the
[op-challenger release history](/releases/op-challenger) for the latest
release, then read the
[version guidance in the configuration guide](/chain-operators/guides/configuration/op-challenger-config-guide#finding-the-current-stable-releases)
and take away which op-challenger, op-reth, and kona-client versions are
compatible with your chain's deployment.

Then choose your configuration path:

| If ...                                     | Choose ...                                                                 | Because ...                                                                                                                                    |
| ------------------------------------------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Your chain is in the superchain-registry   | The `--network` flag                                                       | The game factory address, rollup config, and L2 genesis load automatically from the registry, removing three chances to misconfigure.          |
| Your chain is custom (not in the registry) | Explicit `--game-factory-address`, rollup config, L2 genesis, and prestate | Nothing can be looked up for you; the prestate must be the one your contracts were deployed with, built via `just reproducible-prestate-kona`. |
| Your chain upgrades prestates over time    | `--cannon-kona-prestates-url` instead of a single prestate file            | The challenger can fetch the prestate matching each game, so it keeps playing across a network upgrade instead of ignoring new games.          |

For generating and verifying a prestate, follow the
[absolute prestate tutorial](/chain-operators/tutorials/absolute-prestate);
for custom chains, the
[kona-client custom prestate tutorial](/chain-operators/tutorials/kona-custom-prestate)
covers embedding your chain's configuration.

## Step 4: Provision the four endpoints

The challenger consumes four services, and each has a requirement beyond
"reachable RPC". Read the
[key configuration flags](/chain-operators/guides/configuration/op-challenger-config-guide#configuration-setup)
in the configuration guide and take away, per endpoint:

* **L1 RPC** (`--l1-eth-rpc`): a trusted node that can absorb heavy request
  volume. The challenger signs transactions worth real fees based on what
  this node tells it, so "trusted" is load-bearing.
* **L1 beacon** (`--l1-beacon`): serves the blobs batches were posted in.
  Decide the blob-archiver question now: if your chain proposes valid
  outputs regularly, the roughly 18-day blob retention window is enough; if
  proposals can stall longer than that, a blob archiver is required or the
  challenger can be pushed into an unwinnable position.
* **L2 archive node** (`--l2-eth-rpc`): an op-reth archive node with the
  debug API and the historical-proofs store enabled and seeded before first
  start, sized to cover the dispute window (28 days or more).
* **Rollup node** (`--rollup-rpc`): an op-node with SafeDB enabled
  (`--safedb.path`). Take away the warning about never restoring the SafeDB
  from a snapshot: a SafeDB that disagrees with L1 makes the challenger
  attack valid outputs, and the challenger cannot detect the condition.

## Step 5: Configure and start the challenger

With versions, prestate, and endpoints in hand, the configuration guide is
the canonical stop. Choose your deployment form:

| If ...                                                      | Choose ...        | Because ...                                                                                                               |
| ----------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------- |
| You want full control of binaries for production operations | Build from source | You control the exact release tag and can debug against it; the binary needs `--cannon-kona-server` pointed at kona-host. |
| You want the packaged path                                  | The Docker image  | The image embeds the kona server and Cannon executable, so the server flag and binaries ship pre-wired.                   |

Follow the matching tab of the
[challenger configuration guide](/chain-operators/guides/configuration/op-challenger-config-guide)
end to end. It covers the environment file, the startup script or compose
file, and the flag-by-flag explanations. Keep the guide's `--trace-type`
value, which includes the `cannon-kona` game type from Step 1, and use the
transaction signer posture you use for your other services (private key,
mnemonic, or op-signer).

## Step 6: Attach monitoring

A challenger that silently stops is worse than none, because you believe you
are defended. Read the
[dispute-mon section of chain monitoring](/chain-operators/tools/chain-monitoring#dispute-mon)
and take away that `op-dispute-mon` tracks the status of every game over the
last 28 days and is considered essential for production challenger
deployments. Alert on two conditions at minimum: games the monitor flags as
resolving against your chain, and the challenger's account balance falling
below your Step 2 top-up threshold.

## Step 7: Verify the challenger is defending

Give the challenger a few minutes against live games, then confirm each layer:

* **Startup health**: logs show successful connection to all four
  endpoints and the prestate loading without warnings; the challenger
  refuses to play games whose prestate it lacks, and says so in the logs.
* **Game visibility**: `op-challenger list-games` (against your L1 RPC and
  game factory) returns the chain's games; `list-claims` shows the claims
  of any in-progress game. These read-only subcommands use the same
  configuration as the running service, so they double as configuration
  checks.
* **Participation**: for a game created after your challenger started, the
  challenger either leaves a valid proposal alone or posts counter-claims
  to an invalid one. On a testnet you can exercise this deliberately with
  the `create-game` subcommand and an intentionally wrong root claim.
* **The economic loop**: after games your challenger won resolve and the
  7-day delay passes, `list-credits` shows bonds owed to your challenger's
  address being claimed.

## Next steps

* [op-challenger readme](https://github.com/ethereum-optimism/optimism/blob/develop/op-challenger/README.md):
  subcommand reference (create-game, move, resolve, run-trace) and devnet
  walkthroughs beyond configuration. In-repo document on `develop`, as of
  2026-07-18.
* [Challenger configuration reference](/chain-operators/reference/challenger-configuration):
  the rendered flag catalogue, generated from the op-challenger flag
  definitions at the release tag named on the page and regenerated when a
  new finalized release is published.
* [Honest challenger specification](https://specs.optimism.io/fault-proof/stage-one/honest-challenger-fdg.html?utm_source=op-docs\&utm_medium=docs):
  the normative algorithm your challenger implements, for when you need to
  reason about what a correct response is.
* [Bond incentives specification](https://specs.optimism.io/fault-proof/stage-one/bond-incentives.html?utm_source=op-docs\&utm_medium=docs):
  the required-bond formula behind Step 2's budget.
* [op-dispute-mon](https://github.com/ethereum-optimism/optimism/tree/develop/op-dispute-mon):
  the monitoring service from Step 6. In-repo document on `develop`, as of
  2026-07-18.


# Tune batcher costs
Source: https://docs.optimism.io/use-cases/tune-batcher-costs

Reduce what your OP Stack chain spends posting data to L1, and recover what you do spend, without breaking batch-submission safety limits.

This guide takes a chain operator whose largest onchain operating cost is L1 data
posting and walks the whole cost loop in one pass: what the batcher spends,
the settings that control that spend, and the fee parameters that recover it
from users. It involves the `op-batcher`, your chain's `SystemConfig` fee
parameters, and, for throttling, the sequencer's execution client.

## Is this guide for you?

Use this guide if:

* You operate an OP Stack chain: you control the `op-batcher` deployment
  and can reach the [SystemConfig owner](/op-stack/protocol/privileged-roles)
  when a parameter change needs it.
* Your goal is economic (L1 posting costs look too high, or user fees
  aren't covering them) rather than a batcher outage or sync problem.

If you are standing up a batcher for the first time, follow the
[batcher setup tutorial](/chain-operators/tutorials/create-l2-rollup/op-batcher-setup)
first. If you want to understand how fees work rather than change them, read
[Transaction fees](/op-stack/transactions/fees). If you are evaluating
alternative data availability layers, see the
[Alt-DA mode guide](/chain-operators/guides/features/alt-da-mode-guide).
This guide covers Ethereum DA (calldata and blobs) only.

## Before you start

You should already have:

* A running `op-batcher` posting batches for your chain, and the ability
  to change its flags or environment variables and restart it.
* Access to the batch submitter's L1 spend history (its address on an L1
  explorer) so you can measure the effect of changes.
* Batcher metrics scraped somewhere you can query; see
  [chain monitoring options](/chain-operators/tools/chain-monitoring).
* For Step 5, transaction access as the SystemConfig owner (fee scalars
  are set on L1).

## Step 1: Map where the fees go

Two fee flows matter, and they are tuned by different knobs: the fees
**you** pay L1 to post data (batcher settings), and the fees **users** pay
you (SystemConfig fee parameters). Read
[Transaction fees](/op-stack/transactions/fees) and take away:

* The three components of a user fee (execution gas fee, L1 data fee,
  operator fee), and that the [L1 data fee](/op-stack/transactions/fees#l1-data-fee)
  is the component that exists to recover your batcher spend.
* Which scalars price the L1 data fee (`basefeeScalar` and
  `blobBaseFeeScalar`); you will set them in Step 5.

Then skim [Transaction Fees 101](/chain-operators/guides/management/transaction-fees-101)
and take away which fee parameters are operator-adjustable and the example
scenarios that match your chain's traffic pattern.

## Step 2: Balance your sequencing-window budget

Cost tuning trades posting cost against batch-submission speed, and the
sequencing window puts a hard cap on that trade. The faster you submit
batches, the sooner your users' transactions get Ethereum finality
guarantees; the longer you accumulate before posting, the cheaper each
byte gets, up to the cap. Read the
[batcher policy section](/chain-operators/guides/configuration/batcher#batcher-policy)
of the batcher configuration guide and take away:

* Your chain's **sequencing window**, which is 3,600 L1 blocks (12 hours)
  on standard chains, and that batches must always land on L1 inside it.
  Breached sequencing windows result in a
  [12 hour reorg](/op-stack/protocol/outages#inclusion-rules).
* The standard requirement to target batch submission at **1,800 L1
  blocks (6 hours) or lower**, and why operators leave a congestion
  buffer below that.
* That a long submission interval stalls the
  [safe head](https://specs.optimism.io/glossary.html?utm_source=op-docs\&utm_medium=docs#safe-l2-head)
  for up to that interval, which delays exchanges and bridges that wait
  for Ethereum finality.

Every choice in Steps 3 and 4 must keep batch submission inside the
sequencing window. Decide now how long your chain's users can wait for
Ethereum finality; that number, not the 12-hour hard cap, is your real
budget.

## Step 3: Choose a data availability type

The batcher posts to Ethereum as calldata or as blobs, controlled by
`--data-availability-type` (`OP_BATCHER_DATA_AVAILABILITY_TYPE`); valid
values are `calldata` (the flag's default), `blobs`, and `auto`. A blob must
be bought whole, about 130 KB of usable capacity, whether or not you fill
it. In practice that rarely favors calldata: outside short demand spikes,
the blob base fee has sat at or near its floor since blobs launched, so even
a partly filled blob usually costs less than posting the same bytes as
calldata, and L1's Pectra upgrade (EIP-7623) raised calldata pricing for
data-heavy transactions on top of that.

| If ...                                                                | Choose ... | Because ...                                                                                                                                              |
| --------------------------------------------------------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| You want the sensible default (most chains, at any throughput)        | `blobs`    | The blob base fee spends most of its time at or near its floor, where blob bytes are far cheaper than calldata even when your blobs go out partly empty. |
| You want blob-fee spikes handled automatically                        | `auto`     | The batcher estimates the current cost per byte of both markets and picks the cheaper, staying on blobs while throttling is active.                      |
| A sustained blob-fee spike is underway and you prefer to pin the type | `calldata` | Calldata can win briefly when blob demand spikes; treat it as the exception and switch back (or move to `auto`) once the spike passes.                   |

To check which market is cheaper right now, compare the current blob base
fee with the L1 base fee on any gas tracker that shows both, or let `auto`
make the comparison per channel. To execute a switch, follow
[Post batch data as blobs](/chain-operators/guides/features/blobs), which covers
[switching to blobs](/chain-operators/guides/features/blobs#switch-to-using-blobs),
[switching back to calldata](/chain-operators/guides/features/blobs#switch-back-to-using-calldata),
and [auto mode](/chain-operators/guides/features/blobs#use-auto-da-mode-in-your-batcher);
take away that a DA-type switch also changes the correct scalar values, so
plan Step 5 in the same change window.

## Step 4: Size your channels

With the DA type fixed, the biggest cost levers are how long the batcher
accumulates data before posting and, on blobs, how many blobs it packs per
transaction:

* `--max-channel-duration` (`OP_BATCHER_MAX_CHANNEL_DURATION`), in L1
  blocks. The default is `0` (duration tracking disabled). Read the
  [channel duration recommendation](/chain-operators/guides/configuration/batcher#set-your--op_batcher_max_channel_duration)
  and take away the recommended 1,500-block (5-hour) ceiling, the reasons
  not to exceed it, and that a full channel is posted early regardless of
  this setting.
* `--target-num-frames` (`OP_BATCHER_TARGET_NUM_FRAMES`), the number of
  frames (and so blobs per blob transaction) to target. The default is
  `1`. Read the
  [multi-blob recommendation](/chain-operators/guides/configuration/batcher#configure-your-batcher-to-use-multiple-blobs)
  and take away the companion transaction-manager settings a multi-blob
  configuration needs and the blob-congestion caveat.
* `--batch-type=1` (`OP_BATCHER_BATCH_TYPE`) enables span batches, which
  cut batch overhead; the default is `0` (singular). Follow
  [Enable span batches](/chain-operators/guides/features/enable-span-batches),
  which includes confirming the Delta upgrade is active first.

The connective logic:

| If ...                                                      | Choose ...                                                                         | Because ...                                                                                 |
| ----------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| Low throughput and users tolerate hours of safe-head delay  | Long channel duration (up to 1,500 blocks), single blob                            | Accumulating longer is the only way a quiet chain fills what it pays for.                   |
| Low throughput but bridges/exchanges need fresh safe blocks | Shorter channel duration, accept higher per-byte cost                              | The safe head stalls for up to the channel duration; latency is the price of cheap posting. |
| Medium/high throughput                                      | `blobs` with `--target-num-frames` sized so blobs fill before the duration elapses | You stop paying for empty blob space, and fewer L1 transactions carry the same data.        |
| Any throughput                                              | Span batches (`--batch-type=1`)                                                    | Less overhead per batch at no safety cost on Delta-activated chains.                        |

To get a concrete blob count, estimate the compressed batch data your
chain produces per channel duration and divide by blob capacity (\~130 KB);
Step 7's utilization metrics will confirm or correct the estimate.

## Step 5: Recover the spend with fee scalars

Posting cheaply is half the loop; the L1 data fee your users pay must track
what you now actually spend. Follow the
[L1 fee section of Transaction Fees 101](/chain-operators/guides/management/transaction-fees-101#tune-the-l1-fee)
to read and set `basefeeScalar` and `blobBaseFeeScalar` on your
SystemConfig, and take away the direction of each adjustment. For the
formula the scalars feed and the values OP Mainnet runs, see the
[fee parameters reference](/chain-operators/reference/fee-parameters#fee-formulas).
Size the scalars against your measured batcher spend so they recover it
plus your target margin.

If you switched DA type in Step 3, set the new scalars in the same
maintenance window: blob-appropriate scalars under calldata (or the reverse)
misprice every user transaction until corrected.

## Step 6: Decide your throttling posture

Throttling is the batcher's defense against traffic spikes outrunning your
DA budget: when its backlog of un-posted data grows past a threshold, it
instructs the sequencer's execution client (via the `miner_setMaxDASize`
RPC) to limit DA-heavy transactions and blocks. It is **on by default**, so
this step is about checking the defaults fit your cost posture rather than
turning something on. Read the
[batcher sequencer throttling section](/chain-operators/guides/configuration/batcher#batcher-sequencer-throttling)
and take away:

* The requirement that the sequencer's execution client exposes the
  `miner` RPC namespace, and the follow-the-sequencer caveat for
  multi-node setups.
* The default backlog thresholds at which throttling engages and reaches
  maximum intensity (`--throttle.unsafe-da-bytes-lower/upper-threshold`),
  and that the default controller is `quadratic`
  (`--throttle.controller-type`; the options are `step`, `linear`,
  `quadratic`, and `pid`).

The decision this guide adds: leave throttling on unless, during traffic
spikes, you accept unbounded backlog growth and the cost exposure that
comes with posting that backlog at whatever L1 happens to charge. To
accept that trade anyway, disable throttling by setting
`--throttle.unsafe-da-bytes-lower-threshold=0`. For controller selection
and tuning depth, use the throttling deep dive in the next steps.

## Step 7: Verify the outcome

Give a change at least a few full channel cycles, then check both sides of
the loop. The batcher exports Prometheus metrics under the
`op_batcher_<procname>` namespace (`op_batcher_default_*` unless you set a
custom process name):

* **Blob utilization** (blobs only): the `blob_used_bytes` histogram
  should sit near blob capacity (\~130 KB). Persistently part-empty blobs
  mean your channel duration or frame count is oversized for your
  throughput; revisit Step 4.
* **Posting cadence**: batcher transactions from your batch submitter
  address should appear on L1 at roughly the interval you chose, and
  never approach the sequencing-window deadline from Step 2.
* **Throttling at rest**: `throttle_intensity` should be `0` and
  `unsafe_da_bytes` below the lower threshold in normal operation. If
  throttling engages routinely, your chain's steady-state throughput
  exceeds your posting budget; revisit Steps 3 and 4 before touching
  Step 6's thresholds.
* **The economic bottom line**: over a representative window, compare the
  batch submitter's L1 spend against L1-fee revenue arriving in your
  [fee vaults](/chain-operators/guides/management/fee-vaults). A healthy
  result is revenue at or above spend by your target margin; if not,
  revisit Step 5.

## Next steps

* [Batcher configuration reference](/chain-operators/reference/batcher-configuration):
  the full flag and environment-variable catalogue. Hand-pinned to
  `op-batcher/v1.10.0` as of 2026-07-16; confirm values against
  `op-batcher --help` for the release you run.
* [op-batcher throttling deep dive](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/throttling.md):
  the only in-depth documentation of the four throttling controllers,
  their runtime-management RPCs, and the experimental PID controller's
  tuning profiles. In-repo document on `develop`, as of 2026-07-16.
* [op-batcher readme](https://github.com/ethereum-optimism/optimism/blob/develop/op-batcher/readme.md):
  batcher architecture and operational detail beyond configuration.
  In-repo document on `develop`, as of 2026-07-16.
* [Frame format in the derivation spec](https://specs.optimism.io/protocol/derivation.html?utm_source=op-docs\&utm_medium=docs#frame-format):
  the normative definition of channels and frames, for when you need to
  reason about what a channel actually contains.