From a49a0a27864501dea18cbd41769622d83a0829bb Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Tue, 9 Dec 2025 15:52:38 +0000 Subject: [PATCH 1/7] added Kona proofs to fp components --- op-stack/fault-proofs/fp-components.mdx | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/op-stack/fault-proofs/fp-components.mdx b/op-stack/fault-proofs/fp-components.mdx index 1f2e8b999..89a3b6596 100644 --- a/op-stack/fault-proofs/fp-components.mdx +++ b/op-stack/fault-proofs/fp-components.mdx @@ -29,8 +29,10 @@ The OP Stack's unique, modular design allows the decoupling of the FPP and FPVM, ## Fault proof program -The default for this system component is `op-program`, which implements 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 a combination of `op-node` and `op-geth`, so it has 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 op-geth code. +The Fault Proof (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 exection client code. +The default for this system component is `op-program`, a combination of `op-geth` and `op-node`, both written in Go. For the Rust stack there is `kona-client` which is a combination of `kona-node` and `op-reth`. +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. @@ -39,16 +41,16 @@ All data is retrieved via the [Preimage Oracle API](https://specs.optimism.io/ex ## Fault proof virtual machine The Fault Proof Virtual Machine (FPVM) is one of the modules in the OP Stack's fault proof system. -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://github.com/ethereum-optimism/optimism/blob/546fb2c7a5796b7fe50b0b7edc7666d3bd281d6f/specs/cannon-fault-proof-vm.md). - -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. - 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://github.com/ethereum-optimism/optimism/blob/546fb2c7a5796b7fe50b0b7edc7666d3bd281d6f/specs/cannon-fault-proof-vm.md). + +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 From 1dca930cd109d3e53905e81e2faa3461e4074797 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Tue, 16 Dec 2025 16:47:11 +0000 Subject: [PATCH 2/7] Update challenger.mdx --- op-stack/fault-proofs/challenger.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/op-stack/fault-proofs/challenger.mdx b/op-stack/fault-proofs/challenger.mdx index 13597f30e..a667955ac 100644 --- a/op-stack/fault-proofs/challenger.mdx +++ b/op-stack/fault-proofs/challenger.mdx @@ -29,7 +29,7 @@ graph TD; ``` - The `cannon` and `op-program` executables are run in the `op-challenger` docker container as sub-processes when required to generate game trace data. + The `cannon`,`op-program`, `op-program host`, `kona-client`, and `kona-host` executables are run in the `op-challenger` docker container as sub-processes when required to generate game trace data. ## Fault detection responses @@ -78,7 +78,6 @@ The `FaultDisputeGame` does not put a time cap on resolution - because of the li ## Next steps -* Ready to get started? Read our guide on how to [configure `op-challenger` on your OP Stack chain](/operators/chain-operators/deploy/op-challenger). * 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 From 74813788249c962353cc65ae2e85893286f00f0e Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Wed, 7 Jan 2026 16:07:53 +0000 Subject: [PATCH 3/7] Added switch to kona proof guide --- .../features/switching-to-kona-proofs.mdx | 219 ++++++++++++++++++ docs.json | 3 +- 2 files changed, 221 insertions(+), 1 deletion(-) create mode 100644 chain-operators/guides/features/switching-to-kona-proofs.mdx diff --git a/chain-operators/guides/features/switching-to-kona-proofs.mdx b/chain-operators/guides/features/switching-to-kona-proofs.mdx new file mode 100644 index 000000000..0c63012d0 --- /dev/null +++ b/chain-operators/guides/features/switching-to-kona-proofs.mdx @@ -0,0 +1,219 @@ +--- +title: Switch to Kona Proofs +description: Learn how to switch your OP Stack chain to use Kona-based fault proofs as the respected game type. +--- + +## 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`. This runs alongside the existing `op-program` (a combination of `op-node` and `op-geth`). Both programs: + +- Use Cannon as the FPVM, and +- Use the same dispute game implementation (`FaultDisputeGame.sol`). + +After the cannon+kona upgrade is deployed, both game types are available: + +- `CANNON` (0) — op-program +- `CANNON_KONA` (8) — kona-client + +By default, the respected game type remains `CANNON` (0), meaning only those games are used for withdrawals. This guide explains how to switch your chain so that Kona proofs (`CANNON_KONA`, 8) become the respected game type. + + + 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. + + +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 + + + + Before changing the respected game type, verify that your chain has been upgraded to support both `CANNON` and `CANNON_KONA` games. + + + The required upgrade is performed via `OPCM.upgrade` with an `OpChainConfig` that sets both `cannonPrestate` and `cannonKonaPrestate`. + + + 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" + # CANNON (0) implementation + cast call "gameImpl(uint8)" 0 + + # CANNON_KONA (8) implementation + cast call "gameImpl(uint8)" 8 + ``` + + Both calls should return non-zero addresses. + + + + Your challengers must be able to play both cannon and kona games before you change the respected game type. + + + These settings should already be in place from the cannon+kona upgrade preparation. This step is about double-checking before you switch. + + + 1. **Trace types** + + If you explicitly configure trace types, ensure that `cannon-kona` is included. A typical setting is: + + ```bash + 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 + --prestates-url= + ``` + + - If they are at different locations, use: + + ```bash + --cannon-prestates-url= + --cannon-kona-prestates-url= + ``` + + For operational simplicity, a single location for all prestates is recommended. + + 3. **Kona host binary** + + For operators not using the standard OP Labs `op-challenger` Docker images, you must also provide: + + ```bash + --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. + + + + 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. + + + 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. + + + 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" + CALLDATA=$(cast calldata "setRespectedGameType(uint32)" 8) + ``` + + 2. **Send the transaction** + + Send the transaction from the Guardian to the `AnchorStateRegistry`: + + ```bash title="cast" + cast send \ + --rpc-url \ + --private-key \ + \ + "$CALLDATA" + ``` + + 3. **Verify the new respected game type** + + After the transaction confirms, verify that the respected game type is now `8`: + + ```bash title="cast" + cast call \ + --rpc-url \ + \ + "respectedGameType()(uint32)" + ``` + + The returned value should be `8`, indicating that `CANNON_KONA` is now the respected game type. + + + + 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 + # 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. + + + + 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. + + + +--- + +## 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) \ No newline at end of file diff --git a/docs.json b/docs.json index a43257a7b..f42189d20 100644 --- a/docs.json +++ b/docs.json @@ -1812,7 +1812,8 @@ "chain-operators/guides/features/flashblocks-guide", "chain-operators/guides/features/alt-da-mode-guide", "chain-operators/guides/features/blobs", - "chain-operators/guides/features/snap-sync" + "chain-operators/guides/features/snap-sync", + "chain-operators/guides/features/switching-to-kona-proofs" ] }, { From cec5837dbd480283b8c68c16a26c42a3a428dfa9 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Thu, 8 Jan 2026 14:35:16 +0000 Subject: [PATCH 4/7] Update chain-operators/guides/features/switching-to-kona-proofs.mdx Co-authored-by: Inphi --- chain-operators/guides/features/switching-to-kona-proofs.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/chain-operators/guides/features/switching-to-kona-proofs.mdx b/chain-operators/guides/features/switching-to-kona-proofs.mdx index 0c63012d0..6644a0a41 100644 --- a/chain-operators/guides/features/switching-to-kona-proofs.mdx +++ b/chain-operators/guides/features/switching-to-kona-proofs.mdx @@ -15,7 +15,7 @@ description: Learn how to switch your OP Stack chain to use Kona-based fault pro Kona proofs use the `kona-client` fault proof program, which is a combination of `kona-node` and `op-reth`. This runs alongside the existing `op-program` (a combination of `op-node` and `op-geth`). Both programs: - Use Cannon as the FPVM, and -- Use the same dispute game implementation (`FaultDisputeGame.sol`). +- Are used by the same dispute game implementation (`FaultDisputeGame.sol`). After the cannon+kona upgrade is deployed, both game types are available: From 5167c1605ea2e9aed5e6db09d3b645e289fff9cb Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Thu, 8 Jan 2026 14:37:06 +0000 Subject: [PATCH 5/7] Update op-stack/fault-proofs/challenger.mdx Co-authored-by: Inphi --- op-stack/fault-proofs/challenger.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/op-stack/fault-proofs/challenger.mdx b/op-stack/fault-proofs/challenger.mdx index a667955ac..1f4af7d0e 100644 --- a/op-stack/fault-proofs/challenger.mdx +++ b/op-stack/fault-proofs/challenger.mdx @@ -29,7 +29,7 @@ graph TD; ``` - The `cannon`,`op-program`, `op-program host`, `kona-client`, and `kona-host` executables are run in the `op-challenger` docker container as sub-processes when required to generate game trace data. + The `cannon`, `op-program host`, and `kona-host` executables are run in the `op-challenger` docker container as sub-processes when required to generate game trace data. ## Fault detection responses From 42bd47c934124252cfad5a7d2a8a34ba80f425aa Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Thu, 8 Jan 2026 14:37:40 +0000 Subject: [PATCH 6/7] Update op-stack/fault-proofs/fp-components.mdx Co-authored-by: Inphi --- op-stack/fault-proofs/fp-components.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/op-stack/fault-proofs/fp-components.mdx b/op-stack/fault-proofs/fp-components.mdx index 89a3b6596..36f25841a 100644 --- a/op-stack/fault-proofs/fp-components.mdx +++ b/op-stack/fault-proofs/fp-components.mdx @@ -29,7 +29,7 @@ The OP Stack's unique, modular design allows the decoupling of the FPP and FPVM, ## Fault proof program -The Fault Proof (FPP) is one of the modules in the OP Stack's fault proof system. +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 exection client code. The default for this system component is `op-program`, a combination of `op-geth` and `op-node`, both written in Go. For the Rust stack there is `kona-client` which is a combination of `kona-node` and `op-reth`. 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. From c6624dcde39039d3ff40ef5b344d87bca9075660 Mon Sep 17 00:00:00 2001 From: Zak Ayesh <44901995+ZakAyesh@users.noreply.github.com> Date: Thu, 8 Jan 2026 15:36:55 +0000 Subject: [PATCH 7/7] clean up --- .../guides/features/switching-to-kona-proofs.mdx | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/chain-operators/guides/features/switching-to-kona-proofs.mdx b/chain-operators/guides/features/switching-to-kona-proofs.mdx index 6644a0a41..91d4013ef 100644 --- a/chain-operators/guides/features/switching-to-kona-proofs.mdx +++ b/chain-operators/guides/features/switching-to-kona-proofs.mdx @@ -80,10 +80,7 @@ The high-level flow is: Your challengers must be able to play both cannon and kona games before you change the respected game type. - - These settings should already be in place from the cannon+kona upgrade preparation. This step is about double-checking before you switch. - - + 1. **Trace types** If you explicitly configure trace types, ensure that `cannon-kona` is included. A typical setting is: @@ -111,8 +108,6 @@ The high-level flow is: --cannon-kona-prestates-url= ``` - For operational simplicity, a single location for all prestates is recommended. - 3. **Kona host binary** For operators not using the standard OP Labs `op-challenger` Docker images, you must also provide: