lez-programs

Essential programs for the Logos Execution Zone (LEZ) — a zkVM-based execution environment built on RISC Zero. Programs run inside the RISC Zero zkVM (riscv32im-risc0-zkvm-elf target) and interact with the LEZ runtime via the nssa_core library.

Prerequisites

• Rust — install via rustup. The pinned toolchain version is 1.91.1 (set in rust-toolchain.toml).

• RISC Zero toolchain — required to build guest ZK binaries:

  cargo install cargo-risczero
  cargo risczero install

• SPEL toolchain — provides spel and wallet CLI tools. Install from logos-co/spel.

• LEZ — provides wallet CLI. Install from logos-blockchain/logos-execution-zone

Build & Test

# Lint the entire workspace (skips expensive guest ZK builds)
RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings

# Format check
cargo fmt --all

# Run unit tests for all programs (no zkVM, no ZK proof generation)
RISC0_DEV_MODE=1 cargo test -p token_program -p amm_program -p ata_program

# Run integration tests (dev mode skips ZK proof generation)
RISC0_DEV_MODE=1 cargo test -p integration_tests

# Run all tests
RISC0_DEV_MODE=1 cargo test --workspace

Integration tests live in integration_tests/tests/ and cover token, amm, and ata programs end-to-end through the zkVM using RISC0_DEV_MODE=1 to skip proof generation. Each test file corresponds to a program:

• integration_tests/tests/token.rs
• integration_tests/tests/amm.rs
• integration_tests/tests/ata.rs

Compile Guest Binaries

The guest binaries are compiled to the riscv32im-risc0-zkvm-elf target. This requires the RISC Zero toolchain.

cargo risczero build --manifest-path <PROGRAM>/methods/guest/Cargo.toml

Binaries are output to:

<PROGRAM>/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/<PROGRAM>.bin

Deployment

# Deploy a program binary to the sequencer
wallet deploy-program <path-to-binary>

# Example
wallet deploy-program token/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/token.bin
wallet deploy-program amm/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/amm.bin

To inspect the ProgramId of a built binary:

spel inspect <path-to-binary>

Interacting with Programs via spel

Generate an IDL

The IDL describes the program's instructions and can be used to interact with a deployed program.

Using the idl-gen crate (no external toolchain required — this is what CI uses):

cargo run -p idl-gen -- token/methods/guest/src/bin/token.rs > artifacts/token-idl.json
cargo run -p idl-gen -- amm/methods/guest/src/bin/amm.rs > artifacts/amm-idl.json
cargo run -p idl-gen -- ata/methods/guest/src/bin/ata.rs > artifacts/ata-idl.json

Using the spel CLI (requires the SPEL toolchain):

spel generate-idl token/methods/guest/src/bin/token.rs > artifacts/token-idl.json
spel generate-idl amm/methods/guest/src/bin/amm.rs > artifacts/amm-idl.json
spel generate-idl ata/methods/guest/src/bin/ata.rs > artifacts/ata-idl.json

Generated IDL files are committed under artifacts/. CI will fail if a program's IDL is missing or out of date.

Invoke Instructions

Use spel --idl <IDL> <INSTRUCTION> [ARGS...] to call a deployed program instruction:

spel --idl artifacts/token-idl.json <instruction> [args...]
spel --idl artifacts/amm-idl.json <instruction> [args...]