Skip to content

docs: update README and CLAUDE.md to reflect current state #123

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
0x-r4bbit merged 1 commit into from
May 26, 2026
Merged

docs: update README and CLAUDE.md to reflect current state #123

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 31 additions & 7 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/<program>/methods/guest/Cargo.toml
```

Built binaries output to: `<program>/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/<program>.bin`
Expand Down Expand Up @@ -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
Expand All @@ -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`.
38 changes: 28 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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):
Expand Down
Loading