docs(contracts): improve deployment instructions and scripts (#181)

Author: mattstam

contracts/DESIGN.md

@@ -1,4 +1,4 @@
-# Design
+# Contract Design
 
 This document describes the Succinct Prover Network contracts in detail.
 

contracts/OPERATIONS.md

@@ -0,0 +1,94 @@
+# Contract Operations
+
+This document contains commands to interact with the deployed contracts.
+
+To run these cast commands, you need to set the environment variables to the addresses of the contracts you deployed, by looking at the [deployments](./deployments) directory.
+
+This can be automatically done with the following command:
+
+```sh
+CHAIN_ID=$(cast chain-id --rpc-url "$ETH_RPC_URL") && export $(jq -r 'to_entries|map("\(.key)=\(.value)")|.[]' ./deployments/${CHAIN_ID}.json) >/dev/null
+```
+
+## Staking
+
+### Create a Prover
+
+```sh
+cast send $STAKING "createProver(uint256)" 1000 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+### Stake
+
+```sh
+cast send $PROVE "approve(address,uint256)" $STAKING 10000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+```sh
+cast send $STAKING "stake(address,uint256)" $PROVER 9990e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+### Unstake
+
+```sh
+cast send $STAKING "requestUnstake(uint256)" 2000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+```sh
+cast send $STAKING "finishUnstake()" --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+### Dispense
+
+Figure out the maximum amount of $PROVE that can be dispensed:
+
+```sh
+export DISPENSE_AMOUNT=$(cast call $STAKING "maxDispense()" --rpc-url $ETH_RPC_URL)
+```
+
+Send some $PROVE to the $STAKING contract (assumes your balance is enough):
+
+```sh
+cast send $PROVE "transfer(address,uint256)" $STAKING $DISPENSE_AMOUNT --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+Dispense it:
+
+```sh
+cast send $STAKING "dispense(uint256)" $DISPENSE_AMOUNT --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+OR just simply dispense the maximum amount:
+
+```sh
+cast send $STAKING "dispense(uint256)" $(cast max-uint) --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+## vApp
+
+### Deposit
+
+```sh
+cast send $PROVE "approve(address,uint256)" $VAPP 10000000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+```sh
+cast send $VAPP "deposit(uint256)" 10000000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```
+
+## View
+
+
+### Check stake balances
+
+Staker:
+
+```sh
+cast to-dec $(cast call $STAKING "staked(address)" $(cast wallet address --private-key $PRIVATE_KEY) --rpc-url $ETH_RPC_URL)
+```
+
+Prover:
+
+```sh
+cast to-dec $(cast call $STAKING "proverStaked(address)" $PROVER --rpc-url $ETH_RPC_URL)
+```

contracts/README.md

@@ -62,122 +62,116 @@ Then add a `{CHAIN_ID}.json` file in the [deployments](./deployments) directory
 CHAIN_ID=$(cast chain-id --rpc-url $ETH_RPC_URL); mkdir -p ./deployments && [ -f "./deployments/${CHAIN_ID}.json" ] || echo '{}' > "./deployments/${CHAIN_ID}.json"
 ```
 
-### Run the scripts
+Then you should add the `VKEY` and `GENESIS_STATE_ROOT` to the `{CHAIN_ID}.json` file:
 
-Deploy all contracts:
-
-```sh
-FOUNDRY_PROFILE=deploy forge script AllScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
+```json
+{
+  "VKEY": "0x004988f252500633b4d3d369b3726d5bdacfbe35236b36eb2d487af3742c905e",
+  "GENESIS_STATE_ROOT": "0xc88159adb4da01a67b90803d48a35fbf7f457572b61377e5d4b090c89488b838"
+}
 ```
 
-Then mint some $PROVE tokens (assuming you made the $OWNER the same as the $PRIVATE_KEY address):
+Ensure these match the actual vkey and genesis state root for the Rust vApp program.
 
-```sh
-FOUNDRY_PROFILE=deploy forge script MintScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
-```
+Note: the production version of these contracts were deployed using foundry [v1.3.0](https://github.com/foundry-rs/foundry/releases/tag/v1.3.0).
+
+### Bulk deployment
+
+This should generally only be used for testing.
 
-Then create a prover and stake:
+Deploy all contracts at once:
 
 ```sh
-FOUNDRY_PROFILE=deploy forge script CreateProverAndStakeScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
+FOUNDRY_PROFILE=deploy forge script AllScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
 ```
 
 You can append `--verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY` to the above commands to verify the contracts on Etherscan.
 
-## Other Operations
+### Individual deployment
 
-To run cast commands, you need to set the environment variables to the addresses of the contracts you deployed, by looking at the [deployments](./deployments) directory.
+Instead of deploying all contracts at once, it's recommended to deploy each contract individually for production deployments.
 
-```sh
-CHAIN_ID=$(cast chain-id --rpc-url "$ETH_RPC_URL") && export $(jq -r 'to_entries|map("\(.key)=\(.value)")|.[]' ./deployments/${CHAIN_ID}.json) >/dev/null
-```
+#### Pre-deployed contracts
 
-### Deposit
+Fill out `{CHAIN_ID}.json` with any pre-deployed contracts. For example, if there is an existing `PROVE` and `VERIFIER` those keys would be filled:
 
-```sh
-cast send $PROVE "approve(address,uint256)" $VAPP 10000000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+```json
+{
+  "VKEY": "0x004988f252500633b4d3d369b3726d5bdacfbe35236b36eb2d487af3742c905e",
+  "GENESIS_STATE_ROOT": "0xc88159adb4da01a67b90803d48a35fbf7f457572b61377e5d4b090c89488b838",
+  "PROVE": "0x6BEF15D938d4E72056AC92Ea4bDD0D76B1C4ad29",
+  "VERIFIER": "0x397A5f7f3dBd538f23DE225B51f532c34448dA9B"
+}
 ```
 
-```sh
-cast send $VAPP "deposit(uint256)" 10000000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
-```
+#### Deploy each contract
 
-### Withdraw
+Deploy the SuccinctStaking contract:
 
 ```sh
-cast send $VAPP "requestWithdraw(address,uint256)" $(cast wallet address --private-key $PRIVATE_KEY) 100e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+FOUNDRY_PROFILE=deploy forge script SuccinctStakingScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
 ```
 
-You need to wait for the withdrawal to be processed before you can finish it:
+This DOES NOT initalize the contract - this will be done in a later step once references to other contracts are available.
+
+Deploy the $iPROVE contract (assumes $PROVE is already deployed):
 
 ```sh
-if [ $(cast call $VAPP "claimableWithdrawal(address)" $(cast wallet address --private-key $PRIVATE_KEY) --rpc-url $ETH_RPC_URL) -gt 0 ]; then
- cast send $VAPP "finishWithdraw()" --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
-fi
+FOUNDRY_PROFILE=deploy forge script IntermediateSuccinctScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
 ```
 
-### Create a Prover
+Deploy the SuccinctGovernor contract:
 
 ```sh
-cast send $STAKING "createProver()" $(cast wallet address --private-key $PRIVATE_KEY) --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+FOUNDRY_PROFILE=deploy forge script SuccinctGovernorScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
 ```
 
-### Stake
+Deploy the SuccinctVApp implementation and proxy contracts (assumes verifier is already deployed):
 
 ```sh
-cast send $PROVE "approve(address,uint256)" $STAKING 10000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+FOUNDRY_PROFILE=deploy forge script SuccinctVAppScript --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL --verify --verifier etherscan --etherscan-api-key $ETHERSCAN_API_KEY
 ```
 
-```sh
-cast send $STAKING "stake(address,uint256)" $PROVER 9990e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
-```
+If the SP1VerifierGateway is not already deployed, follow steps in [sp1-contracts](https://github.com/succinctlabs/sp1-contracts) to deploy it and fill out the address in your `{CHAIN_ID}.json` file.
 
-### Unstake
+Initalize the SuccinctStaking contract:
 
 ```sh
-cast send $STAKING "requestUnstake(uint256)" 2000e18 --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+FOUNDRY_PROFILE=deploy forge script SuccinctStakingScript --sig "initialize()" --private-key $PRIVATE_KEY --broadcast --rpc-url $ETH_RPC_URL
 ```
 
+Run the integrity check:
+
 ```sh
-cast send $STAKING "finishUnstake()" --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+FOUNDRY_PROFILE=deploy forge script PostDeploymentScript --rpc-url $ETH_RPC_URL
 ```
 
-### Dispense
+If that passes without reverting, the contracts have been successfully deployed and initalized. The addresses are in the `{CHAIN_ID}.json` file.
 
-Figure out the maximum amount of $PROVE that can be dispensed:
+## Verification
 
-```sh
-export DISPENSE_AMOUNT=$(cast call $STAKING "maxDispense()" --rpc-url $ETH_RPC_URL)
-```
+If any of the contracts failed to verify on Etherscan, you can manually verify them by copying the the flatten source code and uploading it to Etherscan.
 
-Send some $PROVE to the $STAKING contract (assumes your balance is enough):
+To do this, go to the address on Etherscan and click "Verify Contract". Choose:
 
-```sh
-cast send $PROVE "transfer(address,uint256)" $STAKING $DISPENSE_AMOUNT --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
-```
+* Compiler: "Solidity (Single File)"
+* Compiler Version: "0.8.28"
+* License: "MIT"
 
-Dispense it:
+Then flatten the contract you're verifying, for example the SuccinctStaking contract:
 
 ```sh
-cast send $STAKING "dispense(uint256)" $DISPENSE_AMOUNT --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
+forge flatten src/SuccinctStaking.sol
 ```
 
-OR just simply dispense the maximum amount:
+Copy the output into the "Contract Code" field.
 
-```sh
-cast send $STAKING "dispense(uint256)" $(cast max-uint) --private-key $PRIVATE_KEY --rpc-url $ETH_RPC_URL
-```
-
-### Check stake balances
+Then enter the compiler settings from the [foundry.toml](./foundry.toml) file's `[profile.deploy]` section.
 
-Staker:
+If any constructor arguements were used but not shown in the "Constructor Arguments" field, use `cast abi-encode` with the appropriate signature to encode them, for example:
 
 ```sh
-cast to-dec $(cast call $STAKING "staked(address)" $(cast wallet address --private-key $PRIVATE_KEY) --rpc-url $ETH_RPC_URL)
+cast abi-encode "constructor(address)" 0xbD74E9B0Dcb0317E26505CA93757c29d564B533B
 ```
 
-Prover:
-
-```sh
-cast to-dec $(cast call $STAKING "proverStaked(address)" $PROVER --rpc-url $ETH_RPC_URL)
-```
+strip the `0x` prefix from this output and paste it into the "Constructor Arguments" field.

contracts/script/deploy/All.s.sol

@@ -25,7 +25,8 @@ contract AllScript is BaseScript, FixtureLoader {
         address PROVE = address(new Succinct{salt: salt}(OWNER));
         address I_PROVE = address(new IntermediateSuccinct{salt: salt}(PROVE, STAKING));
         address GOVERNOR = _deployGovernor(salt, I_PROVE);
-        (address VERIFIER, address VAPP) = _deployVAppAsProxy(salt, OWNER, PROVE, I_PROVE, STAKING);
+        (address VERIFIER, address VAPP, address VAPP_IMPL) =
+            _deployVAppAsProxy(salt, OWNER, PROVE, I_PROVE, STAKING);
 
         // Initialize staking contract
         _initializeStaking(STAKING, GOVERNOR, VAPP, PROVE, I_PROVE);
@@ -34,6 +35,7 @@ contract AllScript is BaseScript, FixtureLoader {
         writeAddress("STAKING", STAKING);
         writeAddress("VERIFIER", VERIFIER);
         writeAddress("VAPP", VAPP);
+        writeAddress("VAPP_IMPL", VAPP_IMPL);
         writeAddress("PROVE", PROVE);
         writeAddress("I_PROVE", I_PROVE);
         writeAddress("GOVERNOR", GOVERNOR);
@@ -60,14 +62,13 @@ contract AllScript is BaseScript, FixtureLoader {
         address PROVE,
         address I_PROVE,
         address STAKING
-    ) internal returns (address, address) {
+    ) internal returns (address, address, address) {
         // Read config
         address AUCTIONEER = readAddress("AUCTIONEER");
-        address VERIFIER = vm.envOr("VERIFIER", address(0));
+        address VERIFIER = readAddress("VERIFIER");
         uint256 MIN_DEPOSIT_AMOUNT = readUint256("MIN_DEPOSIT_AMOUNT");
-        bytes32 VKEY = bytes32(0x00e76fb5ef418452b5e97124585bafbaeb300468cc863e052341ec81b8daa5d8);
-        bytes32 GENESIS_STATE_ROOT =
-            bytes32(0xde6c5941bbaeab97cabda7eaba5e6dd8b5dfb58cb2fb43238a7e707c6b2c587f);
+        bytes32 VKEY = readBytes32("VKEY");
+        bytes32 GENESIS_STATE_ROOT = readBytes32("GENESIS_STATE_ROOT");
 
         // If the verifier is not provided, deploy the SP1VerifierGateway and add v5.0.0 Groth16 SP1Verifier to it
         if (VERIFIER == address(0)) {
@@ -76,23 +77,29 @@ contract AllScript is BaseScript, FixtureLoader {
             SP1VerifierGateway(VERIFIER).addRoute(groth16);
         }
 
+        // Encode the initialize function call data
+        bytes memory initData = abi.encodeCall(
+            SuccinctVApp.initialize,
+            (
+                OWNER,
+                PROVE,
+                I_PROVE,
+                AUCTIONEER,
+                STAKING,
+                VERIFIER,
+                MIN_DEPOSIT_AMOUNT,
+                VKEY,
+                GENESIS_STATE_ROOT
+            )
+        );
+
         // Deploy contract
-        address vappImpl = address(new SuccinctVApp{salt: salt}());
-        address VAPP =
-            address(SuccinctVApp(payable(address(new ERC1967Proxy{salt: salt}(vappImpl, "")))));
-        SuccinctVApp(VAPP).initialize(
-            OWNER,
-            PROVE,
-            I_PROVE,
-            AUCTIONEER,
-            STAKING,
-            VERIFIER,
-            MIN_DEPOSIT_AMOUNT,
-            VKEY,
-            GENESIS_STATE_ROOT
+        address VAPP_IMPL = address(new SuccinctVApp{salt: salt}());
+        address VAPP = address(
+            SuccinctVApp(payable(address(new ERC1967Proxy{salt: salt}(VAPP_IMPL, initData))))
         );
 
-        return (VERIFIER, VAPP);
+        return (VERIFIER, VAPP, VAPP_IMPL);
     }
 
     /// @dev This is a stack-too-deep workaround.