feat: added OpenVM support

.env.example

@@ -38,31 +38,36 @@ VAST_TEMPLATE_HASH=ca595bee8049f9316883ce8dcfdcf245
 NUMBER_INSTANCES=1
 
 # Which ZK VM(s) each spawned Contemplant should serve. Comma-separated list;
-# valid values are "sp1" and "risc0". The default is both so that Scriptory's
-# fibonacci-sp1 and fibonacci-risc0 services each have a worker to assign to.
-# Magister reads this only when no [[contemplant.provers]] entries were
-# declared in magister.toml; the TOML wins when both are supplied.
-CONTEMPLANT_VMS=sp1,risc0
+# valid values are "sp1", "risc0", and "openvm". The default is all three so
+# that Scriptory's fibonacci-sp1, fibonacci-risc0, and fibonacci-openvm
+# services each have a worker to assign to. Magister reads this only when no
+# [[contemplant.provers]] entries were declared in magister.toml; the TOML
+# wins when both are supplied.
+CONTEMPLANT_VMS=sp1,risc0,openvm
 
 # Per-VM backend. Defaults to "cpu" when unset. Use "cuda" to have the spawned
 # Contemplant run with GPU acceleration. The Vast.ai template referenced by
 # VAST_TEMPLATE_HASH must satisfy SP1's sm_89+ requirement when SP1 CUDA is
 # in play.
 CONTEMPLANT_SP1_BACKEND=cuda
 CONTEMPLANT_RISC0_BACKEND=cuda
+# CONTEMPLANT_OPENVM_BACKEND=cuda
 
 # Opts the spawned RISC Zero worker into producing onchain Groth16 wrapped
 # proofs (default: false). Required for the RISC Zero fibonacci test's
 # groth16 wrap path. The released Contemplant image already ships the
 # vendored Groth16 prover assets.
 CONTEMPLANT_RISC0_GROTH16=true
 
-# Moongate CUDA prover endpoint for SP1 (default: none).
-# Only meaningful when CONTEMPLANT_SP1_BACKEND=cuda. If unset, sp1-sdk spins
-# up a dockerized moongate-server inside the Vast.ai instance. The URL must
-# terminate in `/twirp/`; the Contemplant appends it automatically when
-# missing, so either form is accepted.
-MOONGATE_ENDPOINT=http://localhost:3000/twirp/
+# Opts the spawned OpenVM worker into producing EVM (halo2-wrapped) proofs
+# (default: false). Required for the OpenVM fibonacci test's evm mode; the
+# app and stark modes work without it.
+# CONTEMPLANT_OPENVM_EVM=true
+
+# Which proof flavor the OpenVM fibonacci test requests (default: app).
+# Valid values are "app", "stark", and "evm"; evm additionally requires
+# CONTEMPLANT_OPENVM_EVM=true (or an evm_enabled prover in magister.toml).
+# OPENVM_PROOF_MODE=app
 
 # SSH public keys for debugging access (default: none).
 # Allows SSH access to Contemplant instances on port 2222 for debugging.

.env.maintainer

@@ -10,3 +10,13 @@ HIEROPHANT_IMAGE=unattended/hierophant:latest
 
 # The Magister image to use for operating this project.
 MAGISTER_IMAGE=unattended/magister:latest
+
+# Base URL for vendored dependency tarballs. The fibonacci-openvm build
+# fetches the bare git mirrors of the OpenVM repositories from here instead
+# of cloning GitHub at build time.
+VENDOR_BASE_URL=https://sigil-attic.nyc3.digitaloceanspaces.com/sigil-tarballs
+
+# The OpenVM release tag whose git mirrors are vendored. Keep in lockstep
+# with the tag pinned in src/openvm-fibonacci's Cargo.toml files; checksums
+# for the mirror tarballs live in provers/openvm/git/<tag>/.
+OPENVM_GIT_VERSION=v2.0.1

Makefile

@@ -15,16 +15,22 @@
 BUILD_IMAGE ?= unattended/petros:latest
 HIEROPHANT_IMAGE ?= unattended/hierophant:latest
 MAGISTER_IMAGE ?= unattended/magister:latest
+VENDOR_BASE_URL ?= https://sigil-attic.nyc3.digitaloceanspaces.com/sigil-tarballs
+OPENVM_GIT_VERSION ?= v2.0.1
 COMPOSE_FILE ?= docker-compose.yml
 
 # Export for docker-compose's variable substitution. HIEROPHANT_IMAGE
 # reaches the SP1 fibonacci Dockerfile's `COPY --from=${HIEROPHANT_IMAGE}`
 # step that pulls SP1 circuit artifacts out of the Hierophant image rather
 # than re-vendoring them; the same value also picks the Hierophant
-# container the docker-compose stack runs.
+# container the docker-compose stack runs. VENDOR_BASE_URL and
+# OPENVM_GIT_VERSION reach the OpenVM fibonacci Dockerfile's vendored
+# git-mirror steps.
 export BUILD_IMAGE
 export HIEROPHANT_IMAGE
 export MAGISTER_IMAGE
+export VENDOR_BASE_URL
+export OPENVM_GIT_VERSION
 
 .PHONY: init
 init:
@@ -62,14 +68,14 @@ clean:
 
 .PHONY: build
 build:
-	@echo "Building both fibonacci Docker images ..."
+	@echo "Building all three fibonacci Docker images ..."
 	docker compose --profile all build
 	@echo "Build complete."
 
-# `make test` runs the full end-to-end fibonacci suite (both SP1 and RISC
-# Zero) through docker-compose. There are no host-side unit tests to run;
-# the host's rustc + SP1 / RISC Zero toolchains generally do not match the
-# pinned versions petros ships, so a host `cargo test` would just trip
+# `make test` runs the full end-to-end fibonacci suite (SP1, RISC Zero, and
+# OpenVM) through docker-compose. There are no host-side unit tests to run;
+# the host's rustc and zkVM toolchains generally do not match the pinned
+# versions petros ships, so a host `cargo test` would just trip
 # rustc-version mismatches against fresh transitive deps. Run inside
 # petros (via the docker-compose flow) where the toolchains are pinned.
 .PHONY: test
@@ -91,12 +97,13 @@ run-m:
 	@echo "Starting Magister (and Hierophant if needed) ..."
 	docker compose up magister
 
-# `test-sp1` and `test-risc0` activate the matching docker-compose profile
-# so only the selected fibonacci service runs alongside Hierophant and
-# Magister. Both targets force `--build` so a stale fibonacci image doesn't
-# silently mask a recent edit. Use the env-level overrides documented in
-# `.env.example` (SP1_PROOF_SYSTEM, RISC0_PROOF_MODE, RISC0_WRAP_SNARK) to
-# pick which proving mode each test exercises.
+# `test-sp1`, `test-risc0`, and `test-openvm` activate the matching
+# docker-compose profile so only the selected fibonacci service runs
+# alongside Hierophant and Magister. All three targets force `--build` so a
+# stale fibonacci image doesn't silently mask a recent edit. Use the
+# env-level overrides documented in `.env.example` (SP1_PROOF_SYSTEM,
+# RISC0_PROOF_MODE, RISC0_WRAP_SNARK, OPENVM_PROOF_MODE) to pick which
+# proving mode each test exercises.
 .PHONY: test-sp1
 test-sp1:
 	@echo "Starting SP1 fibonacci test ..."
@@ -107,15 +114,21 @@ test-risc0:
 	@echo "Starting RISC Zero fibonacci test ..."
 	docker compose --profile risc0 up --build
 
+.PHONY: test-openvm
+test-openvm:
+	@echo "Starting OpenVM fibonacci test ..."
+	docker compose --profile openvm up --build
+
 .PHONY: run
 run: scriptory
 
-# `make scriptory` runs both fibonacci tests in the same compose stack so a
-# user with a dual-VM Contemplant pool sees both proof flows light up at
-# once. Use `make test-sp1` or `make test-risc0` to drive only one VM.
+# `make scriptory` runs all three fibonacci tests in the same compose stack
+# so a user with a multi-VM Contemplant pool sees every proof flow light up
+# at once. Use `make test-sp1`, `make test-risc0`, or `make test-openvm` to
+# drive only one VM.
 .PHONY: scriptory
 scriptory:
-	@echo "Starting scriptory services (SP1 + RISC Zero fibonacci) ..."
+	@echo "Starting scriptory services (SP1 + RISC Zero + OpenVM fibonacci) ..."
 	docker compose --profile all up --build
 
 .PHONY: scriptory-d
@@ -149,16 +162,17 @@ help:
 	@echo "Targets:"
 	@echo "  init            Initialize config from examples."
 	@echo "  clean           Clean volumes."
-	@echo "  build           Build both fibonacci Docker images (sp1 and risc0)."
-	@echo "  test            Alias for scriptory. Runs both end-to-end tests."
-	@echo "  docker          Build both fibonacci Docker images."
-	@echo "  ci              Build both fibonacci Docker images."
+	@echo "  build           Build all fibonacci Docker images (sp1, risc0, and openvm)."
+	@echo "  test            Alias for scriptory. Runs all three end-to-end tests."
+	@echo "  docker          Build all fibonacci Docker images."
+	@echo "  ci              Build all fibonacci Docker images."
 	@echo "  test-sp1        Run the SP1 fibonacci end-to-end test."
 	@echo "  test-risc0      Run the RISC Zero fibonacci end-to-end test."
+	@echo "  test-openvm     Run the OpenVM fibonacci end-to-end test."
 	@echo "  run             Alias for scriptory."
 	@echo "  run-h           Run just Hierophant."
 	@echo "  run-m           Run Magister (starts Hierophant if needed)."
-	@echo "  scriptory       Start all services (both VM tests) in foreground."
+	@echo "  scriptory       Start all services (all three VM tests) in foreground."
 	@echo "  scriptory-d     Start all services in background."
 	@echo "  stop            Stop all services."
 	@echo "  restart         Restart all services."

README.md

@@ -2,7 +2,7 @@
 
 > Write the vision; make it plain on tablets, so he may run who reads it.
 
-A simple solution for hosted proof production using [Hierophant](https://github.com/unattended-backpack/hierophant), [Magister](https://github.com/unattended-backpack/magister), and Contemplant. This Docker Compose setup runs a complete zkVM prover network with GPU-accelerated proof generation on Vast, demonstrated with a fibonacci example program for each of the two supported zkVMs: [SP1](https://github.com/succinctlabs/sp1) (over Hierophant's SP1 prover network gRPC) and [RISC Zero](https://risczero.com/) (over Hierophant's [Bonsai](https://dev.bonsai.xyz/)-compatible REST surface).
+A simple solution for hosted proof production using [Hierophant](https://github.com/unattended-backpack/hierophant), [Magister](https://github.com/unattended-backpack/magister), and Contemplant. This Docker Compose setup runs a complete zkVM prover network with GPU-accelerated proof generation on Vast, demonstrated with a fibonacci example program for each of the three supported zkVMs: [SP1](https://github.com/succinctlabs/sp1) (over Hierophant's SP1 prover network gRPC), [RISC Zero](https://risczero.com/) (over Hierophant's [Bonsai](https://dev.bonsai.xyz/)-compatible REST surface), and [OpenVM](https://openvm.dev/) (over Hierophant's OpenVM REST surface).
 
 ## Running
 
@@ -21,11 +21,12 @@ The `.env` file contains the minimal configuration required to run Scriptory. Yo
 The remaining values in `.env` have sensible defaults:
 - `VAST_TEMPLATE_HASH`: Template for creating Contemplant instances (default provided).
 - `NUMBER_INSTANCES`: Number of Contemplant instances to maintain (default: 1).
-- `CONTEMPLANT_VMS`: Comma-separated list of zkVMs each spawned Contemplant should serve (default: `sp1,risc0`). Declaring both produces a Contemplant that advertises both VMs to Hierophant and serves either kind of proof as it becomes idle.
+- `CONTEMPLANT_VMS`: Comma-separated list of zkVMs each spawned Contemplant should serve (default: `sp1,risc0,openvm`). Declaring several produces a Contemplant that advertises all of them to Hierophant and serves whichever kind of proof arrives as it becomes idle.
 - `CONTEMPLANT_SP1_BACKEND`: SP1 backend per Contemplant (`cpu` or `cuda`, default `cuda`).
 - `CONTEMPLANT_RISC0_BACKEND`: RISC Zero backend per Contemplant (`cpu` or `cuda`, default `cuda`).
+- `CONTEMPLANT_OPENVM_BACKEND`: OpenVM backend per Contemplant (`cpu` or `cuda`, default `cpu`).
 - `CONTEMPLANT_RISC0_GROTH16`: Whether the RISC Zero worker accepts onchain Groth16 wrap requests (`true` or `false`, default `true`). Required for the RISC Zero fibonacci test's groth16 wrap path.
-- `MOONGATE_ENDPOINT`: External moongate URL for SP1 CUDA (optional; if unset, the Contemplant spins one up locally inside the Vast.ai instance).
+- `CONTEMPLANT_OPENVM_EVM`: Whether the OpenVM worker accepts EVM (halo2-wrapped) proof requests (`true` or `false`, default `false`). Required for the OpenVM fibonacci test's evm mode.
 - `CONTEMPLANT_SSH_AUTHORIZED_KEYS`: Any SSH public keys for gaining debug access to Contemplant instances.
 
 The TOML files (`hierophant.toml` and `magister.toml`) contain detailed service configuration and work out of the box for Docker Compose deployments. Values in `.env` will override TOML settings where applicable. Review the TOML files if you need to customize advanced settings such as worker timeouts, Vast.ai query parameters, or artifact storage limits.
@@ -34,22 +35,24 @@ The TOML files (`hierophant.toml` and `magister.toml`) contain detailed service
 
 Once configuration is complete, start the services with `make scriptory` (foreground) or `make scriptory-d` (detached). This command will:
 
-1. Build both fibonacci example Docker images (SP1 and RISC Zero variants).
-2. Start Hierophant on ports 9000 (SP1 gRPC) and 9010 (HTTP/WebSocket plus the Bonsai REST surface used by the RISC Zero fibonacci test).
+1. Build all three fibonacci example Docker images (SP1, RISC Zero, and OpenVM variants).
+2. Start Hierophant on ports 9000 (SP1 gRPC) and 9010 (HTTP/WebSocket plus the Bonsai REST surface used by the RISC Zero fibonacci test and the OpenVM REST surface used by the OpenVM fibonacci test).
 3. Start Magister on port 8555, which will:
    - Connect to Hierophant.
-   - Create and maintain the configured number of Contemplant instances on Vast, each declaring both SP1 and RISC Zero capability per the `[[contemplant.provers]]` array in `magister.toml`.
+   - Create and maintain the configured number of Contemplant instances on Vast, each declaring SP1, RISC Zero, and OpenVM capability per the `[[contemplant.provers]]` array in `magister.toml`.
    - Monitor instances and replace any that fail.
 4. Run the SP1 fibonacci example program against Hierophant's SP1 gRPC.
 5. Run the RISC Zero fibonacci example program against Hierophant's Bonsai REST surface.
+6. Run the OpenVM fibonacci example program against Hierophant's OpenVM REST surface.
 
-Each fibonacci example submits a proof request, waits for a Contemplant to pick up the work, retrieves the completed proof, and verifies it. Logs from all services interleave on the foreground command so you can watch both proof flows progress simultaneously.
+Each fibonacci example submits a proof request, waits for a Contemplant to pick up the work, retrieves the completed proof, and verifies it. Logs from all services interleave on the foreground command so you can watch every proof flow progress simultaneously.
 
-To exercise only one zkVM at a time, use `make test-sp1` or `make test-risc0` instead. Both forms accept the following overrides via `.env`:
+To exercise only one zkVM at a time, use `make test-sp1`, `make test-risc0`, or `make test-openvm` instead. All forms accept the following overrides via `.env`:
 
 - `SP1_PROOF_SYSTEM` selects which SP1 proving mode the test requests: `core`, `compressed`, `plonk` (default), or `groth16`.
 - `RISC0_PROOF_MODE` selects the RISC Zero session mode: `composite` (default), `succinct`, or `groth16`.
 - `RISC0_WRAP_SNARK=true` flips on the canonical Bonsai composite-then-Groth16-wrap flow. Requires Contemplants spawned with `CONTEMPLANT_RISC0_GROTH16=true` (the default).
+- `OPENVM_PROOF_MODE` selects the OpenVM proof flavor: `app` (default), `stark`, or `evm`. The evm mode requires Contemplants spawned with `CONTEMPLANT_OPENVM_EVM=true` (or an `evm_enabled = true` prover entry in `magister.toml`).
 
 ### Managing Services
 
@@ -61,9 +64,9 @@ Additional targets are available for building images, running tests, and cleanin
 
 Scriptory orchestrates three core components:
 
-- **Hierophant**: The prover network coordinator that manages proof requests, worker registration, and artifact storage. SP1 clients submit proof requests via the gRPC surface on port 9000 (`sp1-sdk`-compatible); RISC Zero clients submit via the Bonsai-compatible REST surface at `/bonsai/` on port 9010 (`bonsai-sdk`-compatible).
+- **Hierophant**: The prover network coordinator that manages proof requests, worker registration, and artifact storage. SP1 clients submit proof requests via the gRPC surface on port 9000 (`sp1-sdk`-compatible); RISC Zero clients submit via the Bonsai-compatible REST surface at `/bonsai/` on port 9010 (`bonsai-sdk`-compatible); OpenVM clients submit via the OpenVM REST surface at `/openvm/` on port 9010.
 - **Magister**: The Vast instance manager that automatically creates, monitors, and maintains Contemplant workers on GPU instances. Magister ensures the configured number of instances are always available, and tells each spawned Contemplant which zkVM(s) to serve via the `[[contemplant.provers]]` array in `magister.toml`.
-- **Contemplant**: GPU-accelerated proof generation workers that connect to Hierophant via WebSocket, receive proof tasks, and generate zkVM proofs using CUDA acceleration. A single Contemplant can serve both SP1 and RISC Zero proof requests; it processes one proof at a time regardless of how many VMs it advertises.
+- **Contemplant**: GPU-accelerated proof generation workers that connect to Hierophant via WebSocket, receive proof tasks, and generate zkVM proofs using CUDA acceleration. A single Contemplant can serve SP1, RISC Zero, and OpenVM proof requests; it processes one proof at a time regardless of how many VMs it advertises.
 
 ## Requirements