WEB3-557: Updates to deployment documentation on Jan 23

contracts/script/README.md

@@ -5,12 +5,11 @@ An operations guide for the RISC Zero Ethereum contracts.
 > [!NOTE]
 > All the commands in this guide assume your current working directory is the root of the repo.
 
-## Dependencies
+## Setup
 
-Requires [Foundry](https://book.getfoundry.sh/getting-started/installation).
+### Dependencies
 
-> [!NOTE]
-> Running the `manage` commands will run in simulation mode (i.e. will not send transactions) unless the `--broadcast` flag is passed.
+Requires [Foundry](https://book.getfoundry.sh/getting-started/installation).
 
 Some scripts in this guide use `yq` to parse the TOML config files.
 
@@ -20,7 +19,7 @@ You can install `yq` by following the [directions on GitHub][yq-install], or usi
 go install github.com/mikefarah/yq/v4@latest
 ```
 
-## Configuration
+### Configuration
 
 Configurations and deployment state information is stored in `deployment.toml`.
 It contains information about each chain (e.g. name, ID, Etherscan URL), and addresses for the timelock, router, and verifier contracts on each chain.
@@ -36,9 +35,7 @@ rpc-url = "..."
 etherscan-api-key = "..."
 ```
 
-## Environment
-
-### Anvil
+### Development
 
 In development and to test the operations process, you can use Anvil.
 
@@ -53,16 +50,17 @@ Set your RPC URL, as well as your public and private key:
 ```sh
 export DEPLOYER_ADDRESS="0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266"
 export DEPLOYER_PRIVATE_KEY="0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80"
-export CHAIN_KEY="anvil"
 ```
 
 ### Public Networks (Testnet or Mainnet)
 
 Set the chain you are operating on by the key from the `deployment.toml` file.
 An example chain key is "ethereum-sepolia", and you can look at `deployment.toml` for the full list.
 
+When running commands, set the `CHAIN_KEY` env var inline to match the target network.
+
 ```sh
-export CHAIN_KEY="xxx-testnet"
+CHAIN_KEY="xxx-testnet" contracts/script/test
 ```
 
 **Based on the chain key, the `manage` script will automatically load environment variables from deployment.toml and deployment_secrets.toml**
@@ -93,6 +91,10 @@ Also requires that you have a [Fireblocks API account](https://developers.firebl
 
 Set your public key, your Etherscan API key, and the necessary parameters for Fireblocks:
 
+> [!NOTE]
+> Deployment to Linea Sepolia requires the following patch
+> [fireblocks-json-rpc/pull/24](https://github.com/fireblocks/fireblocks-json-rpc/pull/24)
+
 > [!NOTE]
 > Fireblocks only supports RSA for API request signing.
 > `FIREBLOCKS_API_PRIVATE_KEY_PATH` can be the key itself, rather than a path.
@@ -133,6 +135,7 @@ Then, in the instructions below, pass the `--fireblocks` (`-f`) flag to the `man
     MIN_DELAY=1 \
     PROPOSER="${ADMIN_ADDRESS:?}" \
     EXECUTOR="${ADMIN_ADDRESS:?}" \
+    CHAIN_KEY="..." \
     contracts/script/manage DeployTimelockRouter
 
     ...
@@ -182,7 +185,7 @@ This is a two-step process, guarded by the `TimelockController`.
 1. Dry run deployment of Groth16 verifier and estop:
 
     ```sh
-    contracts/script/manage DeployEstopGroth16Verifier
+    CHAIN_KEY="..." contracts/script/manage DeployEstopGroth16Verifier
     ```
 
     > [!IMPORTANT]
@@ -207,7 +210,7 @@ This is a two-step process, guarded by the `TimelockController`.
     > The verify functionality of forge script appears to be broken, see #393
 
     ```sh
-    VERIFIER_SELECTOR="0x..." contracts/script/verify-groth16-verifier.sh 
+    VERIFIER_SELECTOR="0x..." CHAIN_KEY="..." contracts/script/verify-groth16-verifier.sh 
     ```
 
 4. Add the addresses for the newly deployed contract to the `deployment.toml` file.
@@ -217,13 +220,13 @@ This is a two-step process, guarded by the `TimelockController`.
 5. Test the deployment.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
 6. Dry run the operation to schedule the operation to add the verifier to the router.
 
     ```sh
-    VERIFIER_SELECTOR="0x..." contracts/script/manage ScheduleAddVerifier
+    VERIFIER_SELECTOR="0x..." CHAIN_KEY="..." contracts/script/manage ScheduleAddVerifier
     ```
 
     > [!NOTE]
@@ -244,7 +247,7 @@ After the delay on the timelock controller has passed, the operation to add the
 1. Dry run the transaction to execute the add verifier operation:
 
     ```sh
-    VERIFIER_SELECTOR="0x..." contracts/script/manage FinishAddVerifier
+    VERIFIER_SELECTOR="0x..." CHAIN_KEY="..." contracts/script/manage FinishAddVerifier
     ```
 
 2. Run the command again with `--broadcast`
@@ -256,7 +259,7 @@ After the delay on the timelock controller has passed, the operation to add the
 4. Test the deployment.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
 ## Deploy a set verifier with emergency stop mechanism
@@ -288,7 +291,7 @@ This is a two-step process, guarded by the `TimelockController`.
 2. Dry run deployment of the set verifier and estop:
 
    ```sh
-   contracts/script/manage DeployEstopSetVerifier
+   CHAIN_KEY="..." contracts/script/manage DeployEstopSetVerifier
    ```
 
    > [!IMPORTANT]
@@ -316,13 +319,13 @@ This is a two-step process, guarded by the `TimelockController`.
 5. Test the deployment.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
 6. Dry run the operation to schedule the operation to add the verifier to the router.
 
    ```sh
-   contracts/script/manage ScheduleAddVerifier
+   CHAIN_KEY="..." contracts/script/manage ScheduleAddVerifier
    ```
 
 7. Send the transaction for the scheduled update by running the command again with `--broadcast`.
@@ -339,7 +342,7 @@ After the delay on the timelock controller has passed, the operation to add the
 1. Dry run the transaction to execute the add verifier operation:
 
     ```sh
-    VERIFIER_SELECTOR="0x..." contracts/script/manage FinishAddVerifier
+    VERIFIER_SELECTOR="0x..." CHAIN_KEY="..." contracts/script/manage FinishAddVerifier
     ```
 
 2. Run the command again with `--broadcast`
@@ -351,7 +354,7 @@ After the delay on the timelock controller has passed, the operation to add the
 4. Test the deployment.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
 ## Remove a verifier
@@ -363,7 +366,7 @@ This is a two-step process, guarded by the `TimelockController`.
 1. Dry run the transaction to schedule the remove verifier operation:
 
     ```sh
-    VERIFIER_SELECTOR="0x..." contracts/script/manage ScheduleRemoveVerifier
+    VERIFIER_SELECTOR="0x..." CHAIN_KEY="..." contracts/script/manage ScheduleRemoveVerifier
     ```
 
 2. Run the command again with `--broadcast`
@@ -375,7 +378,7 @@ This is a two-step process, guarded by the `TimelockController`.
 1. Dry run the transaction to execute the remove verifier operation:
 
     ```sh
-    VERIFIER_SELECTOR="0x..." contracts/script/manage FinishRemoveVerifier
+    VERIFIER_SELECTOR="0x..." CHAIN_KEY="..." contracts/script/manage FinishRemoveVerifier
     ```
 
 2. Run the command again with `--broadcast`
@@ -387,7 +390,7 @@ This is a two-step process, guarded by the `TimelockController`.
 4. Test the deployment.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
 ## Update the TimelockController minimum delay
@@ -402,6 +405,7 @@ The minimum delay (`MIN_DELAY`) on the timelock controller is denominated in sec
 
     ```sh
     MIN_DELAY=10 \
+    CHAIN_KEY="..." \
     contracts/script/manage ScheduleUpdateDelay
     ```
 
@@ -417,6 +421,7 @@ Execute the action:
 
     ```sh
     MIN_DELAY=10 \
+    CHAIN_KEY="..." \
     contracts/script/manage FinishUpdateDelay
     ```
 
@@ -427,7 +432,7 @@ Execute the action:
 5. Test the deployment.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
 ## Cancel a scheduled timelock operation
@@ -450,7 +455,7 @@ Use the following steps to cancel an operation that is pending on the `TimelockC
 2. Dry run the transaction to cancel the operation.
 
     ```sh
-    contracts/script/manage CancelOperation -f
+    CHAIN_KEY="..." contracts/script/manage CancelOperation -f
     ```
 
 3. Run the command again with `--broadcast`
@@ -472,6 +477,7 @@ Three roles are supported:
     ```sh
     ROLE="executor" \
     ACCOUNT="0x00000000000000aabbccddeeff00000000000000" \
+    CHAIN_KEY="..." \
     contracts/script/manage ScheduleGrantRole
     ```
 
@@ -486,6 +492,7 @@ Three roles are supported:
     ```sh
     ROLE="executor" \
     ACCOUNT="0x00000000000000aabbccddeeff00000000000000" \
+    CHAIN_KEY="..." \
     contracts/script/manage FinishGrantRole
     ```
 
@@ -528,6 +535,7 @@ Three roles are supported:
     ```sh
     ROLE="executor" \
     ACCOUNT="0x00000000000000aabbccddeeff00000000000000" \
+    CHAIN_KEY="..." \
     contracts/script/manage ScheduleRevokeRole
     ```
 
@@ -551,6 +559,7 @@ cast call --rpc-url ${RPC_URL:?} \
     ```sh
     ROLE="executor" \
     ACCOUNT="0x00000000000000aabbccddeeff00000000000000" \
+    CHAIN_KEY="..." \
     contracts/script/manage FinishRevokeRole
     ```
 
@@ -592,6 +601,7 @@ If your private key is compromised, you can renounce your role(s) without waitin
     ```sh
     RENOUNCE_ROLE="executor" \
     RENOUNCE_ADDRESS="0x00000000000000aabbccddeeff00000000000000" \
+    CHAIN_KEY="..." \
     contracts/script/manage RenounceRole
     ```
 
@@ -625,6 +635,7 @@ Activate the emergency stop:
 
     ```sh
     VERIFIER_SELCTOR="0x..." \
+    CHAIN_KEY="..." \
     contracts/script/manage ActivateEstop
     ```
 
@@ -637,7 +648,7 @@ Activate the emergency stop:
 4. Run the deployment tests.
 
     ```sh
-    contracts/script/test
+    CHAIN_KEY="..." contracts/script/test
     ```
 
     > [!IMPORTANT]

contracts/script/manage

@@ -59,21 +59,21 @@ echo "Loading environment variables from deployment_secrets.toml"
 if [ -z "$RPC_URL" ]; then
     echo 'RPC_URL from deployment_secrets.toml'
     export RPC_URL=$(yq eval -e ".chains[\"${CHAIN_KEY:?}\"].rpc-url" $CONTRACTS_DIR/deployment_secrets.toml)
-    [ -n "$RPC_URL" ] || exit 1
+    [ -n "$RPC_URL" ] && [ "$RPC_URL" != "null" ] || exit 1
 else
     echo "RPC_URL from env $RPC_URL"
 fi
 if [ -z "$ETHERSCAN_URL" ]; then
     echo 'ETHERSCAN_URL from deployment.toml'
     export ETHERSCAN_URL=$(yq eval -e ".chains[\"${CHAIN_KEY:?}\"].etherscan-url" $CONTRACTS_DIR/deployment.toml)
-    [ -n "$ETHERSCAN_URL" ] || exit 1
+    [ -n "$ETHERSCAN_URL" ] && [ "$ETHERSCAN_URL" != "null" ] || exit 1
 else
     echo "ETHERSCAN_URL from env $ETHERSCAN_URL"
 fi
 if [ -z "$ETHERSCAN_API_KEY" ]; then
     echo -n 'ETHERSCAN_API_KEY from deployment_secrets.toml'
     export ETHERSCAN_API_KEY=$(yq eval -e ".chains[\"${CHAIN_KEY:?}\"].etherscan-api-key" $CONTRACTS_DIR/deployment_secrets.toml)
-    [ -n "$ETHERSCAN_API_KEY" ] || exit 1
+    [ -n "$ETHERSCAN_API_KEY" ] && [ "$ETHERSCAN_API_KEY" != "null" ] || exit 1
 else
     echo "ETHERSCAN_API_KEY from env $ETHERSCAN_API_KEY"
 fi

contracts/script/test

@@ -13,7 +13,7 @@ echo "Loading environment variables from deployment_secrets.toml"
 if [ -z "$RPC_URL" ]; then
     echo -n 'RPC_URL from deployment_secrets.toml: ' > /dev/stderr
     export RPC_URL=$(yq eval -e ".chains[\"${CHAIN_KEY:?}\"].rpc-url" $CONTRACTS_DIR/deployment_secrets.toml)
-    [ -n "$RPC_URL" ] || exit 1
+    [ -n "$RPC_URL" ] && [ "$RPC_URL" != "null" ] || exit 1
 else
     echo -n "RPC_URL from env $RPC_URL"
 fi