Struct Executor

pub struct Executor<'a> {

    pub program: Arc<Program>,
    pub state: ExecutionState,
    pub memory_checkpoint: Memory<Option<MemoryRecord>>,
    pub uninitialized_memory_checkpoint: Memory<bool>,
    pub report: ExecutionReport,
    pub executor_mode: ExecutorMode,
    pub memory_accesses: MemoryAccessRecord,
    pub unconstrained: bool,
    pub print_report: bool,
    pub record_estimator: Option<Box<RecordEstimator>>,
    pub emit_global_memory_events: bool,
    pub shard_size: u32,
    pub shard_batch_size: u32,
    pub max_syscall_cycles: u32,
    pub syscall_map: HashMap<SyscallCode, Arc<dyn Syscall>>,
    pub opts: SP1CoreOpts,
    pub max_cycles: Option<u64>,
    pub record: Box<ExecutionRecord>,
    pub records: Vec<Box<ExecutionRecord>>,
    pub local_memory_access: HashMap<u32, MemoryLocalEvent>,
    pub cycle_tracker: HashMap<String, (u64, u32)>,
    pub io_buf: HashMap<u32, String>,
    pub unconstrained_state: Box<ForkState>,
    pub local_counts: LocalCounts,
    pub subproof_verifier: Option<&'a dyn SubproofVerifier>,
    pub hook_registry: HookRegistry<'a>,
    pub maximal_shapes: Option<MaximalShapes>,
    pub costs: HashMap<RiscvAirId, u64>,
    pub deferred_proof_verification: DeferredProofVerification,
    pub shape_check_frequency: u64,
    pub lde_size_check: bool,
    pub lde_size_threshold: u64,
    pub io_options: IoOptions<'a>,
    /* private fields */
}

An executor for the SP1 RISC-V zkVM.

The exeuctor is responsible for executing a user program and tracing important events which occur during execution (i.e., memory reads, alu operations, etc).

Fields

program: Arc<Program>

The program.

state: ExecutionState

The state of the execution.

memory_checkpoint: Memory<Option<MemoryRecord>>

Memory addresses that were touched in this batch of shards. Used to minimize the size of checkpoints.

uninitialized_memory_checkpoint: Memory<bool>

Memory addresses that were initialized in this batch of shards. Used to minimize the size of checkpoints. The value stored is whether or not it had a value at the beginning of the batch.

report: ExecutionReport

Report of the program execution.

executor_mode: ExecutorMode

The mode the executor is running in.

memory_accesses: MemoryAccessRecord

The memory accesses for the current cycle.

unconstrained: bool

Whether the runtime is in constrained mode or not.

In unconstrained mode, any events, clock, register, or memory changes are reset after leaving the unconstrained block. The only thing preserved is writes to the input stream.

print_report: bool

Whether we should write to the report.

record_estimator: Option<Box<RecordEstimator>>

Data used to estimate total trace area.

emit_global_memory_events: bool

Whether we should emit global memory init and finalize events. This can be enabled in Checkpoint mode and disabled in Trace mode.

shard_size: u32

The maximum size of each shard.

shard_batch_size: u32

The maximum number of shards to execute at once.

max_syscall_cycles: u32

The maximum number of cycles for a syscall.

syscall_map: HashMap<SyscallCode, Arc<dyn Syscall>>

The mapping between syscall codes and their implementations.

opts: SP1CoreOpts

The options for the runtime.

max_cycles: Option<u64>

The maximum number of cpu cycles to use for execution.

record: Box<ExecutionRecord>

The current trace of the execution that is being collected.

records: Vec<Box<ExecutionRecord>>

The collected records, split by cpu cycles.

local_memory_access: HashMap<u32, MemoryLocalEvent>

Local memory access events.

cycle_tracker: HashMap<String, (u64, u32)>

A counter for the number of cycles that have been executed in certain functions.

io_buf: HashMap<u32, String>

A buffer for stdout and stderr IO.

unconstrained_state: Box<ForkState>

The state of the runtime when in unconstrained mode.

local_counts: LocalCounts

Statistics for event counts.

subproof_verifier: Option<&'a dyn SubproofVerifier>

Verifier used to sanity check verify_sp1_proof during runtime.

hook_registry: HookRegistry<'a>

Registry of hooks, to be invoked by writing to certain file descriptors.

maximal_shapes: Option<MaximalShapes>

The maximal shapes for the program.

costs: HashMap<RiscvAirId, u64>

The costs of the program.

deferred_proof_verification: DeferredProofVerification

Skip deferred proof verification. This check is informational only, not related to circuit correctness.

shape_check_frequency: u64

The frequency to check the stopping condition.

lde_size_check: bool

Early exit if the estimate LDE size is too big.

lde_size_threshold: u64

The maximum LDE size to allow.

io_options: IoOptions<'a>

The options for the IO.

Implementations

impl<'a> Executor<'a>

pub fn new(program: Program, opts: SP1CoreOpts) -> Self

Create a new Executor from a program and options.

pub fn maybe_setup_profiler(&mut self, elf_bytes: &[u8])

WARNING: This function’s API is subject to change without a major version bump.

If the feature "profiling" is enabled, this sets up the profiler. Otherwise, it does nothing. The argument elf_bytes must describe the same program as self.program.

The profiler is configured by the following environment variables:

• TRACE_FILE: writes Gecko traces to this path. If unspecified, the profiler is disabled.
• TRACE_SAMPLE_RATE: The period between clock cycles where samples are taken. Defaults to 1.

pub fn with_context( program: Program, opts: SP1CoreOpts, context: SP1Context<'a>, ) -> Self

Create a new runtime from a program, options, and a context.

pub fn hook(&self, fd: u32, buf: &[u8]) -> Result<Vec<Vec<u8>>>

Invokes a hook with the given file descriptor fd with the data buf.

Errors

If the file descriptor is not found in the HookRegistry, this function will return an error.

pub fn hook_env<'b>(&'b self) -> HookEnv<'b, 'a>

Prepare a HookEnv for use by hooks.

pub fn recover( program: Program, state: ExecutionState, opts: SP1CoreOpts, ) -> Self

Recover runtime state from a program and existing execution state.

pub fn registers(&mut self) -> [u32; 32]

Get the current values of the registers.

pub fn register(&mut self, register: Register) -> u32

Get the current value of a register.

pub fn word(&mut self, addr: u32) -> u32

Get the current value of a word.

Assumes addr is a valid memory address, not a register.

pub fn byte(&mut self, addr: u32) -> u8

Get the current value of a byte.

Assumes addr is a valid memory address, not a register.

pub const fn timestamp(&self, position: &MemoryAccessPosition) -> u32

Get the current timestamp for a given memory access position.

pub fn shard(&self) -> u32

Get the current shard.

pub fn mr( &mut self, addr: u32, shard: u32, timestamp: u32, local_memory_access: Option<&mut HashMap<u32, MemoryLocalEvent>>, ) -> MemoryReadRecord

Read a word from memory and create an access record.

pub fn rr(&mut self, register: Register, shard: u32, timestamp: u32) -> u32

Read a register and return its value.

Assumes that the executor mode IS NOT ExecutorMode::Trace

pub fn rr_traced( &mut self, register: Register, shard: u32, timestamp: u32, local_memory_access: Option<&mut HashMap<u32, MemoryLocalEvent>>, ) -> MemoryReadRecord

Read a register and create an access record.

Assumes that self.mode IS ExecutorMode::Trace.

pub fn mw( &mut self, addr: u32, value: u32, shard: u32, timestamp: u32, local_memory_access: Option<&mut HashMap<u32, MemoryLocalEvent>>, ) -> MemoryWriteRecord

Write a word to memory and create an access record.

pub fn rw_traced( &mut self, register: Register, value: u32, shard: u32, timestamp: u32, local_memory_access: Option<&mut HashMap<u32, MemoryLocalEvent>>, ) -> MemoryWriteRecord

Write a word to a register and create an access record.

Assumes that self.mode IS ExecutorMode::Trace.

pub fn rw(&mut self, register: Register, value: u32, shard: u32, timestamp: u32)

Write a word to a register and create an access record.

Assumes that the executor mode IS NOT ExecutorMode::Trace.

pub fn mr_cpu(&mut self, addr: u32) -> u32

Read from memory, assuming that all addresses are aligned.

pub fn rr_cpu( &mut self, register: Register, position: MemoryAccessPosition, ) -> u32

Read a register.

pub fn mw_cpu(&mut self, addr: u32, value: u32)

Write to memory.

Panics

This function will panic if the address is not aligned or if the memory accesses are already initialized.

pub fn rw_cpu(&mut self, register: Register, value: u32)

Write to a register.

pub fn bump_record(&mut self)

Bump the record.

pub fn execute_record( &mut self, emit_global_memory_events: bool, ) -> Result<(Vec<Box<ExecutionRecord>>, bool), ExecutionError>

Execute up to self.shard_batch_size cycles, returning the events emitted and whether the program ended.

Errors

This function will return an error if the program execution fails.

pub fn execute_state( &mut self, emit_global_memory_events: bool, ) -> Result<(ExecutionState, PublicValues<u32, u32>, bool), ExecutionError>

Execute up to self.shard_batch_size cycles, returning the checkpoint from before execution and whether the program ended.

Errors

This function will return an error if the program execution fails.

pub fn run_fast(&mut self) -> Result<(), ExecutionError>

Executes the program without tracing and without emitting events.

Errors

This function will return an error if the program execution fails.

pub fn run_checkpoint( &mut self, emit_global_memory_events: bool, ) -> Result<(), ExecutionError>

Executes the program in checkpoint mode, without emitting the checkpoints.

Errors

This function will return an error if the program execution fails.

pub fn run(&mut self) -> Result<(), ExecutionError>

Executes the program and prints the execution report.

Errors

This function will return an error if the program execution fails.

pub fn execute(&mut self) -> Result<bool, ExecutionError>

Executes up to self.shard_batch_size cycles of the program, returning whether the program has finished.

impl Executor<'_>

pub fn write_stdin<T: Serialize>(&mut self, input: &T)

Write a serializable input to the standard input stream.

pub fn write_stdin_slice(&mut self, input: &[u8])

Write a slice of bytes to the standard input stream.

pub fn write_vecs(&mut self, inputs: &[Vec<u8>])

Write a slice of vecs to the standard input stream.

pub fn write_proof( &mut self, proof: SP1ReduceProof<BabyBearPoseidon2>, vk: StarkVerifyingKey<BabyBearPoseidon2>, )

Write a proof and verifying key to the proof stream.

pub fn read_public_values<T: DeserializeOwned>(&mut self) -> T

Read a serializable public values from the public values stream.

pub fn read_public_values_slice(&mut self, buf: &mut [u8])

Read a slice of bytes from the public values stream.

Trait Implementations

impl Read for Executor<'_>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.