feat(riscv-guest): l2 execution guest rollup

.github/actions/setup-arithmetization-riscv/action.yml

@@ -44,7 +44,28 @@
           echo "${HOME}/.local/bin" >> "${GITHUB_PATH}"
           echo "${HOME}/.local/share/mise/shims" >> "${GITHUB_PATH}"
 
+      # blst + mcl are not packaged for Ubuntu; `install-native-crypto-deps` (riscv-guests/Makefile)
+      # builds them from the pinned tags once and installs into /usr/local — the SAME command a
+      # developer runs locally, and the same one .github/actions/setup-riscv-guests calls, so there
+      # is one recipe to keep in sync instead of two. The l2-execution guest's native host tools
+      # (l2-execution-wrap, l2-execution-runner) link them via the default `zig build` step this job
+      # also runs, even though the benchmark itself only consumes the freestanding riscv64 ELF.
+      - name: Cache blst + mcl builds
+        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: |
+            /usr/local/lib/libblst.a
+            /usr/local/lib/libmcl.so
+            /usr/local/include/blst.h
+            /usr/local/include/blst_aux.h
+            /usr/local/include/mcl
+          key: crypto-libs-blst-e7f90de551e8df682f3cc99067d204d8b90d27ad-mcl-0499298adcfad3bbcebf77f17700ebbe97166060
+
+      - name: Install native crypto deps (blst, mcl)
+        shell: bash
+        run: make -C riscv-guests install-native-crypto-deps
+
       - name: Install riscv64-unknown-elf toolchain
         # Install the riscv64-unknown-elf toolchain
         # Use the xpack-dev-tools/riscv-none-elf-gcc-xpack for riscv64-none-elf-gcc
         # Simlinked riscv64-none-elf-gcc to riscv64-none-elf-gcc

.github/actions/setup-riscv-guests/action.yml

@@ -20,51 +20,23 @@ runs:
         version: ${{ steps.zigversion.outputs.version }}
         dependency-hash-paths: riscv-guests/*/build.zig.zon
 
-    - name: Install apt crypto dependencies
-      shell: bash
-      run: |
-        sudo apt-get update -qq
-        sudo apt-get install -y --no-install-recommends libsecp256k1-dev libssl-dev build-essential git
-
-    # blst + mcl are not packaged for Ubuntu; build once from pinned tags and cache the artifacts.
-    # Bump the two SHAs here AND in the cache key together.
+    # blst + mcl are not packaged for Ubuntu; `install-native-crypto-deps` builds them from the
+    # pinned tags once and installs into /usr/local — the SAME command a developer runs locally.
+    # Cache /usr/local's result directly so a hit skips straight to a no-op inside that target.
     - name: Cache blst + mcl builds
-      id: crypto-cache
       uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
       with:
-        path: ~/.crypto-libs
+        path: |
+          /usr/local/lib/libblst.a
+          /usr/local/lib/libmcl.so
+          /usr/local/include/blst.h
+          /usr/local/include/blst_aux.h
+          /usr/local/include/mcl
         key: crypto-libs-blst-e7f90de551e8df682f3cc99067d204d8b90d27ad-mcl-0499298adcfad3bbcebf77f17700ebbe97166060
 
-    - name: Build blst and mcl from source
-      if: steps.crypto-cache.outputs.cache-hit != 'true'
-      shell: bash
-      run: |
-        BLST_SHA=e7f90de551e8df682f3cc99067d204d8b90d27ad   # v0.3.16
-        MCL_SHA=0499298adcfad3bbcebf77f17700ebbe97166060    # v3.06
-        STAGE="$HOME/.crypto-libs"
-        mkdir -p "$STAGE/lib" "$STAGE/include"
-
-        git clone https://github.com/supranational/blst.git "$HOME/blst-src"
-        git -C "$HOME/blst-src" checkout --detach "$BLST_SHA"
-        (cd "$HOME/blst-src" && ./build.sh)
-        cp "$HOME/blst-src/libblst.a" "$STAGE/lib/"
-        cp "$HOME/blst-src/bindings/blst.h" "$HOME/blst-src/bindings/blst_aux.h" "$STAGE/include/"
-
-        git clone https://github.com/herumi/mcl.git "$HOME/mcl-src"
-        git -C "$HOME/mcl-src" checkout --detach "$MCL_SHA"
-        make -C "$HOME/mcl-src" -j"$(nproc)"
-        cp "$HOME/mcl-src/lib/libmcl.so" "$STAGE/lib/"
-        cp -r "$HOME/mcl-src/include/mcl" "$STAGE/include/"
-
-    - name: Install blst and mcl into /usr/local
+    - name: Install native crypto deps (blst, mcl)
       shell: bash
-      run: |
-        sudo cp "$HOME/.crypto-libs/lib/libblst.a" /usr/local/lib/
-        sudo cp "$HOME/.crypto-libs/lib/libmcl.so" /usr/local/lib/
-        sudo rm -f /usr/local/lib/libmcl.a
-        sudo cp "$HOME/.crypto-libs/include/blst.h" "$HOME/.crypto-libs/include/blst_aux.h" /usr/local/include/
-        sudo cp -r "$HOME/.crypto-libs/include/mcl" /usr/local/include/
-        sudo ldconfig
+      run: make -C riscv-guests install-native-crypto-deps
 
     # Zig package fetches (zesu, zesu-zkvm, EF zkevm fixtures) land in each guest's zig-pkg/.
     - name: Cache Zig package fetches

.github/workflows/arithmetization-guest-programs-run.yml

@@ -2,14 +2,18 @@ name: Tracer guest programs run - l2-execution, Add in Zig and Blake in Rust
 
 on:
   pull_request:
-    branches:
-      - main
+    # No branches: filter — this must also run on PRs targeting stacked, non-main
+    # integration branches (e.g. feat/l2-execution-guest-rollup-v2 and its own stack of
+    # PRs), not just PRs whose base is main. The paths: filter below still scopes it.
     paths:
       - 'arithmetization/**'
       - 'riscv-guests/l2-execution/**'
       - 'riscv-guests/build_common/**'
+      - 'riscv-guests/guest-common/**'
       - 'riscv-guests/lineth-accelerators/**'
+      - 'riscv-guests/Makefile'
       - '.github/actions/setup-arithmetization-riscv/**'
+      - '.github/actions/setup-zig/**'
       - '.github/workflows/arithmetization-*.yml'
   push:
     branches:
@@ -18,8 +22,11 @@ on:
      - 'arithmetization/**'
      - 'riscv-guests/l2-execution/**'
      - 'riscv-guests/build_common/**'
+     - 'riscv-guests/guest-common/**'
      - 'riscv-guests/lineth-accelerators/**'
+     - 'riscv-guests/Makefile'
      - '.github/actions/setup-arithmetization-riscv/**'
+     - '.github/actions/setup-zig/**'
      - '.github/workflows/arithmetization-*.yml'
   workflow_call:
     inputs:

.github/workflows/arithmetization-riscv-act4-test.yml

@@ -2,18 +2,25 @@ name: Tracer riscv ACT4 test
 
 on:
   pull_request:
-    branches:
-      - main
+    # No branches: filter — this must also run on PRs targeting stacked, non-main
+    # integration branches (e.g. feat/l2-execution-guest-rollup-v2 and its own stack of
+    # PRs), not just PRs whose base is main. The paths: filter below still scopes it.
     paths:
       - 'arithmetization/**'
+      - 'riscv-guests/build_common/**'
+      - 'riscv-guests/Makefile'
       - '.github/actions/setup-arithmetization-riscv/**'
+      - '.github/actions/setup-zig/**'
       - '.github/workflows/arithmetization-*.yml'
   push:
     branches:
      - main
     paths:
      - 'arithmetization/**'
+     - 'riscv-guests/build_common/**'
+     - 'riscv-guests/Makefile'
      - '.github/actions/setup-arithmetization-riscv/**'
+     - '.github/actions/setup-zig/**'
      - '.github/workflows/arithmetization-*.yml'
   workflow_call:
     inputs:

.github/workflows/riscv-guests-host-tests.yml

@@ -1,27 +1,29 @@
 # Host-machine CI for the RISC-V guest programs (riscv-guests/):
 #   - host-tests: `make test` — the top-level orchestrator fans the native unit tests out to every
 #     guest in GUESTS (single-fixture smoke test, delegated-accel integration test, …).
-#   - spec-tests: `make spec-test` in l2-execution — the FULL EF execution-spec-tests zkevm
-#     stateless suite (~2,880 fixture files / ~16.8k blocks) run through the guest on the host.
-#     This is deliberately NOT orchestrated: the EF suite only exists for the EVM-execution guest.
+#   - reference-tests: `make reference-test` in l2-execution — the dummy-wrap-vs-fixture-truth
+#     reference-test guard (extended_vanilla_runner.zig), over the Amsterdam EF corpus.
 # Both run the guest logic natively (no RISC-V, no ZKC); running the guest through the ZKC
 # interpreter is covered separately, by its own dedicated workflow.
 name: riscv-guests host tests
 
 on:
   pull_request:
-    branches:
-      - main
+    # No branches: filter — this must also run on PRs targeting stacked, non-main
+    # integration branches (e.g. feat/l2-execution-guest-rollup-v2 and its own stack of
+    # PRs), not just PRs whose base is main. The paths: filter below still scopes it.
     paths:
       - 'riscv-guests/**'
       - '.github/actions/setup-riscv-guests/**'
+      - '.github/actions/setup-zig/**'
       - '.github/workflows/riscv-guests-host-tests.yml'
   push:
     branches:
       - main
     paths:
       - 'riscv-guests/**'
       - '.github/actions/setup-riscv-guests/**'
+      - '.github/actions/setup-zig/**'
       - '.github/workflows/riscv-guests-host-tests.yml'
   workflow_dispatch:
 
@@ -53,8 +55,8 @@ jobs:
         working-directory: riscv-guests
         timeout-minutes: 20
 
-  spec-tests:
-    name: l2-execution EF spec tests (host)
+  reference-tests:
+    name: l2-execution extended-guest reference-test guards (host)
     runs-on: gha-lfdt-lineth-ss-ubuntu-24-amd64-large
     steps:
       - name: Checkout repository
@@ -65,8 +67,8 @@ jobs:
       - name: Setup Environment
         uses: ./.github/actions/setup-riscv-guests
 
-      - name: Run full EF zkevm stateless fixture suite
-        run: make spec-test
+      - name: Run extended-guest reference-test guards
+        run: make reference-test
         working-directory: riscv-guests/l2-execution
         timeout-minutes: 30
 

.github/workflows/riscv-guests-zkc-interpreter-run.yml

@@ -17,17 +17,18 @@ name: riscv-guests zkc interpreter run
 
 on:
   pull_request:
-    branches:
-      - main
+    # No branches: filter — this must also run on PRs targeting stacked, non-main
+    # integration branches (e.g. feat/l2-execution-guest-rollup-v2 and its own stack of
+    # PRs), not just PRs whose base is main. The paths: filter below still scopes it.
     paths:
       - 'riscv-guests/**'
       - 'arithmetization/src/main/riscv/**'      # main.zkc — the interpreter (ZKC_MAIN)
       - 'arithmetization/src/main/lib/**'         # zkc stdlib used by the interpreter
-      - 'arithmetization/src/main/wrappers/**'    # linea_zkvm_accel — imported by the guest build (l2-execution/build.zig)
       - 'arithmetization/src/test/Makefile'       # elf-exec / elf-to-json / linker-script
       - 'arithmetization/src/test/scripts/**'     # elf_to_json_gen
       - 'arithmetization/Makefile'                # install-zkc / ZKC_REF
       - '.github/actions/setup-riscv-guests/**'
+      - '.github/actions/setup-zig/**'
       - '.github/workflows/riscv-guests-zkc-interpreter-run.yml'
   push:
     branches:
@@ -36,11 +37,11 @@ on:
       - 'riscv-guests/**'
       - 'arithmetization/src/main/riscv/**'
       - 'arithmetization/src/main/lib/**'
-      - 'arithmetization/src/main/wrappers/**'
       - 'arithmetization/src/test/Makefile'
       - 'arithmetization/src/test/scripts/**'
       - 'arithmetization/Makefile'
       - '.github/actions/setup-riscv-guests/**'
+      - '.github/actions/setup-zig/**'
       - '.github/workflows/riscv-guests-zkc-interpreter-run.yml'
   workflow_dispatch:
     inputs:

.husky/commit-msg

@@ -28,7 +28,7 @@ ALLOWED_SCOPES=\
 'coordinator prover prover-ray verifier-ray postman tx-exclusion-api '\
 'linea-besu contracts sdk-core sdk-ethers sdk-viem '\
 'tracer sequencer state-recovery jvm-libs blob-libs '\
-'e2e ci docker deps misc maru'
+'e2e ci docker deps misc maru riscv-guest'
 
 # Match overall structure: <type>(<scope-group>)!?: <subject>
 HEADER_RE="^(${ALLOWED_TYPES})\\(([^)]+)\\)!?: .+"

riscv-guests/.gitignore

@@ -7,3 +7,4 @@ zig-out/
 zig-pkg/
 .cache/
 *.objdump
+*/.cache/

riscv-guests/Makefile

@@ -18,7 +18,7 @@ ZIG    ?= zig
 # Mirrors the CI `zig fmt --check` invocation (riscv-guests-host-tests.yml) and scales with GUESTS.
 FMT_PATHS := build_common/build.zig $(foreach g,$(GUESTS),$(g)/build.zig $(g)/src $(g)/test)
 
-.PHONY: compile test fetch clean fmt fmt-check help
+.PHONY: compile test fetch clean fmt fmt-check help install-native-crypto-deps
 
 # Each common target fans out to every guest's own Makefile.
 compile test fetch clean:
@@ -27,6 +27,60 @@ compile test fetch clean:
 		$(MAKE) -C $$g $@ ZIG="$(ZIG)" || exit $$?; \
 	done
 
+# Native crypto libs (blst, mcl) that zesu's native host backend links — needed to build/run any
+# guest's native host tools (unit tests, the wrap/runner CLIs), never for the freestanding riscv64
+# guest ELF itself. Not packaged for Ubuntu, so built from pinned upstream tags; idempotent (skips
+# already-installed libs), so this is the SAME command whether run in CI or on a dev machine —
+# CI's job is only to cache the result, not to own a separate copy of this recipe. Bump the two SHAs
+# below when updating (keep in sync with any CI cache key that also names them).
+BLST_SHA := e7f90de551e8df682f3cc99067d204d8b90d27ad
+MCL_SHA  := 0499298adcfad3bbcebf77f17700ebbe97166060
+
+install-native-crypto-deps:
+	@set -eu; \
+	uname_s=$$(uname -s); \
+	if [ "$$uname_s" = "Darwin" ]; then \
+		command -v brew >/dev/null 2>&1 || { echo "Homebrew not found: https://brew.sh"; exit 1; }; \
+		brew install secp256k1 openssl || true; \
+		prefix=$$(brew --prefix); \
+		sudo=""; \
+	else \
+		sudo=$$(command -v sudo >/dev/null 2>&1 && echo sudo || echo ""); \
+		$$sudo apt-get update -qq; \
+		$$sudo apt-get install -y --no-install-recommends libsecp256k1-dev libssl-dev build-essential git; \
+		prefix=/usr/local; \
+	fi; \
+	if [ -f "$$prefix/lib/libblst.a" ]; then \
+		echo "blst already installed at $$prefix/lib/libblst.a"; \
+	else \
+		echo "Building blst from source ($(BLST_SHA))..."; \
+		rm -rf /tmp/blst-src; \
+		git clone https://github.com/supranational/blst.git /tmp/blst-src; \
+		git -C /tmp/blst-src checkout --detach $(BLST_SHA); \
+		(cd /tmp/blst-src && ./build.sh); \
+		$$sudo mkdir -p "$$prefix/lib" "$$prefix/include"; \
+		$$sudo cp /tmp/blst-src/libblst.a "$$prefix/lib/"; \
+		$$sudo cp /tmp/blst-src/bindings/blst.h /tmp/blst-src/bindings/blst_aux.h "$$prefix/include/"; \
+	fi; \
+	if [ -f "$$prefix/lib/libmcl.so" ] || [ -f "$$prefix/lib/libmcl.dylib" ]; then \
+		echo "mcl already installed under $$prefix/lib"; \
+	else \
+		echo "Building mcl from source ($(MCL_SHA))..."; \
+		rm -rf /tmp/mcl-src; \
+		git clone https://github.com/herumi/mcl.git /tmp/mcl-src; \
+		git -C /tmp/mcl-src checkout --detach $(MCL_SHA); \
+		$(MAKE) -C /tmp/mcl-src; \
+		$$sudo mkdir -p "$$prefix/lib" "$$prefix/include"; \
+		if [ "$$uname_s" = "Darwin" ]; then \
+			$$sudo cp /tmp/mcl-src/lib/libmcl.dylib "$$prefix/lib/" 2>/dev/null || $$sudo cp /tmp/mcl-src/lib/libmcl.a "$$prefix/lib/"; \
+		else \
+			$$sudo rm -f "$$prefix/lib/libmcl.a"; \
+			$$sudo cp /tmp/mcl-src/lib/libmcl.so "$$prefix/lib/"; \
+			$$sudo ldconfig; \
+		fi; \
+		$$sudo cp -r /tmp/mcl-src/include/mcl "$$prefix/include/"; \
+	fi
+
 # Formatting spans build_common + all guests, so it lives here (not fanned out). `fmt` rewrites in
 # place; `fmt-check` only verifies — the same gate CI runs.
 fmt:
@@ -44,4 +98,5 @@ help:
 	@echo "  make clean       # remove each guest's zig-out/ and .zig-cache/"
 	@echo "  make fmt         # format build_common + all guest sources in place (zig fmt)"
 	@echo "  make fmt-check   # verify formatting without writing (the CI gate)"
+	@echo "  make install-native-crypto-deps  # install blst/mcl for native host-tool builds"
 	@echo ""