Merge pull request #7184 from ethereum-optimism/inphi/honest-chal

specs: Honest Challenger specs

specs/fault-dispute-game.md

@@ -7,6 +7,7 @@
 - [Overview](#overview)
 - [Definitions](#definitions)
   - [Virtual Machine (VM)](#virtual-machine-vm)
+  - [PreimageOracle](#preimageoracle)
   - [Execution Trace](#execution-trace)
   - [Claims](#claims)
   - [DAG](#dag)
@@ -20,6 +21,7 @@
     - [Defend](#defend)
   - [Step](#step)
   - [Step Types](#step-types)
+  - [PreimageOracle Interaction](#preimageoracle-interaction)
   - [Team Dynamics](#team-dynamics)
   - [Game Clock](#game-clock)
   - [Resolution](#resolution)
@@ -44,7 +46,7 @@ claims made that are disputed and which aren't, to determine the winners of the
 ### Virtual Machine (VM)
 
 This is a state transition function (STF) that takes a _pre-state_ and computes the post-state.
-The VM may reference external data during the STF and as such, it also accepts a _proof_ of this data.
+The VM may access data referenced during the STF and as such, it also accepts a _proof_ of this data.
 Typically, the pre-state contains a commitment to the _proof_ to verify the integrity of the data referenced.
 
 Mathemtically, we define the STF as $VM(S_i,P_i)$ where
@@ -52,6 +54,12 @@ Mathemtically, we define the STF as $VM(S_i,P_i)$ where
 - $S_i$ is the pre-state
 - $P_i$ is an optional proof needed for the transition from $S_i$ to $S_{i+1}$.
 
+### PreimageOracle
+
+This is a pre-image data store. It is often used by VMs to read external data during its STF.
+Before successfully executing a VM STF, it may be necessary to preload the PreimageOracle with pertinent data.
+The method for key-based retrieval of these pre-images varies according to the specific VM.
+
 ### Execution Trace
 
 An execution trace $T$ is a sequence $(S_0,S_1,S_2,...,S_n)$ where each $S_i$ is a VM state and
@@ -62,7 +70,7 @@ We refer to this state as the **ABSOLUTE\_PRESTATE**.
 ### Claims
 
 Claims assert an execution trace. This is represented as `ClaimHash`, a `bytes32` commitment to
-the last VM state in the trace. A FDG is initialized with a root claim, which commits to the entire
+the last VM state in a trace. A FDG is initialized with a root claim, which commits to the entire
 execution trace. As we'll see later, there can be multiple claims, committing to different states in the FDG.
 
 ### DAG
@@ -97,6 +105,7 @@ Positions higher up the game tree also cover the deepest, right-most positions r
 We refer to this coverage as the **trace index** of a Position.
 
 > This means claims commit to an execution trace that terminates at the same index as their Position's trace index.
+> That is, for a given trace index $n$, its ClaimHash corresponds to the $S_n$ th state in the trace.
 
 Note that there can be multiple positions covering the same _trace index_.
 
@@ -198,6 +207,22 @@ Players interface with `step` by providing an indicator of attack and state data
 that corresponds to the expected pre/post state (depending on whether it's an attack or defend).
 The FDG will assert that an existing claim commits to the state data provided by players.
 
+### PreimageOracle Interaction
+
+Certain steps (VM state transitions) require external data to be available by the `PreimageOracle`.
+To ensure a successful state transition, players should provide this data in advance.
+The FDG provides the following interface to manage data loaded to the `PreimageOracle`:
+
+```solidity
+/// @notice Posts the requested local data to the VM's `PreimageOralce`.
+/// @param _ident The local identifier of the data to post.
+/// @param _partOffset The offset of the data to post.
+function addLocalData(uint256 _ident, uint256 _partOffset) external;
+```
+
+The `addLocalData` function loads parts of a pre-image to VM's `PreimageOracle`.
+Players use this to ensure pre-image parts are available to the VM during a step.
+
 ### Team Dynamics
 
 Challengers seek to dispute the root claim, while Defenders aim to support it.

specs/honest-challenger-fdg.md

+# Honest Challenger (Fault Dispute Game)
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Overview](#overview)
+- [FDG Responses](#fdg-responses)
+  - [Root Claims](#root-claims)
+  - [Counter Claims](#counter-claims)
+  - [Steps](#steps)
+- [Resolution](#resolution)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+The honest challenger is an agent interacting in the [Fault Dispute Game](./fault-dispute-game.md)
+(FDG) that supports honest claims and disputes false claims.
+An honest challenger strives to ensure a correct, truthful, game resolution.
+The honest challenger is also _rational_ as any deviation from its behavior will result in
+negative outcomes.
+This document specifies the expected behavior of an honest challenger.
+
+## Overview
+
+The Honest Challenger has two primary duties:
+
+1. Support valid root claims in Fault Dispute Games.
+2. Dispute invalid root claims in Fault Dispute Games.
+
+The honest challenger polls the `DisputeGameFactory` contract for new and on-going Fault
+Dispute Games.
+For verifying the legitimacy of claims, it relies on a synced, trusted rollup node
+as well as a trace provider (ex: [Cannon](./cannon-fault-proof-vm.md)).
+The trace provider must be configured with the [ABSOLUTE_PRESTATE](./fault-dispute-game.md#execution-trace)
+of the FDG being interacted with to generate the traces needed to make truthful claims.
+
+## FDG Responses
+
+### Root Claims
+
+When a `FaultDisputeGame` is created, the honest challenger has two possible correct responses
+to its root claim:
+
+1. [**Attack**](./fault-dispute-game.md#attack) if they disagree with the root claim.
+The root claim commits to the entire execution trace, so the first move here is to
+attack with the [ClaimHash](./fault-dispute-game.md#claims) at the midpoint
+instruction within their execution trace.
+2. **Do Nothing** if they agree with the root claim. They do nothing because if the root
+claim is left un-countered, the game resolves to their agreement.
+NOTE: The honest challenger will still track this game in order to defend any subsequent
+claims made against the root claim - in effect, "playing the game".
+
+### Counter Claims
+
+For every claim made in a dispute game with a [game tree](./fault-dispute-game.md#game-tree)
+depth in the range of `[1, MAX_DEPTH]`, the honest challenger processes them and performs
+a response.
+
+To determine the appropriate response, the challenger first needs to know which
+[_team_](./fault-dispute-game.md#team-dynamics) it belongs to.
+This determines the set of claims it should respond to in the FDG.
+If the agent determines itself to be a Defender, which aims to support the root claim,
+then it must dispute claims positioned at odd depths in the game tree.
+Otherwise, it disputes claims positioned at even depths in the game tree.
+This means an honest challenger only responds to claims made by the opposing team.
+
+The next step is to determine whether the claim has a valid commitment (i.e. `ClaimHash`).
+If the `ClaimHash` matches the honest challenger's at the same trace index, then we
+disagree with the claim's stance by moving to [defend](./fault-dispute-game.md#defend).
+Otherwise, the claim is [attacked](./fault-dispute-game.md#attack).
+
+The following pseudocode illustrates the response logic.
+
+```python
+class Team(Enum):
+    DEFENDER = 0
+    CHALLENGER = 1
+
+class Claim:
+    position: uint64
+    claim_hash: ClaimHash
+
+MAX_TRACE = 2**MAX_GAME_DEPTH
+
+def respond(claim: Claim, chal: Team, chal_trace: List[ClaimHash, MAX_TRACE]):
+    if depth(claim.position) % 2 != chal.value:
+        if chal_trace[trace_index(claim.position)] == claim.claim_hash:
+            defend()
+        else:
+            attack()
+    else: pass # no response
+```
+
+In attack or defense, the honest challenger submit a `ClaimHash` corresponding to the
+state identified by the trace index of their response position.
+
+The honest challenger responds to claims as soon as possible to avoid the clock of its
+counter-claim from expiring.
+
+### Steps
+
+At the max depth of the game, claims represent commitments to the state of the fault proof VM
+at a single instruction step interval.
+Because the game can no longer bisect further, when the honest challenger has a valid move
+against these claims (valid defined by the response in [Counter Claims](#counter-claims)),
+the only option for an honest challenger is to execute a VM step on-chain to disprove the claim at `MAX_GAME_DEPTH`.
+
+Similar to the above section, the honest challenger will issue an
+[attack step](./fault-dispute-game.md#step-types) when in response to such claims with
+invalid `ClaimHash` commitments. Otherwise, it issues a _defense step_.
+
+## Resolution
+
+When the [chess clock](./fault-dispute-game.md#game-clock) of a `FaultDisputeGame` team
+runs out, the game can be resolved.
+The honest challenger does this by calling the `resolve` function on the
+`FaultDisputeGame` contract.
+
+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 incentivized to resolve the game promptly to capture the bonds.