Generating absolute prestate and preimage files for permissionless proofs

pages/operators/chain-operators/tutorials.mdx

@@ -36,12 +36,14 @@ This section provides information on adding attributes to the derivation functio
 
   <Card title="Running a Local Development Environment" href="/operators/chain-operators/tutorials/chain-dev-net" />
 
-  <Card title="Deploying new dispute games with OPCM" href="/operators/chain-operators/tutorials/dispute-games" />
-
   <Card title="Integrating a new da layer with alt Da" href="/operators/chain-operators/tutorials/integrating-da-layer" />
 
   <Card title="Migrating to permissionless fault proofs on OP Stack" href="/operators/chain-operators/tutorials/migrating-permissionless" />
 
+  <Card title="Deploying new dispute games with OPCM" href="/operators/chain-operators/tutorials/dispute-games" />
+
+  <Card title="Generating absolute prestate and preimage files" href="/operators/chain-operators/tutorials/absolute-prestate" />
+
   <Card title="Modifying predeployed contracts" href="/operators/chain-operators/tutorials/modifying-predeploys" />
 
   <Card title="Using viem" href="/app-developers/get-started" />

pages/operators/chain-operators/tutorials/_meta.json

@@ -5,5 +5,7 @@
     "modifying-predeploys": "Modifying predeployed contracts",
     "integrating-da-layer": "Integrating a new DA layer",
     "migrating-permissionless": "Migrating to permissionless fault proofs on OP Stack",
+    "dispute-games":"Deploying new dispute games with OPCM",
+    "absolute-prestate":"Generating absolute prestate and preimage files",
     "chain-dev-net": "Running a local network environment"
 }

pages/operators/chain-operators/tutorials/absolute-prestate.mdx

@@ -0,0 +1,249 @@
+---
+title: Generating absolute prestate and preimage files
+description: A high-level guide on how to generate the absolute prestate and preimage necessary for running cannon/permissionless proofs.
+lang: en-US
+content_type: tutorial
+topic: generating absolute prestate files
+personas:
+-   chain-operator
+categories:
+-   fault proofs
+-   cannon
+-   permissionless proofs
+-   proof system
+is_imported_content: 'false'
+---
+
+import { Callout, Steps } from 'nextra/components'
+
+# 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
+*   Have sufficient disk space and memory
+
+## Using the latest AP and multi-threaded Cannon
+
+As of the latest releases, OP Stack chains should utilize the `64-bit` MIPS multi-threaded version of Cannon. 
+This upgrade offers several advantages:
+
+*   Improved performance through parallelized execution
+*   Enhanced fault proof VM capabilities
+*   Support for the latest network upgrades
+
+<Callout type="info">
+  Beginning with [Upgrade 14](/notices/upgrade-14), all chains should use the `64-bit` multi-threaded version of Cannon. 
+  The absolute prestate files for this version typically have the format `prestate-mt64.bin.gz`.
+</Callout>
+
+## Generating the absolute prestate
+
+<Steps>
+  ### 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
+  git clone https://github.com/ethereum-optimism/optimism.git
+  cd optimism
+  git checkout op-program/v1.6.1-rc.1  # Use the latest tagged version
+  git submodule update --init --recursive # Initialize submodules
+
+```
+
+### Build the op-program
+
+Build the op-program binary:
+
+```bash
+make op-program
+```
+
+### Generate the absolute prestate
+
+Generate the prestate by running the op-program binary directly:
+
+```bash
+cd op-program
+make reproducible-prestate
+cd ..
+```
+
+The output should look like this:
+
+```bash
+
+-------------------- Production Prestates --------------------
+
+Cannon64 Absolute prestate hash: 
+0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8
+
+-------------------- Experimental Prestates --------------------
+
+CannonInterop Absolute prestate hash: 
+0x03fc3b4d091527d53f1ff369ea8ed65e5e17cc7fc98ebf75380238151cdc949c
+
+Cannon64Next Absolute prestate hash: 
+0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8
+
+```
+
+  The output should display three prestate hashes:
+
+  *   `Cannon64`: The current production absolute prestate hash for the 64-bit version of Cannon
+  *   `CannonInterop`: The absolute prestate hash used for interoperability
+  *   `Cannon64Next`: The next state version for Cannon with in-progress features (like Go 1.24 support)
+
+  For permissionless fault proofs, you'll primarily use the Cannon64 absolute prestate hash.
+
+  ### Prepare the preimage file
+
+  After generating the prestate, find the preimage file.
+  You should see a file named `prestate-mt64.bin.gz` or similar (the exact name might vary based on the version).
+  Rename this file to include the prestate hash:
+  The preimage file is located at `op-program/bin/prestate-mt64.bin.gz`. Rename it to match the prestate hash:
+
+  ```bash
+  cd op-program/bin
+  mv prestate-mt64.bin.gz 0x[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.
+</Steps>
+
+## 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 all chains in the Superchain registry.
+For chains listed in the Superchain registry, you should use the official prestate hashes rather than generating your own.
+
+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).
+
+## Handling unannounced chain configurations
+
+If your chain is not included in the Superchain registry, you'll need to generate a custom prestate with your specific chain configuration. This applies to:
+
+*   New chains
+*   Chains with custom configurations
+
+For these cases, follow these additional steps:
+
+<Steps>
+
+### Create a directory for your custom chain configuration
+```bash
+mkdir -p op-program/chainconfig/configs
+```
+
+### Copy your chain configuration files to this directory
+
+First, you need to obtain your chain's configuration files. These are typically generated when you [deploy your L2 chain](/operators/chain-operators/deploy/smart-contracts) with op-deployer:
+
+*   ***rollup.json**: The rollup configuration file
+*   **genesis.json**: The L2 genesis file 
+
+Name them according to the required format:
+
+```bash
+# Replace 67865 with your actual chain ID
+cp /path/to/rollup.json op-program/chainconfig/configs/67865-rollup.json
+cp /path/to/genesis.json op-program/chainconfig/configs/67865-genesis-l2.json
+```
+Note: The naming format is critical - the files must be named as:
+
+*   `<L2-chain-id>-rollup.json`
+*   `<L2-chain-id>-genesis-l2.json`
+
+These files are outputs from your L2 chain deployment process using op-deployer.
+
+### Generate the prestate
+
+From the root of the monorepo, run:
+
+```bash
+make reproducible-prestate
+```
+Alternatively, you can also specify the paths directly:
+
+```bash
+make reproducible-prestate ROLLUP_CONFIG=/path/to/67865-rollup.json L2_GENESIS=/path/to/67865-genesis-l2.json
+```
+
+This should generate output containing three prestate hashes:
+
+```bash
+-------------------- Production Prestates --------------------
+
+Cannon64 Absolute prestate hash: 
+0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8
+
+-------------------- Experimental Prestates --------------------
+
+CannonInterop Absolute prestate hash: 
+0x03fc3b4d091527d53f1ff369ea8ed65e5e17cc7fc98ebf75380238151cdc949c
+
+Cannon64Next Absolute prestate hash: 
+0x03eb07101fbdeaf3f04d9fb76526362c1eea2824e4c6e970bdb19675b72e4fc8
+
+```
+
+For current production use, you should use the `Cannon64` Absolute prestate hash.
+
+### Locate and prepare the preimage File
+Follow this [step](/operators/chain-operators/tutorials/absolute-prestate#prepare-the-preimage-file)
+
+</Steps>
+
+## Deploying and configuring with the absolute prestate
+
+After generating the absolute prestate and preimage files, you'll need to:
+
+<Steps>
+  ### Upload preimage file
+
+  Upload the preimage file to a location accessible by your op-challenger instances
+
+  ### Configure op-challenger
+
+  Configure the op-challenger to use this prestate:
+
+  ```bash
+  op-challenger \
+    --trace-type permissioned,cannon \
+    --prestates-url <URL_TO_PRESTATES_DIRECTORY> \
+    --l1-eth-rpc <YOUR_L1_RPC_URL> \
+    --rollup-rpc <YOUR_ROLLUP_RPC_URL> \
+    --game-factory-address <YOUR_DISPUTE_GAME_FACTORY> \
+    --cannon-rollup-config /path/to/your/<chain-id>-rollup.json \
+    --cannon-l2-genesis /path/to/your/<chain-id>-genesis-l2.json \
+    --network <YOUR_NETWORK_NAME> \
+    --datadir <YOUR_DATA_DIR>
+  ```
+
+
+  Replace `<URL_TO_PRESTATES_DIRECTORY>` with the URL where you've stored your prestate files.
+  The `--prestates-url` should point to the directory where you've uploaded the renamed prestate file from step 3.
+
+</Steps>
+
+<Callout type="info">
+Ensure you're using the latest op-challenger version, see the [release page](https://github.com/ethereum-optimism/optimism/release)
+The dispute game factory address must be manually specified via the `--game-factory-address` option.
+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 in the same format as the op-supervisor's configs. You can extract this from your existing op-supervisor setup.
+</Callout>
+
+## Next Steps
+
+*   [Deploying new dispute games with OPCM](/operators/chain-operators/tutorials/dispute-games)
+*   [Migrating to permissionless fault proofs](/operators/chain-operators/tutorials/migrating-permissionless)
+*   [Fault proofs explainer](/stack/fault-proofs/explainer)