feat(zkevm): SP1 platform for ZKEVM guests (eth-act zkvm-standards) (#2763)

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: tamirhemo

.github/workflows/pr.yml

@@ -11,6 +11,7 @@ on:
       - "slop/**"
       - "sp1-gpu/**"
       - "examples/**"
+      - "zkevm/**"
       - "Cargo.toml"
       - ".github/workflows/**"
       - ".github/actions/**"

.github/workflows/release.yml

@@ -332,6 +332,16 @@ jobs:
       docker-tag: ${{ needs.prepare.outputs.tag_name }}
       dry-run: ${{ inputs.dry_run }}
 
+  zkevm-sdk-release:
+    name: zkEVM SDK build and upload
+    needs: [prepare]
+    uses: ./.github/workflows/zkevm-sdk-build.yml
+    with:
+      version: ${{ needs.prepare.outputs.tag_name }}
+      release_tag: ${{ needs.prepare.outputs.tag_name }}
+      dry_run: ${{ inputs.dry_run }}
+    secrets: inherit
+
   set-latest-release:
     name: Set latest release
     runs-on: ubuntu-latest

.github/workflows/zkevm-sdk-build.yml

@@ -0,0 +1,73 @@
+name: zkevm-sdk-build
+
+# Builds the redistributable `zkevm-sdk-<version>.tar.gz` artifact.
+# Contents (host-independent — `libzkevm.a` is always built for
+# `riscv64im-succinct-zkvm-elf`):
+#
+#   zkevm-sdk-<version>/
+#   ├── libzkevm.a
+#   ├── zkvm.ld
+#   ├── include/zkvm_accelerators.h
+#   └── README.md
+#
+# Triggers:
+#   - workflow_dispatch: manual sanity-check build. Uploads the tarball
+#     as a workflow artifact (downloadable from the Actions UI).
+#   - workflow_call: invoked from `release.yml` as part of the SP1
+#     release process. With `release_tag` set, the tarball is
+#     `gh release upload`-ed to that tag instead of being kept as a
+#     workflow artifact.
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'SDK version (used in the tarball filename, e.g. v6.2.0 or 0.1.0-pre)'
+        required: true
+        default: '0.1.0-pre'
+  workflow_call:
+    inputs:
+      version:
+        description: 'SDK version (used in the tarball filename)'
+        type: string
+        required: true
+      release_tag:
+        description: 'If non-empty, gh release upload the tarball to this tag instead of saving a workflow artifact'
+        type: string
+        default: ''
+      dry_run:
+        description: 'Dry run - build but skip the release upload'
+        type: boolean
+        default: false
+
+jobs:
+  build:
+    runs-on: [runs-on, runner=8cpu-linux-x64, "run-id=${{ github.run_id }}"]
+    timeout-minutes: 60
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Setup CI
+        uses: ./.github/actions/setup
+
+      - name: Install SP1 toolchain (succinct)
+        run: cargo run -p sp1-cli --no-default-features -- prove install-toolchain
+
+      - name: Build SDK archive
+        run: make -C zkevm sdk-archive SDK_VERSION=${{ inputs.version }}
+
+      - name: Upload tarball as workflow artifact
+        if: ${{ inputs.release_tag == '' }}
+        uses: actions/upload-artifact@v4
+        with:
+          name: zkevm-sdk-${{ inputs.version }}
+          path: zkevm/zkevm-sdk-${{ inputs.version }}.tar.gz
+          retention-days: 30
+
+      - name: Upload tarball to release
+        if: ${{ inputs.release_tag != '' && inputs.dry_run != true }}
+        env:
+          GH_TOKEN: ${{ secrets.SP1_RELEASE_TOKEN }}
+        run: |
+          gh release upload "${{ inputs.release_tag }}" "zkevm/zkevm-sdk-${{ inputs.version }}.tar.gz"

.github/workflows/zkevm.yml

@@ -0,0 +1,65 @@
+name: ZKEVM
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "zkevm/**"
+      - "crates/zkvm/**"
+      - "crates/build/**"
+      - ".github/workflows/zkevm.yml"
+  pull_request:
+    branches:
+      - "**"
+    paths:
+      - "zkevm/**"
+      - "crates/zkvm/**"
+      - "crates/build/**"
+      - ".github/workflows/zkevm.yml"
+  merge_group:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  conformance:
+    name: SDK build + executor conformance
+    runs-on:
+      [
+        runs-on,
+        runner=64cpu-linux-x64,
+        spot=false,
+        disk=large,
+        "run-id=${{ github.run_id }}",
+      ]
+    env:
+      CARGO_NET_GIT_FETCH_WITH_CLI: "true"
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v6
+
+      - name: Setup CI
+        uses: ./.github/actions/setup
+        with:
+          pull_token: ${{ secrets.PRIVATE_PULL_TOKEN }}
+
+      - name: Install SP1 toolchain from repo
+        run: cargo run -p sp1-cli --no-default-features -- prove install-toolchain
+
+      # Builds libzkevm-cabi for the riscv target and assembles sdk/
+      # (libzkevm.a + zkvm.ld + headers) — the artifact C guests link.
+      - name: Build SDK staticlib
+        run: make -C zkevm sdk
+
+      # Runs the full official vector suites (geth precompile testdata,
+      # Wycheproof sample) through the accelerator C ABI inside the SP1
+      # executor — i.e. over the real syscall paths. Host-side (software
+      # fallback) coverage of the same suites runs in pr.yml via
+      # `cargo test -p libzkevm`.
+      - name: Run executor conformance
+        working-directory: zkevm/examples
+        run: cargo run --release -p conformance-script --bin conformance-execute
+        env:
+          RUST_LOG: info
+          RUST_BACKTRACE: 1

.gitignore

@@ -33,6 +33,11 @@ crates/perf/data/
 crates/prover/maximal_shapes.sh
 
 # Build Artifacts
+# zkevm/sdk is fully generated by `make -C zkevm sdk` (zkevm-build-sdk)
+zkevm/sdk/
+# C guest objects/ELFs built by the zkevm example/template Makefiles
+zkevm/examples/**/*.o
+zkevm/examples/**/*.elf
 recursion/gnark-ffi/build
 crates/prover/build
 crates/prover/data