ff89025ead
Move the spel-framework dependency from the 0x-r4bbit/spel fork (v0.5.0 @ 91023c9, the refactor/lez-v020-compat branch) to the released logos-co/spel tag v0.6.0. spel v0.6.0 is built against the final logos-execution-zone v0.2.0, not the v0.2.0-rc6 this repo pinned. The two must match: with rc6, the guest ELF build fails because spel's lee_core::program::ValidityWindow and the repo's own copy are distinct types the #[lez_program] macro can't unify. So this also bumps every logos-execution-zone pin (lee/lee_core aliased as nssa/nssa_core, plus clock_core) from v0.2.0-rc6 to the final v0.2.0. - 10 Cargo.toml switched to logos-co/spel tag v0.6.0 - 24 logos-execution-zone pins across 18 Cargo.toml moved rc6 -> v0.2.0 - All 7 Cargo.lock files re-resolved (root + 5 guest workspaces + benchmark); pulls in lee_core v0.1.0 (v0.2.0) as a spel transitive dep Guest ImageIDs change as a result: the ID hashes the whole guest ELF, which links the updated spel-framework and lee_core object code, even though the program sources are unchanged. Update any ImageID-derived values (deployed program IDs, PDA addresses, AMM/ATA program-id inputs) before submitting transactions.
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.
Programs
| Program | Description |
|---|---|
| token | Fungible and non-fungible token program — create definitions, mint/burn tokens, transfer, initialize accounts, print NFTs |
| amm | Constant-product AMM — add/remove liquidity and swap via chained calls to the token program |
| ata | Associated Token Account program — derives and initializes deterministic token holding accounts for a given owner and token definition |
| stablecoin | Collateral-backed position program — open collateral positions as a foundation for stablecoin debt issuance |
| twap_oracle | TWAP oracle — provides canonical on-chain price accounts consumed by other programs (e.g. stablecoin) |
Apps
| App | Description |
|---|---|
| amm | QML-based UI for interacting with the AMM program |
Running Apps
Apps live under apps/ and are standalone UI applications. Each app has its own README.md with full details.
Apps use Nix flakes. Enable flakes if you haven't already:
mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf
Example (apps/amm)
cd apps/amm
# Run the app
nix run .
# Update pinned dependencies
nix flake update
Prerequisites
-
Rust — install via rustup. The pinned toolchain version is set in
rust-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)
make clippy
# Format check
make fmt
# 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 -p stablecoin_program -p twap_oracle_program
# Run integration tests (dev mode skips ZK proof generation)
RISC0_DEV_MODE=1 cargo test -p integration_tests
# Run all tests
make test
Integration tests live in programs/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:
programs/integration_tests/tests/token.rsprograms/integration_tests/tests/amm.rsprograms/integration_tests/tests/ata.rs
stablecoin and twap_oracle are tested via their own unit tests (cargo test -p stablecoin_program -p twap_oracle_program).
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 programs/token/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/token.bin
wallet deploy-program programs/amm/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/amm.bin
wallet deploy-program programs/ata/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/ata.bin
wallet deploy-program programs/stablecoin/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/stablecoin.bin
wallet deploy-program programs/twap_oracle/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/twap_oracle.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):
make idl
Using the spel CLI (requires the SPEL toolchain):
spel generate-idl programs/token/methods/guest/src/bin/token.rs > artifacts/token-idl.json
spel generate-idl programs/amm/methods/guest/src/bin/amm.rs > artifacts/amm-idl.json
spel generate-idl programs/ata/methods/guest/src/bin/ata.rs > artifacts/ata-idl.json
spel generate-idl programs/stablecoin/methods/guest/src/bin/stablecoin.rs > artifacts/stablecoin-idl.json
spel generate-idl programs/twap_oracle/methods/guest/src/bin/twap_oracle.rs > artifacts/twap_oracle-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...]
spel --idl artifacts/ata-idl.json <instruction> [args...]
spel --idl artifacts/stablecoin-idl.json <instruction> [args...]
spel --idl artifacts/twap_oracle-idl.json <instruction> [args...]