Skip to content

eth-act/ere

BranchesTags

Repository files navigation

Ere logo

Ere – Unified zkVM Interface & Toolkit

Compile. Execute. Prove. Verify.
One ergonomic Rust API, multiple zero‑knowledge virtual machines.

Table of Contents

Supported Rust Versions (MSRV)

The current MSRV (minimum supported rust version) is 1.88.

Overview

This repository contains the following crates:

Architecture

The Interface

Host-side traits:

  • Compiler (from ere-compiler-core)

    Compile a guest program into an Elf.

  • zkVMProver (from ere-prover-core)

    Execute, prove and verify. A zkVM prover instance is created for an Elf produced by a Compiler. Elf specific verifying key generation happens in the constructor.

  • zkVMVerifier (from ere-verifier-core)

    zkVM verifier that is created by a succinct ProgramVk for specific Elf produced by zkVMProver. A zkVM verifier instance verifies a Proof and returns PublicValues. Pulled in standalone by verify-only consumers without the prover deps if upstream zkVM SDK provides verifier-only crate.

Guest-side trait (ere-platform-core):

  • Platform

    Provides platform-dependent methods for IO read/write and cycle tracking. It also re-exports the runtime SDK of the zkVM, guaranteed to match the host when ere-prover-{zkvm} and ere-platform-{zkvm} share the same version.

Communication between Host and Guest

Host and guest communicate through raw bytes. Serialization/deserialization can be done in any way as long as they agree with each other.

Reading Private Values from Host

The Input structure holds stdin as raw bytes. There are 2 ways to use it:

  1. Input::new().with_prefixed_stdin(data) for Platform::read_whole_input()

    The Platform trait provides a unified interface to read the whole stdin. However, some zkVMs don't provide access to the stdin length, so we require it to have a length prefix.

    The method Input::with_prefixed_stdin automatically adds a LE u32 length prefix to the stdin. In the guest, Platform::read_whole_input will return only the actual data.

    Without the length prefix, the Platform::read_whole_input will cause guest panic at runtime.

  2. Input::new().with_stdin(data) for zkVM-specific stdin APIs

    The method Input::with_stdin sets stdin without modification. Use this when you need direct access to zkVM-specific stdin APIs (e.g., sp1_zkvm::io::read, risc0_zkvm::guest::env::read), such as streaming reads or partial data consumption.

Writing Public Values to Host

Public values written in the guest program (via Platform::write_whole_output() or zkVM-specific output APIs) are returned as raw bytes to the host after zkVMProver::execute, zkVMProver::prove and zkVMProver::verify methods.

Different zkVMs handles public values in different approaches:

zkVM Size Limit Note
Airbender 32 bytes Padded to 32 bytes with zeros
OpenVM 32 bytes Padded to 32 bytes with zeros
Risc0 unlimited Hashed internally
SP1 unlimited Hashed internally
Zisk 256 bytes

Supported zkVMs

zkVM Version ISA GPU Multi GPU Cluster
Airbender 0.5.2 RV32IMA V V
OpenVM 1.4.3 RV32IMA V
Risc0 3.0.5 RV32IMA V V
SP1 6.0.1 RV64IMA V
Zisk 0.16.1 RV64IMA V V V

Examples

With SDK Installation

Install the required zkVM SDKs locally for better performance and debugging.

1. Install SDKs

Install the SP1 SDK as an example

bash scripts/sdk_installers/install_sp1_sdk.sh

2. Create Guest Program

# guest/Cargo.toml

[workspace]

[package]
name = "guest"
edition = "2024"

[dependencies]
ere-platform-sp1 = { git = "https://github.com/eth-act/ere.git" }
// guest/src/main.rs

#![no_main]

use ere_platform_sp1::{sp1_zkvm, Platform, SP1Platform};

sp1_zkvm::entrypoint!(main);

type P = SP1Platform;

pub fn main() {
    // Read serialized input and deserialize it.
    let input = P::read_whole_input();
    let n = u64::from_le_bytes(input.as_slice().try_into().unwrap());

    // Compute nth fib.
    let fib_n = fib(n);

    // Write serialized output.
    let output = [input, fib_n.to_le_bytes().to_vec()].concat();
    P::write_whole_output(&output);
}

fn fib(n: u64) -> u64 {
    let mut a = 0;
    let mut b = 1;
    for _ in 0..n {
        let c = a + b;
        a = b;
        b = c;
    }
    a
}

3. Create Host

# host/Cargo.toml

[workspace]

[package]
name = "host"
edition = "2024"

[dependencies]
ere-prover-core = { git = "https://github.com/eth-act/ere.git" }
ere-prover-sp1 = { git = "https://github.com/eth-act/ere.git" }
// host/src/main.rs

use ere_compiler_core::Compiler;
use ere_compiler_sp1::SP1RustRv64imaCustomized;
use ere_prover_core::{Input, ProverResource, zkVMProver};
use ere_prover_sp1::SP1Prover;
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let guest_directory = Path::new("path/to/guest");

    // Compile guest program with SP1 customized toolchain
    let compiler = SP1RustRv64imaCustomized;
    let elf = compiler.compile(guest_directory)?;

    // Create zkVM instance (setup/preprocessing happens here)
    let zkvm = SP1Prover::new(elf, ProverResource::Cpu)?;

    // Prepare input
    // Use `with_prefixed_stdin` when guest uses `Platform::read_whole_input()`
    let input = Input::new().with_prefixed_stdin(10u64.to_le_bytes().to_vec());
    let expected_output = [input, 55u64.to_le_bytes()].concat();

    // Execute
    let (public_values, report) = zkvm.execute(&input)?;
    assert_eq!(public_values, expected_output);
    println!("Execution cycles: {}", report.total_num_cycles);

    // Prove
    let (public_values, proof, report) = zkvm.prove(&input)?;
    assert_eq!(public_values, expected_output);
    println!("Proving time: {:?}", report.proving_time);

    // Verify
    let public_values = zkvm.verify(&proof)?;
    assert_eq!(public_values, expected_output);
    println!("Proof verified successfully!");

    Ok(())
}

Docker-Only Setup

Use Docker for zkVM operations without installing SDKs locally. Only requires Docker to be installed.

1. Create Guest Program

We use the same guest program created above.

2. Create Host

# host/Cargo.toml

[workspace]

[package]
name = "host"
edition = "2024"

[dependencies]
ere-prover-core = { git = "https://github.com/eth-act/ere.git" }
ere-dockerized = { git = "https://github.com/eth-act/ere.git" }
// host/src/main.rs

use ere_compiler_core::Compiler;
use ere_dockerized::{
    CompilerKind, DockerizedCompiler, DockerizedzkVM, DockerizedzkVMConfig, zkVMKind,
};
use ere_prover_core::{Input, ProverResource, zkVMProver};
use std::path::Path;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let guest_directory = Path::new("path/to/guest");

    // Compile guest program with SP1 customized toolchain (builds Docker images if needed)
    let compiler =
        DockerizedCompiler::new(zkVMKind::SP1, CompilerKind::RustCustomized, guest_directory)?;
    let elf = compiler.compile(guest_directory)?;

    // Create zkVM instance (builds Docker images if needed)
    // It spawns a container that runs a gRPC server handling zkVM operations
    let zkvm = DockerizedzkVM::new(
        zkVMKind::SP1,
        elf,
        ProverResource::Cpu,
        DockerizedzkVMConfig::default(),
    )?;

    // Prepare input
    // Use `with_prefixed_stdin` when guest uses `Platform::read_whole_input()`
    let input = Input::new().with_prefixed_stdin(10u64.to_le_bytes().to_vec());
    let expected_output = [input, 55u64.to_le_bytes()].concat();

    // Execute
    let (public_values, report) = zkvm.execute(&input)?;
    assert_eq!(public_values, expected_output);
    println!("Execution cycles: {}", report.total_num_cycles);

    // Prove
    let (public_values, proof, report) = zkvm.prove(&input)?;
    assert_eq!(public_values, expected_output);
    println!("Proving time: {:?}", report.proving_time);

    // Verify
    let public_values = zkvm.verify(&proof)?;
    assert_eq!(public_values, expected_output);
    println!("Proof verified successfully!");

    Ok(())
}

Environment Variables

Variable Description Default
ERE_IMAGE_REGISTRY Specifies docker image registry of the images. When specified, it will try to pull image from the registry and possibly skip building. ``
ERE_FORCE_REBUILD_DOCKER_IMAGE Force to rebuild docker images locally even they exist, it also prevents pulling image from registry. false
ERE_GPU_DEVICES Specifies which GPU devices to use when running Docker containers for GPU-enabled zkVMs. The value is passed to Docker's --gpus flag. all
ERE_DOCKER_NETWORK Specifies the Docker network being used (if any) so spawned ere-server-* containers will join that network. ``

Example usage:

# Use all GPUs (default)
ere prove ...

# Use specific GPU devices
ERE_GPU_DEVICES="device=0" ere prove ...

# Use multiple specific GPUs
ERE_GPU_DEVICES="device=0,1" ere prove ...

# Can also signal to use any available GPUs
ERE_GPU_DEVICES="4" ere prove ...

Directory Layout

ere/
├── crates/                        # Rust crates
│   ├── catalog/                   # ere-catalog
│   ├── codec/                     # ere-codec
│   ├── prover/
│   │   ├── core/                  # ere-prover-core
│   │   └── {zkvm}/                # ere-prover-{zkvm}
│   ├── platform/
│   │   ├── core/                  # ere-platform-core
│   │   └── {zkvm}/                # ere-platform-{zkvm}
│   ├── verifier/
│   │   ├── core/                  # ere-verifier-core
│   │   └── {zkvm}/                # ere-verifier-{zkvm}
│   ├── dockerized/                # ere-dockerized
│   ├── compiler/
│   │   ├── cli/                   # ere-compiler
│   │   ├── core/                  # ere-compiler-core
│   │   └── {zkvm}/                # ere-compiler-{zkvm}
│   ├── server/
│   │   ├── api/                   # ere-server-api
│   │   ├── cli/                   # ere-server
│   │   └── client/                # ere-server-client
│   ├── cluster-client/
│   │   └── zisk/                  # ere-cluster-client-zisk
│   └── util/
│       ├── build/                 # ere-util-build
│       ├── compile/               # ere-util-compile
│       ├── test/                  # ere-util-test
│       └── tokio/                 # ere-util-tokio
│
├── docker/                        # Dockerfile used by ere-dockerized
│   ├── Dockerfile.base            # ere-base
│   └── {zkvm}/
│       ├── Dockerfile.base        # ere-base-{zkvm}
│       ├── Dockerfile.compiler    # ere-compiler-{zkvm}
│       └── Dockerfile.server      # ere-server-{zkvm}
│
├── scripts/                       # SDK installation scripts per zkVM
└── tests/                         # Guest programs per zkVM for integration test

Contributing

PRs and issues are welcome!

Disclaimer

zkVMs evolve quickly; expect breaking changes. Although the API is generic, its primary target is zkEVMs, which may for example, guide the default set of precompiles.

License

Licensed under either of

at your option.

About

Unified zkVM Interface & Toolkit

Topics

ethereum zkvm

Resources

Readme

License

Apache-2.0, MIT licenses found

Licenses found

Apache-2.0
LICENSE-APACHE
MIT
LICENSE-MIT
Activity
Custom properties

Stars

82 stars

Watchers

4 watching

Forks

21 forks
Report repository

Releases 26

v0.8.1 Latest
Apr 23, 2026
+ 25 releases

Packages

 
 
 

Contributors

Languages