op-challenger: Add documentation for manual testing scripts.

op-challenger/README.md

@@ -20,3 +20,72 @@ to see a list of available options.
 
 `op-challenger` is configurable via command line flags and environment variables. The help menu
 shows the available config options and can be accessed by running `./op-challenger --help`.
+
+## Scripts
+
+The [scripts](scripts) directory contains a collection of scripts to assist with manually creating and playing games.
+This are not intended to be used in production, only to support manual testing and to aid with understanding how
+dispute games work. They also serve as examples of how to use `cast` to manually interact with the dispute game
+contracts.
+
+### Dependencies
+
+These scripts assume that the following tools are installed and available on the current `PATH`:
+
+* `cast` (https://book.getfoundry.sh/cast/)
+* `jq` (https://jqlang.github.io/jq/)
+* `bash`
+
+### [create_game.sh](scripts/create_game.sh)
+
+```shell
+./scripts/create_game.sh <RPC_URL> <GAME_FACTORY_ADDRESS> <ROOT_CLAIM> <SIGNER_ARGS>...
+```
+
+Starts a new fault dispute game that disputes the latest output proposal in the L2 output oracle.
+
+* `RPC_URL` - the RPC endpoint of the L1 endpoint to use (e.g. `http://localhost:8545`).
+* `GAME_FACTORY_ADDRESS` - the address of the dispute game factory contract on L1.
+* `ROOT_CLAIM` a hex encoded 32 byte hash to use as the root claim for the created game.
+* `SIGNER_ARGS` the remaining args are past as arguments to `cast` when sending transactions.
+  These arguments must specify a way for `cast` to sign the transactions.
+  See `cast send --help` for supported options.
+
+Creating a dispute game requires sending two transactions. The first transaction creates a
+checkpoint in the `BlockOracle` that records the L1 block that will be used as the L1 head
+when generating the cannon execution trace. The second transaction then creates the actual
+dispute game, specifying the disputed L2 block number and previously checkpointed L1 head block.
+
+### [move.sh](scripts/move.sh)
+
+```shell
+./scripts/move.sh <RPC_URL> <GAME_ADDRESS> (attack|defend) <PARENT_INDEX> <CLAIM> <SIGNER_ARGS>...
+```
+
+Performs a move to either attack or defend the latest claim in the specified game.
+
+* `RPC_URL` - the RPC endpoint of the L1 endpoint to use (e.g. `http://localhost:8545`).
+* `GAME_ADDRESS` - the address of the dispute game to perform the move in.
+* `(attack|defend)` - the type of move to make.
+  * `attack` indicates that the state hash in your local cannon trace differs to the state
+    hash included in the latest claim.
+  * `defend` indicates that the state hash in your local cannon trace matches the state hash
+    included in the latest claim.
+* `PARENT_INDEX` - the index of the parent claim that will be countered by this new claim.
+  The special value of `latest` will counter the latest claim added to the game.
+* `CLAIM` - the state hash to include in the counter-claim you are posting.
+* `SIGNER_ARGS` the remaining args are past as arguments to `cast` when sending transactions.
+  These arguments must specify a way for `cast` to sign the transactions.
+  See `cast send --help` for supported options.
+
+
+### [list_claims.sh](scripts/list_claims.sh)
+
+```shell
+./scripts/list_claims.sh <RPC> <GAME_ADDR>
+```
+
+Prints the list of current claims in a dispute game.
+
+* `RPC_URL` - the RPC endpoint of the L1 endpoint to use (e.g. `http://localhost:8545`).
+* `GAME_ADDRESS` - the address of the dispute game to list the move in.

op-challenger/scripts/create_game.sh

@@ -15,20 +15,26 @@ SIGNER_ARGS="${@:4}"
 GAME_TYPE=${GAME_TYPE:-0}
 
 # Get the fault dispute game implementation addr
-GAME_IMPL_ADDR=$(cast call --rpc-url "${RPC}" "${FACTORY_ADDR}" 'gameImpls(uint8) returns(address)' 0)
+GAME_IMPL_ADDR=$(cast call --rpc-url "${RPC}" "${FACTORY_ADDR}" 'gameImpls(uint8) returns(address)' "${GAME_TYPE}")
 echo "Fault dispute game impl: ${GAME_IMPL_ADDR}"
 
+# Get the L2 output oracle address
 L2OO_ADDR=$(cast call --rpc-url "${RPC}" "${GAME_IMPL_ADDR}" 'L2_OUTPUT_ORACLE() returns(address)')
 echo "L2OO: ${L2OO_ADDR}"
 
+# Get the block oracle address
 BLOCK_ORACLE_ADDR=$(cast call --rpc-url "${RPC}" "${GAME_IMPL_ADDR}" 'BLOCK_ORACLE() returns(address)')
 echo "Block Oracle: ${BLOCK_ORACLE_ADDR}"
 
+# Get the L2 block number of the latest output proposal. This is the proposal that will be disputed by the created game.
 L2_BLOCK_NUM=$(cast call --rpc-url "${RPC}" "${L2OO_ADDR}" 'latestBlockNumber() public view returns (uint256)')
 echo "L2 Block Number: ${L2_BLOCK_NUM}"
 
+# Create a checkpoint in the block oracle to commit to the current L1 head.
+# This defines the L1 head that will be used in the dispute game.
 echo "Checkpointing the block oracle..."
 L1_CHECKPOINT=$(cast send --rpc-url "${RPC}" ${SIGNER_ARGS} "${BLOCK_ORACLE_ADDR}" "checkpoint()" --json | jq -r .blockNumber | cast to-dec)
+# The L1 head to be used is the block prior to the one the checkpoint transaction was included in.
 ((L1_CHECKPOINT=L1_CHECKPOINT-1))
 echo "L1 Checkpoint: $L1_CHECKPOINT"
 
@@ -38,6 +44,8 @@ EXTRA_DATA=$(cast abi-encode "f(uint256,uint256)" "${L2_BLOCK_NUM}" "${L1_CHECKP
 
 echo "Initializing the game"
 FAULT_GAME_DATA=$(cast send --rpc-url "${RPC}" ${SIGNER_ARGS} "${FACTORY_ADDR}" "create(uint8,bytes32,bytes) returns(address)" "${GAME_TYPE}" "${ROOT_CLAIM}" "${EXTRA_DATA}" --json)
+
+# Extract the address of the newly created game from the receipt logs.
 FAULT_GAME_ADDRESS=$(echo "${FAULT_GAME_DATA}" | jq -r '.logs[0].topics[1]' | cast parse-bytes32-address)
 echo "Fault game address: ${FAULT_GAME_ADDRESS}"
 echo "${FAULT_GAME_ADDRESS}" > $CHALLENGER_DIR/.fault-game-address

op-challenger/scripts/move.sh

@@ -4,11 +4,22 @@ set -euo pipefail
 RPC=${1:?Must specify RPC URL}
 GAME_ADDR=${2:?Must specify game address}
 ACTION=${3:?Must specify attack or defend}
-CLAIM=${4:?Must specify claim hash}
-SIGNER_ARGS="${@:5}"
+PARENT_INDEX=${4:?Must specify parent index. Use latest to counter the latest claim added to the game.}
+CLAIM=${5:?Must specify claim hash}
+SIGNER_ARGS="${@:6}"
 
-# Respond to the last claim that was made
-CLAIM_IDX=$(cast call --rpc-url "${RPC}" "${GAME_ADDR}" 'claimDataLen() returns(uint256)')
-((CLAIM_IDX=CLAIM_IDX-1))
+if [[ "${ACTION}" != "attack" && "${ACTION}" != "defend" ]]
+then
+  echo "Action must be either attack or defend"
+  exit 1
+fi
 
-cast send --rpc-url "${RPC}" ${SIGNER_ARGS} "${GAME_ADDR}" "$ACTION(uint256,bytes32)" "${CLAIM_IDX}" "${CLAIM}"
+if [[ "${PARENT_INDEX}" == "latest" ]]
+then
+  # Fetch the index of the most recent claim made.
+  PARENT_INDEX=$(cast call --rpc-url "${RPC}" "${GAME_ADDR}" 'claimDataLen() returns(uint256)')
+  ((PARENT_INDEX=PARENT_INDEX-1))
+fi
+
+# Perform the move.
+cast send --rpc-url "${RPC}" ${SIGNER_ARGS} "${GAME_ADDR}" "$ACTION(uint256,bytes32)" "${PARENT_INDEX}" "${CLAIM}"