diff --git a/pages/operators/chain-operators/tutorials.mdx b/pages/operators/chain-operators/tutorials.mdx index 2e31df92a..e18dc82c9 100644 --- a/pages/operators/chain-operators/tutorials.mdx +++ b/pages/operators/chain-operators/tutorials.mdx @@ -36,12 +36,14 @@ This section provides information on adding attributes to the derivation functio - - + + + + diff --git a/pages/operators/chain-operators/tutorials/_meta.json b/pages/operators/chain-operators/tutorials/_meta.json index 807ecbed1..9168131fe 100644 --- a/pages/operators/chain-operators/tutorials/_meta.json +++ b/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" } \ No newline at end of file diff --git a/pages/operators/chain-operators/tutorials/absolute-prestate.mdx b/pages/operators/chain-operators/tutorials/absolute-prestate.mdx new file mode 100644 index 000000000..248301f5d --- /dev/null +++ b/pages/operators/chain-operators/tutorials/absolute-prestate.mdx @@ -0,0 +1,250 @@ +--- +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 absolute prestate 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 + + + 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`. + + +## Generating the absolute prestate + + + ### 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. + + +## 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: + + + +### 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: + +* `-rollup.json` +* `-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) + + + +## Deploying and configuring with the absolute prestate + +After generating the absolute prestate and preimage files, you'll need to: + + + ### 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 + docker run -d --name op-challenger \ + -e OP_CHALLENGER_TRACE_TYPE=permissioned,cannon \ + -e OP_CHALLENGER_PRESTATES_URL= \ + -e OP_CHALLENGER_L1_ETH_RPC= \ + -e OP_CHALLENGER_GAME_FACTORY_ADDRESS= \ + -e OP_CHALLENGER_PRIVATE_KEY= \ + -e OP_CHALLENGER_NETWORK= \ + -e OP_CHALLENGER_CANNON_ROLLUP_CONFIG= \ + -e OP_CHALLENGER_CANNON_L2_GENESIS= \ + -v /path/to/local/prestates:/prestates \ + us-docker.pkg.dev/oplabs-tools-artifacts/images/op-challenger:latest #use the latest version + ``` + + + Replace `` 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. + + + + +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. + + +## 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)