refactor: move programs into programs and UIs into apps

CLAUDE.md

@@ -27,8 +27,8 @@ RISC0_DEV_MODE=1 cargo test -p amm_program
 cargo fmt --all
 
 # Build the guest ZK binary (requires risc0 toolchain)
-cargo risczero build --manifest-path token/methods/guest/Cargo.toml
-cargo risczero build --manifest-path amm/methods/guest/Cargo.toml
+cargo risczero build --manifest-path programs/token/methods/guest/Cargo.toml
+cargo risczero build --manifest-path programs/amm/methods/guest/Cargo.toml
 ```
 
 Built binaries output to: `<program>/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/<program>.bin`
@@ -38,17 +38,19 @@ Built binaries output to: `<program>/methods/guest/target/riscv32im-risc0-zkvm-e
 Using the `idl-gen` crate (no external toolchain required — this is what CI uses):
 
 ```bash
-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
+make idl
+```
+
+Or individually per program:
+
+```bash
+cargo run -p idl-gen -- programs/<program>/methods/guest/src/bin/<program>.rs > artifacts/<program>-idl.json
 ```
 
 Alternatively, using the `spel` CLI (requires the SPEL toolchain):
 
 ```bash
-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
+spel generate-idl programs/<program>/methods/guest/src/bin/<program>.rs > artifacts/<program>-idl.json
 ```
 
 Generated IDL files live in `artifacts/`. CI checks that every program under `*/methods/guest/src/bin/` has a corresponding `artifacts/<program>-idl.json` that matches the source.
@@ -71,16 +73,17 @@ spel inspect <path-to-binary>
 
 ```
 Cargo.toml              # Workspace root (excludes guest crates)
-token/
-  core/src/lib.rs       # Data types & Instruction enum (shared with guest)
-  src/                  # Program logic: burn, mint, transfer, initialize, new_definition, print_nft
-  methods/              # Host-side zkVM method embedding (build.rs uses risc0_build::embed_methods)
-  methods/guest/        # Guest binary (separate workspace, riscv32im target)
-amm/
-  core/src/lib.rs       # Data types, Instruction enum, PDA computation helpers
-  src/                  # Program logic: add, remove, swap, new_definition
-  methods/              # Host-side zkVM method embedding
-  methods/guest/        # Guest binary (separate workspace)
+programs/
+  token/
+    core/src/lib.rs     # Data types & Instruction enum (shared with guest)
+    src/                # Program logic: burn, mint, transfer, initialize, new_definition, print_nft
+    methods/            # Host-side zkVM method embedding (build.rs uses risc0_build::embed_methods)
+    methods/guest/      # Guest binary (separate workspace, riscv32im target)
+  amm/
+    core/src/lib.rs     # Data types, Instruction enum, PDA computation helpers
+    src/                # Program logic: add, remove, swap, new_definition
+    methods/            # Host-side zkVM method embedding
+    methods/guest/      # Guest binary (separate workspace)
 ```
 
 ## Architecture

Cargo.toml

@@ -1,45 +1,45 @@
 [workspace]
 members = [
-    "token/core",
-    "token",
-    "token/methods",
-    "amm/core",
-    "amm",
-    "amm/methods",
-    "ata/core",
-    "ata",
-    "ata/methods",
-    "twap_oracle/core",
-    "twap_oracle",
-    "twap_oracle/methods",
-    "stablecoin/core",
-    "stablecoin",
-    "stablecoin/methods",
-    "integration_tests",
+    "programs/token/core",
+    "programs/token",
+    "programs/token/methods",
+    "programs/amm/core",
+    "programs/amm",
+    "programs/amm/methods",
+    "programs/ata/core",
+    "programs/ata",
+    "programs/ata/methods",
+    "programs/twap_oracle/core",
+    "programs/twap_oracle",
+    "programs/twap_oracle/methods",
+    "programs/stablecoin/core",
+    "programs/stablecoin",
+    "programs/stablecoin/methods",
+    "programs/integration_tests",
     "tools/idl-gen",
 ]
 exclude = [
-    "token/methods/guest",
-    "amm/methods/guest",
-    "ata/methods/guest",
-    "stablecoin/methods/guest",
-    "twap_oracle/methods/guest"
+    "programs/token/methods/guest",
+    "programs/amm/methods/guest",
+    "programs/ata/methods/guest",
+    "programs/stablecoin/methods/guest",
+    "programs/twap_oracle/methods/guest"
 ]
 resolver = "2"
 
 [workspace.dependencies]
 nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", tag = "v0.2.0-rc3", features = ["host"] }
 nssa = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", tag = "v0.2.0-rc3", features = ["test-utils"] }
-token_core = { path = "token/core" }
-token_program = { path = "token" }
-amm_core = { path = "amm/core" }
-amm_program = { path = "amm" }
-ata_core = { path = "ata/core" }
-ata_program = { path = "ata" }
-twap_oracle_core = { path = "twap_oracle/core" }
-twap_oracle_program = { path = "twap_oracle" }
-stablecoin_core = { path = "stablecoin/core" }
-stablecoin_program = { path = "stablecoin" }
+token_core = { path = "programs/token/core" }
+token_program = { path = "programs/token" }
+amm_core = { path = "programs/amm/core" }
+amm_program = { path = "programs/amm" }
+ata_core = { path = "programs/ata/core" }
+ata_program = { path = "programs/ata" }
+twap_oracle_core = { path = "programs/twap_oracle/core" }
+twap_oracle_program = { path = "programs/twap_oracle" }
+stablecoin_core = { path = "programs/stablecoin/core" }
+stablecoin_program = { path = "programs/stablecoin" }
 serde = { version = "1.0", features = ["derive"] }
 borsh = { version = "1.5", features = ["derive"] }
 risc0-zkvm = { version = "=3.0.5" }

Makefile

@@ -4,7 +4,7 @@ clippy:
 	RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings
 
 clippy-guest:
-	for manifest in token/methods/guest/Cargo.toml amm/methods/guest/Cargo.toml ata/methods/guest/Cargo.toml stablecoin/methods/guest/Cargo.toml twap_oracle/methods/guest/Cargo.toml; do \
+	for manifest in programs/*/methods/guest/Cargo.toml; do \
 		cargo clippy --manifest-path "$$manifest" --all-targets -- -D warnings || exit 1; \
 	done
 
@@ -17,6 +17,7 @@ fmt:
 	cargo +nightly fmt --all
 
 idl:
-	for program in token amm ata stablecoin twap_oracle; do \
-		cargo run -p idl-gen -- "$$program/methods/guest/src/bin/$$program.rs" > "artifacts/$$program-idl.json" || exit 1; \
+	for src in programs/*/methods/guest/src/bin/*.rs; do \
+		program=$$(basename "$$src" .rs); \
+		cargo run -p idl-gen -- "$$src" > "artifacts/$${program}-idl.json" || exit 1; \
 	done

README.md

@@ -2,6 +2,22 @@
 
 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.
 
+## 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-ui** | QML-based UI for interacting with the AMM program |
+
 ## Prerequisites
 
 - **Rust** — install via [rustup](https://rustup.rs/). The pinned toolchain version is `1.91.1` (set in `rust-toolchain.toml`).
@@ -24,7 +40,7 @@ RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings
 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
+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
@@ -33,11 +49,13 @@ RISC0_DEV_MODE=1 cargo test -p integration_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 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.rs`
+- `programs/integration_tests/tests/amm.rs`
+- `programs/integration_tests/tests/ata.rs`
 
-- `integration_tests/tests/token.rs`
-- `integration_tests/tests/amm.rs`
-- `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
 
@@ -60,8 +78,11 @@ Binaries are output to:
 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
+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:
@@ -79,17 +100,21 @@ 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 -- 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
+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
 ```
 
 **Using the `spel` CLI** (requires the SPEL toolchain):
 
 ```bash
-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
+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.
@@ -101,4 +126,7 @@ Use `spel --idl <IDL> <INSTRUCTION> [ARGS...]` to call a deployed program instru
 ```bash
 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...]
 ```