Struct ExecutorEnvBuilder

pub struct ExecutorEnvBuilder<'a> { /* private fields */ }

Available on crate feature client and non-target_os="zkvm" only.

A builder pattern used to construct an ExecutorEnv.

Implementations

impl<'a> ExecutorEnvBuilder<'a>

pub fn build(&mut self) -> Result<ExecutorEnv<'a>>

Finalize this builder to construct an ExecutorEnv.

Example

use risc0_zkvm::ExecutorEnv;

let env = ExecutorEnv::builder().build().unwrap();

After calling build, the ExecutorEnvBuilder will be reset to default.

pub fn segment_limit_po2(&mut self, limit: u32) -> &mut Self

Set a segment limit, specified in powers of 2 cycles.

Lowering this value will reduce the memory consumption of the prover. Memory consumption is roughly linear with the segment size, so lowering this value by 1 will cut memory consumpton by about half.

The default value is chosen to be performant on commonly used hardware. Tuning this value, either up or down, may result in better proving performance.

Given value must be between risc0_zkp::MIN_CYCLES_PO2 and risc0_zkp::MAX_CYCLES_PO2 (inclusive).

pub fn keccak_max_po2(&mut self, limit: u32) -> Result<&mut Self>

Set a segment limit for keccak proofs, specified in powers of 2 cycles.

Lowering this value will reduce the memory consumption of the prover. Memory consumption is roughly linear with the segment size, so lowering this value by 1 will cut memory consumpton by about half.

The default value is chosen to be performant on commonly used hardware. Tuning this value, either up or down, may result in better proving performance.

Given value must be within risc0_circuit_keccak::KECCAK_PO2_RANGE

pub fn session_limit(&mut self, limit: Option<u64>) -> &mut Self

Set a session limit, specified in number of cycles.

Example

use risc0_zkvm::ExecutorEnv;

let env = ExecutorEnv::builder()
    .session_limit(Some(32 * 1024 * 1024)) // 32M cycles
    .build()
    .unwrap();

pub fn env_vars(&mut self, vars: HashMap<String, String>) -> &mut Self

Add environment variables to the guest environment.

Example

use std::collections::HashMap;
use risc0_zkvm::ExecutorEnv;

let mut vars = HashMap::new();
vars.insert("VAR1".to_string(), "SOME_VALUE".to_string());
vars.insert("VAR2".to_string(), "SOME_VALUE".to_string());

let env = ExecutorEnv::builder()
    .env_vars(vars)
    .build()
    .unwrap();

pub fn args(&mut self, args: &[String]) -> &mut Self

Add an argument array to the guest environment.

Example

let env = ExecutorEnv::builder()
    .args(&["grep".to_string(), "-c".to_string(), "foo".to_string(), "-".to_string()])
    .build()
    .unwrap();

pub fn env_var(&mut self, name: &str, val: &str) -> &mut Self

Add an environment variable to the guest environment.

Example

use risc0_zkvm::ExecutorEnv;

let env = ExecutorEnv::builder()
    .env_var("VAR1", "SOME_VALUE")
    .build()
    .unwrap();

pub fn write<T: Serialize>(&mut self, data: &T) -> Result<&mut Self>

Write input data to the zkVM guest stdin.

This function will serialize data using a zkVM-optimized codec that can be deserialized in the guest with a corresponding env::read with the same data type.

Example

use risc0_zkvm::ExecutorEnv;
use serde::Serialize;

#[derive(Serialize)]
struct Input {
    a: u32,
    b: u32,
}

let input1 = Input{ a: 1, b: 2 };
let input2 = Input{ a: 3, b: 4 };
let env = ExecutorEnv::builder()
    .write(&input1).unwrap()
    .write(&input2).unwrap()
    .build()
    .unwrap();

pub fn write_slice<T: Pod>(&mut self, slice: &[T]) -> &mut Self

Write input data to the zkVM guest stdin.

This function writes a slice directly to the underlying buffer. A corresponding env::read_slice can be used within the guest to read the data.

Example

use risc0_zkvm::ExecutorEnv;

let slice1 = [0, 1, 2, 3];
let slice2 = [3, 2, 1, 0];
let env = ExecutorEnv::builder()
    .write_slice(&slice1)
    .write_slice(&slice2)
    .build()
    .unwrap();

pub fn write_frame(&mut self, payload: &[u8]) -> &mut Self

Available on crate feature unstable only.

Write a frame to the zkVM guest via stdin.

A frame contains a length header along with the payload. Reading a frame can be more efficient than deserializing a message on-demand. On-demand deserialization can cause many syscalls, whereas a frame will only have two.

Availability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn stdin(&mut self, reader: impl Read + 'a) -> &mut Self

Add a posix-style standard input.

pub fn stdout(&mut self, writer: impl Write + 'a) -> &mut Self

Add a posix-style standard output.

pub fn stderr(&mut self, writer: impl Write + 'a) -> &mut Self

Add a posix-style standard error.

pub fn read_fd(&mut self, fd: u32, reader: impl BufRead + 'a) -> &mut Self

Add a posix-style file descriptor for reading.

pub fn write_fd(&mut self, fd: u32, writer: impl Write + 'a) -> &mut Self

Add a posix-style file descriptor for writing.

pub fn slice_io( &mut self, channel: &str, handler: impl SliceIo + 'a, ) -> &mut Self

Add a handler for simple I/O handling.

pub fn io_callback<C: AsRef<str>>( &mut self, channel: C, callback: impl Fn(Bytes) -> Result<Bytes> + 'a, ) -> &mut Self

Add a handler for simple I/O handling.

pub fn add_assumption( &mut self, assumption: impl Into<AssumptionReceipt>, ) -> &mut Self

Add an AssumptionReceipt to the ExecutorEnv, for use in composition.

During execution, when the guest calls env::verify or env::verify_integrity, this collection will be searched for an AssumptionReceipt that corresponds the verification call.

Either a crate::Receipt or a crate::ReceiptClaim can be provided. If a crate::Receipt is provided, then an AssumptionReceipt::Proven will be added to the ExecutorEnv and the crate::Receipt generated by proving will be unconditional.

pub fn trace_callback(&mut self, callback: impl TraceCallback + 'a) -> &mut Self

Add a callback handler for raw trace messages.

pub fn segment_path<P: AsRef<Path>>(&mut self, path: P) -> &mut Self

Set the path where segments will be stored.

pub fn enable_profiler<P: AsRef<Path>>(&mut self, path: P) -> &mut Self

Enable the profiler and output results to the specified path.

pub fn input_digest(&mut self, digest: Digest) -> &mut Self

Set the input digest.

pub fn coprocessor_callback( &mut self, callback: impl CoprocessorCallback + 'a, ) -> &mut Self

Available on crate feature unstable only.

Add a callback for coprocessor requests.

Availability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

pub fn coprocessor_callback_ref( &mut self, callback: Rc<RefCell<dyn CoprocessorCallback + 'a>>, ) -> &mut Self

Available on crate feature unstable only.

Add a callback for coprocessor requests.

Availability

This API is marked as unstable and is only available when the unstable crate feature is enabled. This comes with no stability guarantees, and could be changed or removed at any time.

Trait Implementations

impl<'a> Default for ExecutorEnvBuilder<'a>

fn default() -> ExecutorEnvBuilder<'a>

Returns the “default value” for a type.