Merge pull request #7031 from ethereum-optimism/aj/game-scripts

op-challenger: Make scripts more flexible

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/alphabet/init_game.sh

@@ -15,7 +15,7 @@ make cannon-prestate
 make devnet-up
 
 DEVNET_SPONSOR="ac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
-DISPUTE_GAME_PROXY=$(jq -r .DisputeGameFactoryProxy $MONOREPO_DIR/.devnet/addresses.json)
+DISPUTE_GAME_FACTORY=$(jq -r .DisputeGameFactoryProxy $MONOREPO_DIR/.devnet/addresses.json)
 
 echo "----------------------------------------------------------------"
 echo " Dispute Game Factory at $DISPUTE_GAME_PROXY"
@@ -59,43 +59,8 @@ do
   sleep 2
 done
 
-# Fetch the latest block number
-L2_BLOCK_NUMBER=$(cast call $L2_OUTPUT_ORACLE_PROXY "latestBlockNumber()")
-echo "Using the latest L2OO block number: $L2_BLOCK_NUMBER"
-
-# We will use the l2 block number of 1 for the dispute game.
-# We need to check that the block oracle contains the corresponding l1 block number.
-echo "Checkpointing the block oracle..."
-L1_CHECKPOINT=$(cast send --private-key $DEVNET_SPONSOR $BLOCK_ORACLE_PROXY "checkpoint()" --json | jq -r .blockNumber | cast to-dec)
-((L1_CHECKPOINT=L1_CHECKPOINT-1))
-echo "L1 Checkpoint: $L1_CHECKPOINT"
-
-INDEX=$(cast call $L2_OUTPUT_ORACLE_PROXY "getL2OutputIndexAfter(uint256)" $L2_BLOCK_NUMBER | cast to-dec)
-((PRIOR_INDEX=INDEX-1))
-echo "Getting the l2 output at index $PRIOR_INDEX"
-cast call $L2_OUTPUT_ORACLE_PROXY "getL2Output(uint256)" $PRIOR_INDEX
-
-echo "Getting the l2 output at index $INDEX"
-cast call $L2_OUTPUT_ORACLE_PROXY "getL2Output(uint256)" $INDEX
-
-# (Alphabet) Fault game type = 255
-GAME_TYPE=255
-
 # Root claim commits to the entire trace.
 # Alphabet game claim construction: keccak256(abi.encode(trace_index, trace[trace_index]))
 ROOT_CLAIM=$(cast keccak $(cast abi-encode "f(uint256,uint256)" 15 122))
 
-# Fault dispute game extra data is calculated as follows.
-# abi.encode(uint256(l2_block_number), uint256(l1 checkpoint))
-EXTRA_DATA=$(cast abi-encode "f(uint256,uint256)" $L2_BLOCK_NUMBER $L1_CHECKPOINT)
-
-echo "Initializing the game"
-FAULT_GAME_ADDRESS=$(cast call --private-key $MALLORY_KEY $DISPUTE_GAME_PROXY "create(uint8,bytes32,bytes)" $GAME_TYPE $ROOT_CLAIM $EXTRA_DATA)
-
-echo "Creating game at address $FAULT_GAME_ADDRESS"
-cast send --private-key $MALLORY_KEY $DISPUTE_GAME_PROXY "create(uint8,bytes32,bytes)" $GAME_TYPE $ROOT_CLAIM $EXTRA_DATA
-
-FORMATTED_ADDRESS=$(cast parse-bytes32-address $FAULT_GAME_ADDRESS)
-echo "Formatted Address: $FORMATTED_ADDRESS"
-
-echo $FORMATTED_ADDRESS > $CHALLENGER_DIR/.fault-game-address
+GAME_TYPE=255 ${SOURCE_DIR}/../create_game.sh http://localhost:8545 "${DISPUTE_GAME_FACTORY}" "${ROOT_CLAIM}" --private-key "${DEVNET_SPONSOR}"

op-challenger/scripts/create_game.sh

+#!/usr/bin/env bash
+set -euo pipefail
+
+SOURCE_DIR=$(cd $(dirname "${BASH_SOURCE[0]}") && pwd)
+CHALLENGER_DIR=$(echo ${SOURCE_DIR%/*})
+MONOREPO_DIR=$(echo ${CHALLENGER_DIR%/*})
+
+# ./create_game.sh <rpc-addr> <dispute-game-factory-addr> <cast signing args>
+RPC=${1:?Must specify RPC address}
+FACTORY_ADDR=${2:?Must specify factory address}
+ROOT_CLAIM=${3:?Must specify root claim}
+SIGNER_ARGS="${@:4}"
+
+# Default to Cannon Fault game type
+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)' "${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 '.logs[0].topics[1]' | cast to-dec)
+echo "L1 Checkpoint: $L1_CHECKPOINT"
+
+# Fault dispute game extra data is calculated as follows.
+# abi.encode(uint256(l2_block_number), uint256(l1 checkpoint))
+EXTRA_DATA=$(cast abi-encode "f(uint256,uint256)" "${L2_BLOCK_NUM}" "${L1_CHECKPOINT}")
+
+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/list_claims.sh

+#!/usr/bin/env bash
+
+set -euo pipefail
+
+RPC=${1:?Must specify RPC address}
+GAME_ADDR=${2:?Must specify fault dispute game address}
+
+COUNT=$(cast call --rpc-url "${RPC}" "${GAME_ADDR}" 'claimDataLen() returns(uint256)')
+echo "Claim count: ${COUNT}"
+((COUNT=COUNT-1))
+for i in $(seq 0 "${COUNT}")
+do
+  CLAIM=$(cast call --rpc-url "${RPC}" "${GAME_ADDR}" 'claimData(uint256) returns(uint32 parentIndex, bool countered, bytes32 claim, uint128 position, uint128 clock)' "${i}")
+  SAVEIFS=$IFS   # Save current IFS (Internal Field Separator)
+  IFS=$'\n'      # Change IFS to newline char
+  CLAIM=($CLAIM) # split the string into an array by the same name
+  IFS=$SAVEIFS   # Restore original IFS
+
+  echo "${i}  Parent: ${CLAIM[0]} Countered: ${CLAIM[1]} Claim: ${CLAIM[2]} Position: ${CLAIM[3]} Clock ${CLAIM[4]}"
+done

op-challenger/scripts/move.sh

+#!/bin/bash
+set -euo pipefail
+
+RPC=${1:?Must specify RPC URL}
+GAME_ADDR=${2:?Must specify game address}
+ACTION=${3:?Must specify attack or defend}
+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}"
+
+if [[ "${ACTION}" != "attack" && "${ACTION}" != "defend" ]]
+then
+  echo "Action must be either attack or defend"
+  exit 1
+fi
+
+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}"

op-challenger/scripts/visualize.sh

@@ -2,23 +2,8 @@
 
 set -euo pipefail
 
-if [ $# -eq 0 ]
-  then
-    echo "Missing Fault Dispute Game address argument"
-fi
-
-echo ""
-echo "Visualize the fault dispute game at https://dispute.clab.by/game?addr=$1"
-echo ""
-
-DISPUTE_GAME_PROXY=$(jq .DisputeGameFactoryProxy .devnet/addresses.json)
-DISPUTE_GAME_PROXY=$(echo $DISPUTE_GAME_PROXY | tr -d '"')
-
-echo "----------------------------------------------------------------"
-echo " Dispute Game Factory at $DISPUTE_GAME_PROXY"
-echo "----------------------------------------------------------------"
-
-FAULT_GAME_ADDRESS=$1
+RPC="${1:?Must specify RPC address}"
+FAULT_GAME_ADDRESS="${2:?Must specify game address}"
 
 DIR=$(cd $(dirname "${BASH_SOURCE[0]}") && pwd)
 DIR=$(echo ${DIR%/*/*})
@@ -26,6 +11,6 @@ cd $DIR/packages/contracts-bedrock
 
 forge script scripts/FaultDisputeGameViz.s.sol \
   --sig "remote(address)" $FAULT_GAME_ADDRESS \
-  --fork-url http://localhost:8545
+  --fork-url "$RPC"
 
 mv dispute_game.svg "$dir"