From e585a2225630ee8e282592ca1648be2f6f3b843b Mon Sep 17 00:00:00 2001 From: r4bbit <445106+0x-r4bbit@users.noreply.github.com> Date: Tue, 26 May 2026 14:32:10 +0200 Subject: [PATCH] docs: update README and CLAUDE.md to reflect current state - Rename amm-ui to amm in the Apps table - Add "Running Apps" section with Nix flake setup and amm example - Remove hardcoded Rust toolchain version; point to rust-toolchain.toml - Replace raw cargo/clippy invocations with make targets (clippy, test, fmt, idl) - Expand program listings in overview and workspace structure to cover all five programs: token, amm, ata, stablecoin, twap_oracle - Add integration_tests and apps/amm to the workspace structure diagram --- CLAUDE.md | 38 +++++++++++++++++++++++++++++++------- README.md | 38 ++++++++++++++++++++++++++++---------- 2 files changed, 59 insertions(+), 17 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7858749..3d6ea9a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,29 +6,34 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co This repo contains essential programs for the **Logos Execution Zone (LEZ)** — a zkVM-based execution environment built on [RISC Zero](https://risczero.com/). Programs run inside the RISC Zero zkVM (`riscv32im-risc0-zkvm-elf` target) and interact with the LEZ runtime via the `nssa_core` library from `logos-execution-zone`. -Two programs are implemented: +Five programs are implemented: - **token** — Fungible and non-fungible token program (create, mint, burn, transfer, print NFTs) - **amm** — Automated market maker (constant product AMM with add/remove liquidity and swaps) +- **ata** — Associated Token Account program (derives and initializes deterministic token accounts for a given owner and token definition) +- **stablecoin** — Collateral-backed position program (open positions, repay debt, withdraw collateral) +- **twap_oracle** — TWAP oracle (provides canonical on-chain price accounts consumed by other programs) ## Build Commands ```bash # Check all workspace crates (skips expensive guest ZK builds) -RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings +make clippy # Run all tests (dev mode skips ZK proof generation) -RISC0_DEV_MODE=1 cargo test --workspace +make test # Run tests for a single package RISC0_DEV_MODE=1 cargo test -p token_program RISC0_DEV_MODE=1 cargo test -p amm_program +RISC0_DEV_MODE=1 cargo test -p ata_program +RISC0_DEV_MODE=1 cargo test -p stablecoin_program +RISC0_DEV_MODE=1 cargo test -p twap_oracle_program # Format -cargo fmt --all +make fmt # Build the guest ZK binary (requires risc0 toolchain) -cargo risczero build --manifest-path programs/token/methods/guest/Cargo.toml -cargo risczero build --manifest-path programs/amm/methods/guest/Cargo.toml +cargo risczero build --manifest-path programs//methods/guest/Cargo.toml ``` Built binaries output to: `/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/.bin` @@ -84,6 +89,25 @@ programs/ src/ # Program logic: add, remove, swap, new_definition methods/ # Host-side zkVM method embedding methods/guest/ # Guest binary (separate workspace) + ata/ + core/src/lib.rs # Data types & Instruction enum + src/ # Program logic: create, burn, transfer + methods/ # Host-side zkVM method embedding + methods/guest/ # Guest binary (separate workspace) + stablecoin/ + core/src/lib.rs # Data types & Instruction enum + src/ # Program logic: open_position, repay_debt, withdraw_collateral + methods/ # Host-side zkVM method embedding + methods/guest/ # Guest binary (separate workspace) + twap_oracle/ + core/src/lib.rs # Data types & Instruction enum + src/ # Program logic: noop (price account initialization) + methods/ # Host-side zkVM method embedding + methods/guest/ # Guest binary (separate workspace) + integration_tests/ + tests/ # End-to-end tests through the zkVM (token, amm, ata) +apps/ + amm/ # QML-based UI for the AMM program (Nix flake) ``` ## Architecture @@ -106,4 +130,4 @@ Each program follows a layered pattern: **Chained calls**: The AMM's swap and liquidity operations compose with the token program via `ChainedCall` — the AMM instructs the token program to execute transfers as part of the same atomic operation. -**Testing**: Tests call program functions directly (no zkVM overhead). Set `RISC0_DEV_MODE=1` to skip ZK proof generation when running integration tests that go through the zkVM. The Rust toolchain pinned version is **1.94.0**. +**Testing**: Tests call program functions directly (no zkVM overhead). Set `RISC0_DEV_MODE=1` to skip ZK proof generation when running integration tests that go through the zkVM. The Rust toolchain version is pinned in `rust-toolchain.toml`. diff --git a/README.md b/README.md index 35fad34..91a73ec 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,33 @@ Essential programs for the **Logos Execution Zone (LEZ)** — a zkVM-based execu | App | Description | |---|---| -| **amm-ui** | QML-based UI for interacting with the AMM program | +| **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](https://nixos.org/) flakes. Enable flakes if you haven't already: + +```bash +mkdir -p ~/.config/nix && echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf +``` + +### Example (`apps/amm`) + +```bash +cd apps/amm + +# Run the app +nix run . + +# Update pinned dependencies +nix flake update +``` ## Prerequisites -- **Rust** — install via [rustup](https://rustup.rs/). The pinned toolchain version is `1.91.1` (set in `rust-toolchain.toml`). +- **Rust** — install via [rustup](https://rustup.rs/). The pinned toolchain version is set in `rust-toolchain.toml`. - **RISC Zero toolchain** — required to build guest ZK binaries: ```bash @@ -34,10 +56,10 @@ Essential programs for the **Logos Execution Zone (LEZ)** — a zkVM-based execu ```bash # Lint the entire workspace (skips expensive guest ZK builds) -RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings +make clippy # Format check -cargo fmt --all +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 @@ -46,7 +68,7 @@ RISC0_DEV_MODE=1 cargo test -p token_program -p amm_program -p ata_program -p st RISC0_DEV_MODE=1 cargo test -p integration_tests # Run all tests -RISC0_DEV_MODE=1 cargo test --workspace +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: @@ -100,11 +122,7 @@ The IDL describes the program's instructions and can be used to interact with a **Using the `idl-gen` crate** (no external toolchain required — this is what CI uses): ```bash -cargo run -p idl-gen -- programs/token/methods/guest/src/bin/token.rs > artifacts/token-idl.json -cargo run -p idl-gen -- programs/amm/methods/guest/src/bin/amm.rs > artifacts/amm-idl.json -cargo run -p idl-gen -- programs/ata/methods/guest/src/bin/ata.rs > artifacts/ata-idl.json -cargo run -p idl-gen -- programs/stablecoin/methods/guest/src/bin/stablecoin.rs > artifacts/stablecoin-idl.json -cargo run -p idl-gen -- programs/twap_oracle/methods/guest/src/bin/twap_oracle.rs > artifacts/twap_oracle-idl.json +make idl ``` **Using the `spel` CLI** (requires the SPEL toolchain):