feat: v2 base and deferral solidity verifiers (#24)

Author: stephenh-axiom-xyz

.github/workflows/consistency-sdk.yml

@@ -0,0 +1,86 @@
+name: OpenVM SDK Consistency Check
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "OpenVM version to check, e.g. 2.0.0"
+        required: true
+
+env:
+  GENERATOR_MANIFEST: tools/generate-verifier/Cargo.toml
+  VERSION: ${{ github.event.inputs.version }}
+
+jobs:
+  consistency-check:
+    name: v${{ github.event.inputs.version }}-${{ matrix.variant }}
+    runs-on:
+      - runs-on=${{ github.run_id }}
+      - family=m7a.24xlarge
+      - volume=80gb
+    strategy:
+      fail-fast: false
+      matrix:
+        variant: [base, deferral]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: tools/generate-verifier
+
+      - name: Install solc
+        run: |
+          (hash svm 2>/dev/null || cargo install --version 0.2.23 svm-rs)
+          svm install 0.8.19
+          solc --version
+
+      - uses: foundry-rs/foundry-toolchain@v1
+        with:
+          version: v1.5.0
+
+      - name: Build generator
+        run: |
+          cargo fmt --check --manifest-path "${GENERATOR_MANIFEST}"
+          cargo build --release --locked --manifest-path "${GENERATOR_MANIFEST}" --bin generate-verifier
+
+      - name: Generate verifier
+        run: |
+          trunc_version="$(echo "${VERSION}" | cut -d '.' -f1-2)"
+          expected="${VERSION%.*}"
+          test "${trunc_version}" = "${expected}"
+          expected_dir="v${trunc_version}-${{ matrix.variant }}"
+
+          generated_dir="$(mktemp -d)"
+          tools/generate-verifier/target/release/generate-verifier \
+            --variant "${{ matrix.variant }}" \
+            --output-dir "${generated_dir}"
+
+          test -d "${generated_dir}/src/${expected_dir}"
+          test -d "src/${expected_dir}"
+
+          echo "GENERATED_DIR=${generated_dir}" >> "$GITHUB_ENV"
+          echo "VERSION_DIR=${expected_dir}" >> "$GITHUB_ENV"
+
+      - name: Compare bytecode
+        run: |
+          repo_root="$(mktemp -d)"
+          generated_root="$(mktemp -d)"
+          mkdir -p "${repo_root}/src" "${generated_root}/src"
+
+          cp foundry.toml "${repo_root}/foundry.toml"
+          cp foundry.toml "${generated_root}/foundry.toml"
+          cp -R "src/${VERSION_DIR}" "${repo_root}/src/${VERSION_DIR}"
+          cp -R "${GENERATED_DIR}/src/${VERSION_DIR}" "${generated_root}/src/${VERSION_DIR}"
+
+          forge fmt --root "${repo_root}"
+          forge fmt --root "${generated_root}"
+          forge build --force --root "${repo_root}" --config-path "${repo_root}/foundry.toml"
+          forge build --force --root "${generated_root}" --config-path "${generated_root}/foundry.toml"
+
+          diff \
+            <(jq -r '.bytecode.object | ltrimstr("0x")' "${repo_root}/out/OpenVmHalo2Verifier.sol/OpenVmHalo2Verifier.json") \
+            <(jq -r '.bytecode.object | ltrimstr("0x")' "${generated_root}/out/OpenVmHalo2Verifier.sol/OpenVmHalo2Verifier.json")

.github/workflows/consistency.yml

@@ -12,9 +12,10 @@ on:
 
 env:
   VERSION: ${{ github.event.inputs.version }}
+  SDK_VERSION: ${{ github.event.inputs.sdk-version }}
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.inputs.version }}
+  group: ${{ github.workflow }}-${{ github.event.inputs.version }}-${{ github.event.inputs.sdk-version }}
   cancel-in-progress: true
 
 run-name: "check ${{ github.event.inputs.sdk-version }} verifier is consistent with OpenVM version ${{ github.event.inputs.version }}"
@@ -41,6 +42,14 @@ jobs:
             echo "::error::TRUNC_VERSION mismatch: got '$TRUNC_VERSION' but expected '$expected'"
             exit 1
           fi
+          if [[ "$SDK_VERSION" != "$TRUNC_VERSION" && "$SDK_VERSION" != "$TRUNC_VERSION"-* ]]; then
+            echo "::error::sdk-version '$SDK_VERSION' must be '$TRUNC_VERSION' or a '$TRUNC_VERSION-*' variant"
+            exit 1
+          fi
+          if [[ "$TRUNC_VERSION" == v2.* && "$SDK_VERSION" != "$TRUNC_VERSION-base" ]]; then
+            echo "::error::cargo openvm setup --evm only generates the '$TRUNC_VERSION-base' verifier; got sdk-version '$SDK_VERSION'"
+            exit 1
+          fi
 
       - name: Install solc # svm should support arm64 linux
         run: (hash svm 2>/dev/null || cargo install --version 0.2.23 svm-rs) && svm install 0.8.19 && solc --version
@@ -65,8 +74,8 @@ jobs:
           mkdir -p "${compare_dir}/repo/src" "${compare_dir}/generated/src"
           cp foundry.toml "${compare_dir}/repo/foundry.toml"
           cp foundry.toml "${compare_dir}/generated/foundry.toml"
-          cp -R "src/${TRUNC_VERSION}" "${compare_dir}/repo/src/${TRUNC_VERSION}"
-          cp -R "${HOME}/.openvm/halo2/src/${TRUNC_VERSION}" "${compare_dir}/generated/src/${TRUNC_VERSION}"
+          cp -R "src/${SDK_VERSION}" "${compare_dir}/repo/src/${SDK_VERSION}"
+          cp -R "${HOME}/.openvm/halo2/src/${SDK_VERSION}" "${compare_dir}/generated/src/${SDK_VERSION}"
 
           forge fmt --root "${compare_dir}/repo"
           forge fmt --root "${compare_dir}/generated"

.gitignore

@@ -1,6 +1,7 @@
 # Compiler files
 cache/
 out/
+target/
 
 # Ignores development broadcast logs
 !/broadcast

README.md

@@ -2,7 +2,7 @@
 
 [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/openvm-org/openvm-solidity-sdk)
 
-This repository contains OpenVM verifier contracts generated from official release commits of the [openvm](https://github.com/openvm-org/openvm) repository using the default VM configuration via the cargo-openvm CLI tool. If you're using an advanced or custom VM configuration, you may need to generate and maintain your own verifier contracts separately.
+This repository contains OpenVM verifier contracts generated from official release commits of the [openvm](https://github.com/openvm-org/openvm) repository, either by the cargo-openvm CLI tool or the OpenVM SDK. Most releases use the default VM configuration; some releases may include additional supported variants, such as the v2.0 deferral-enabled verifier. If you're using an advanced or custom VM configuration, you may need to generate and maintain your own verifier contracts separately.
 
 The contracts are built on every _minor_ release as OpenVM guarantees verifier backward compatibility across patch releases.
 
@@ -14,12 +14,21 @@ To install `openvm-solidity-sdk` as a dependency in your forge project, run the
 forge install openvm-org/openvm-solidity-sdk
 ```
 
+## v2.0 Contract Variants
+
+The v2.0 verifier contracts are published in two variants:
+
+- `v2.0-base` is the standard verifier generated for the default OpenVM v2.0 configuration.
+- `v2.0-deferral` is generated with deferral support enabled. Use this variant when your verifier must support verifying `verify-stark` guest programs.
+
+The examples below use `v2.0-base`. If your application needs guest program `verify-stark` support, replace `v2.0-base` with `v2.0-deferral` in the import and deployment paths.
+
 ## Usage
 
 If you are using a deployed instance of the verifier contract, then you can import the interfaces in your contract directly.
 
 ```solidity
-import { IOpenVmHalo2Verifier } from "openvm-solidity-sdk/v1.7/interfaces/IOpenVmHalo2Verifier.sol";
+import { IOpenVmHalo2Verifier } from "openvm-solidity-sdk/v2.0-base/interfaces/IOpenVmHalo2Verifier.sol";
 
 contract MyContract {
     function myFunction() public view {
@@ -36,7 +45,7 @@ contract MyContract {
 If you want to deploy your own instance of the verifier contract, you can use `forge create`:
 
 ```bash
-forge create src/v1.7/OpenVmHalo2Verifier.sol:OpenVmHalo2Verifier --rpc-url $RPC --private-key $PRIVATE_KEY --broadcast
+forge create src/v2.0-base/OpenVmHalo2Verifier.sol:OpenVmHalo2Verifier --rpc-url $RPC --private-key $PRIVATE_KEY --broadcast
 ```
 
 If you want to import the verifier contract into your own repository for testing purposes, note that it is locked to Solidity version `0.8.19`. If your project uses a different version, the import may not compile. As a workaround, you can compile the contract separately and use `vm.etch()` to inject the raw bytecode into your tests.

foundry.toml

@@ -8,7 +8,7 @@ optimizer = true
 optimizer_runs = 100000
 evm_version = "paris"
 show_progress = true
-fs_permissions = [{ access = "read", path = "./test/v1.2/evm.proof"}, { access = "read", path = "./test/v1.3/evm.proof"}, { access = "read", path = "./test/v1.4/evm.proof"}, { access = "read", path = "./test/v1.5/evm.proof"}, { access = "read", path = "./test/v1.6/evm.proof"}, { access = "read", path = "./test/v1.7/evm.proof"}]
+fs_permissions = [{ access = "read", path = "./test/v1.2/evm.proof"}, { access = "read", path = "./test/v1.3/evm.proof"}, { access = "read", path = "./test/v1.4/evm.proof"}, { access = "read", path = "./test/v1.5/evm.proof"}, { access = "read", path = "./test/v1.6/evm.proof"}, { access = "read", path = "./test/v1.7/evm.proof"}, { access = "read", path = "./test/v2.0-base/evm.proof"}, { access = "read", path = "./test/v2.0-deferral/evm.proof"}]
 
 [profile.default.optimizer_details]
   constantOptimizer = false