Skip to content

README.md

Latest commit

 

History

History
161 lines (113 loc) · 5.79 KB

README.md

File metadata and controls

161 lines (113 loc) · 5.79 KB
Raw

Lambda VM CLI

A command-line interface for executing, proving, and verifying RISC-V ELF programs using the Lambda VM zkVM.

Installation

cargo build --release -p cli

The binary will be available at target/release/cli.

Producing an ELF

The CLI consumes RISC-V ELF binaries. The repo ships ready-to-use guest programs that you can compile with:

# RISC-V assembly tests → executor/program_artifacts/asm/*.elf
make compile-programs-asm

# Rust guest programs → executor/program_artifacts/rust/*.elf  (needs the sysroot + nightly toolchain)
make compile-programs-rust

# Benchmark programs → executor/program_artifacts/bench/*.elf  (needs the sysroot + nightly toolchain)
make compile-bench

See the root README.md for the toolchain setup.

Commands

Execute

Run a RISC-V ELF program without generating a proof. Useful for testing and debugging.

cargo run -p cli --release -- execute <PROGRAM.elf> [--private-input <FILE>] [--flamegraph <FILE>] [--cycles]
Flag Description
--private-input <FILE> Pass private input bytes to the guest (read via get_private_input()).
--flamegraph <FILE> Generate folded-stack flamegraph output. See Guest Program Flamegraphs.
--cycles Count instructions during execution and print the dynamic instruction count.

Prove

Generate a STARK proof for a RISC-V ELF program execution.

cargo run -p cli --release -- prove <PROGRAM.elf> -o proof.bin [flags]
Flag Description
-o, --output <FILE> Output path for the serialized proof bundle. Required.
--private-input <FILE> Pass private input bytes to the guest.
--blowup <N> FRI blowup factor (power of 2). Higher = fewer queries, smaller proof, slower proving. [default: 2]
--time Print total proving time.
--cycles Run one extra execution outside the timer and print the dynamic instruction count. Also supported with --continuations.
--elements Build traces and print main-trace and aux-trace field element counts. Monolithic proving only; conflicts with --continuations.
--continuations Prove as a continuation bundle split into fixed-size epochs.
--epoch-size-log2 <N> Continuation epoch size as 2^N cycles. Requires --continuations. Defaults to 20; values below 18 are rejected.

Verify

Verify a proof generated by prove.

cargo run -p cli --release -- verify <PROOF> <PROGRAM.elf> [flags]
Flag Description
--blowup <N> FRI blowup factor used during proving. Must match. [default: 2]
--time Print verification time.
--continuations Verify a continuation proof bundle produced by prove --continuations.

Returns exit code 0 on successful verification, 1 on failure. --blowup must match the value used during proving.

Count Elements

Build traces and print main-trace and aux-trace field element counts without running the proof step. Useful for sizing.

cargo run -p cli --release -- count-elements <PROGRAM.elf> [--private-input <FILE>]

Examples

# Compile the bundled assembly tests
make compile-programs-asm

# Execute a simple program
cargo run -p cli --release -- execute executor/program_artifacts/asm/add.elf

# Generate and verify a proof
cargo run -p cli --release -- prove executor/program_artifacts/asm/add.elf -o /tmp/proof.bin
cargo run -p cli --release -- verify /tmp/proof.bin executor/program_artifacts/asm/add.elf

# Generate and verify a continuation proof
cargo run -p cli --release -- prove program.elf -o /tmp/cont.bin --continuations --epoch-size-log2 20
cargo run -p cli --release -- verify /tmp/cont.bin program.elf --continuations

# Generate a continuation proof and print total dynamic instruction count
cargo run -p cli --release -- prove program.elf -o /tmp/cont.bin --continuations --cycles

# Prove with private input and print metrics
cargo run -p cli --release -- prove program.elf -o /tmp/proof.bin --private-input input.bin --time --cycles

For continuation proofs, --epoch-size-log2 is the power in 2^N cycles. Larger values reduce epoch count and fixed per-epoch overhead, but increase peak memory. As rough ethrex 10-transfer distinct-account reference points from a local sweep: 19 used about 6.9 GB peak heap, 20 about 9.5 GB, 21 about 15.8 GB, and 22 about 26.8 GB. For a new workload, use the highest value the machine can run without swapping.

Continuation proof bundles are self-contained for standalone verification. When --private-input is used, the serialized continuation proof includes the raw private input bytes so the verifier can rebuild the genesis memory commitment. Do not treat continuation proof files as confidential-input hiding artifacts.

Guest Program Flamegraphs

Generate flamegraphs showing where the guest RISC-V program spends its execution time (by instruction count).

Generate Folded Stacks

cargo run -p cli --release -- execute <PROGRAM.elf> --flamegraph folded.txt

Convert to SVG

Requires inferno or flamegraph.pl:

# Install inferno (one-time)
cargo install inferno

# Generate SVG
cat folded.txt | inferno-flamegraph > flamegraph.svg

Example

# Generate flamegraph for quicksort benchmark
cargo run -p cli --release -- execute executor/program_artifacts/bench/quicksort.elf --flamegraph /tmp/quicksort.txt
cat /tmp/quicksort.txt | inferno-flamegraph --title "quicksort" > quicksort_flamegraph.svg

Notes

  • The flamegraph shows instruction count per function, not wall-clock time
  • Function names are demangled from Rust symbols
  • Inlined functions won't appear (they're merged into their caller)
  • Syscalls using ecall are not tracked as separate function calls