README.md

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>]

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.

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 pre-pass outside the timer and print the dynamic instruction count.
--elements	Build traces and print main-trace and aux-trace field element counts.

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.

Returns exit code 0 on successful verification, 1 on failure.

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

# 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

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