feat: v3.0.0-rc4 + simplify artifacts flow + better documentation (#30)

Co-authored-by: mattstam <codeguy0112358@gmail.com>

Author: ratankaliani

Cargo.lock

@@ -11,4 +11,4 @@ path = "src/bin/artifacts.rs"
 anyhow = "1.0.86"
 dotenv = "0.15.0"
 log = "0.4.21"
-sp1-sdk = "3.0.0-rc3"
+sp1-sdk = "3.0.0-rc4"

Cargo.toml

@@ -1,7 +1,11 @@
-# Update SP1 Contracts with New SP1 Version
+# Add a new SP1 Version to `sp1-contracts`
 
 This section outlines the steps required to update the SP1 contracts repository with a new SP1 version. Follow these instructions to ensure the SP1 contracts are correctly updated and aligned with the latest version.
 
+## Add SP1 Verifier Contracts
+
+Let's add the verifier contracts for a new `sp1-sdk` tag.
+
 1. Change the version tag in `Cargo.toml` to the target `sp1` version.
 
 ```toml
@@ -15,11 +19,23 @@ sp1-sdk = "<SP1_TAG>"
 cargo update
 
 cargo run --bin artifacts --release
+
+...
+
+[sp1] plonk circuit artifacts for version v3.0.0-rc4 do not exist at /Users/ratankaliani/.sp1/circuits/plonk/v3.0.0-rc4. downloading...
+⠦ [00:00:08] [#######>---------------------] 272.01 MiB/1.07 GiB (29.22 MiB/s, 28s)
 ```
 
-3. Open a PR to commit the changes to `main`.
-4. After merging to `main`, create a release tag with the same version as the `sp1` tag used.
+This will download the circuit artifacts for the SP1 version, and write the verifier contracts to `/contracts/src/{SP1_CIRCUIT_VERSION}`.
+
+## Create a new release
+
+For users to use the contracts associated with a specific `sp1-sdk` tag, we need to create a new release.
+
+1. Open a PR to add the changes to `main`.
+2. After merging to `main`, create a release tag with the same version as the `sp1` tag used (e.g `2.0.0`). For release candidates (e.g. `v3.0.0-rc4`), the release tag should be a **pre-release** tag.
+3. Now users will be able to install contracts for this version with `forge install succinctlabs/sp1-contracts@VERSION`. By default, `forge install` will install the latest release.
 
-## Miscellaneous
+## Appendix
 
 The SP1 Solidity contract artifacts are included in each release of `sp1`. You can see how these are included in the `sp1` repository [here](https://github.com/succinctlabs/sp1/blob/21455d318ae383b317c92e10709bbfc313d8f1df/recursion/gnark-ffi/src/plonk_bn254.rs#L57-L96).

UPDATE_CONTRACTS.md

@@ -44,4 +44,7 @@ ETHERSCAN_API_URL_BASE_SEPOLIA=https://api-sepolia.basescan.org/api
 ETHERSCAN_API_URL_OPTIMISM=https://api-optimistic.etherscan.io/api
 ETHERSCAN_API_URL_OPTIMISM_SEPOLIA=https://api-sepolia-optimistic.etherscan.io/api
 ETHERSCAN_API_URL_SCROLL=https://api.scrollscan.com/api
-ETHERSCAN_API_URL_SCROLL_SEPOLIA=https://api-sepolia.scrollscan.com/api
+ETHERSCAN_API_URL_SCROLL_SEPOLIA=https://api-sepolia.scrollscan.com/api
+
+## Contract Deployer Private Key
+PRIVATE_KEY=

contracts/.env.example

@@ -12,5 +12,7 @@
   "V2_0_0_SP1_VERIFIER_PLONK": "0xaeE21CeadF7A03b3034DAE4f190bFE5F861b6ebf",
   "V3_0_0_RC1_SP1_VERIFIER_GROTH16": "0x8dB92f28D7C30154d38E55DbA1054b5A7Fc5A829",
   "V3_0_0_RC3_SP1_VERIFIER_GROTH16": "0x890E1c4ff98453f1201e5cB65F6C588FD28748b0",
-  "V3_0_0_RC3_SP1_VERIFIER_PLONK": "0x31aeD863BecC509B9e16403c52C07560A0d4ecBf"
+  "V3_0_0_RC3_SP1_VERIFIER_PLONK": "0x31aeD863BecC509B9e16403c52C07560A0d4ecBf",
+  "V3_0_0_RC4_SP1_VERIFIER_GROTH16": "0xbEe24654bF5D675D88e504a0DC148022664Ce436",
+  "V3_0_0_RC4_SP1_VERIFIER_PLONK": "0xAF58C8Feee48f9952A444cD897Fd16e99000a4E1"
 }

contracts/deployments/11155111.json

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {BaseScript} from "../../utils/Base.s.sol";
+import {SP1Verifier} from "../../../src/v3.0.0-rc4/SP1VerifierGroth16.sol";
+import {SP1VerifierGateway} from "../../../src/SP1VerifierGateway.sol";
+import {ISP1VerifierWithHash} from "../../../src/ISP1Verifier.sol";
+
+contract SP1VerifierScript is BaseScript {
+    string internal constant KEY = "V3_0_0_RC4_SP1_VERIFIER_GROTH16";
+
+    function run() external multichain(KEY) broadcaster {
+        // Read config
+        bytes32 CREATE2_SALT = readBytes32("CREATE2_SALT");
+        address SP1_VERIFIER_GATEWAY = readAddress("SP1_VERIFIER_GATEWAY");
+
+        // Deploy contract
+        address verifier = address(new SP1Verifier{salt: CREATE2_SALT}());
+
+        // Add the verifier to the gateway
+        SP1VerifierGateway gateway = SP1VerifierGateway(SP1_VERIFIER_GATEWAY);
+        gateway.addRoute(verifier);
+
+        // Write address
+        writeAddress(KEY, verifier);
+    }
+
+    function freeze() external multichain(KEY) broadcaster {
+        // Read config
+        address SP1_VERIFIER_GATEWAY = readAddress("SP1_VERIFIER_GATEWAY");
+        address SP1_VERIFIER = readAddress(KEY);
+
+        // Freeze the verifier on the gateway
+        SP1VerifierGateway gateway = SP1VerifierGateway(SP1_VERIFIER_GATEWAY);
+        bytes4 selector = bytes4(ISP1VerifierWithHash(SP1_VERIFIER).VERIFIER_HASH());
+        gateway.freezeRoute(selector);
+    }
+}

contracts/script/deploy/v3.0.0-rc4/SP1VerifierGroth16.s.sol

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import {BaseScript} from "../../utils/Base.s.sol";
+import {SP1Verifier} from "../../../src/v3.0.0-rc4/SP1VerifierPlonk.sol";
+import {SP1VerifierGateway} from "../../../src/SP1VerifierGateway.sol";
+import {ISP1VerifierWithHash} from "../../../src/ISP1Verifier.sol";
+
+contract SP1VerifierScript is BaseScript {
+    string internal constant KEY = "V3_0_0_RC4_SP1_VERIFIER_PLONK";
+
+    function run() external multichain(KEY) broadcaster {
+        // Read config
+        bytes32 CREATE2_SALT = readBytes32("CREATE2_SALT");
+        address SP1_VERIFIER_GATEWAY = readAddress("SP1_VERIFIER_GATEWAY");
+
+        // Deploy contract
+        address verifier = address(new SP1Verifier{salt: CREATE2_SALT}());
+
+        // Add the verifier to the gateway
+        SP1VerifierGateway gateway = SP1VerifierGateway(SP1_VERIFIER_GATEWAY);
+        gateway.addRoute(verifier);
+
+        // Write address
+        writeAddress(KEY, verifier);
+    }
+
+    function freeze() external multichain(KEY) broadcaster {
+        // Read config
+        address SP1_VERIFIER_GATEWAY = readAddress("SP1_VERIFIER_GATEWAY");
+        address SP1_VERIFIER = readAddress(KEY);
+
+        // Freeze the verifier on the gateway
+        SP1VerifierGateway gateway = SP1VerifierGateway(SP1_VERIFIER_GATEWAY);
+        bytes4 selector = bytes4(ISP1VerifierWithHash(SP1_VERIFIER).VERIFIER_HASH());
+        gateway.freezeRoute(selector);
+    }
+}