e58aa946bc
Enforce at the ATA layer that the recipient token holding is already initialized, owned by the same token program as the sender ATA, decodes to a valid `TokenHolding`, and points at the same token definition as the sender. Align the core instruction doc and guest wrapper doc with that contract, and cover the boundary with unit tests (default, foreign-owned, malformed, mismatched-definition recipients, plus the missing-owner-auth and happy paths) and end-to-end integration tests (default and mismatched-definition recipients). Without this, the downstream `token::Transfer` default-recipient `Claim::Authorized` path was reachable through ATA, so integrators had to reverse-engineer recipient semantics from token/runtime internals.
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 inrust-toolchain.toml). -
RISC Zero toolchain — required to build guest ZK binaries:
cargo install cargo-risczero cargo risczero install -
SPEL toolchain — provides
spelandwalletCLI tools. Install from logos-co/spel. -
LEZ — provides
walletCLI. 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.rsintegration_tests/tests/amm.rsintegration_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...]