chore: initial repository setup for programs

.claude/skills/deploy-program/skill.md

@@ -0,0 +1,18 @@
+---
+description: Deploy a LEZ program to the sequencer. Use when the user asks to deploy, ship, or publish a program (e.g. "deploy the token program", "ship amm to the sequencer").
+---
+
+# deploy-program
+
+Deploying a LEZ program is always a two-step process: compile first, then deploy. Never deploy
+without rebuilding first — a stale binary deploys silently but won't reflect recent code changes.
+
+The program name corresponds to a top-level workspace directory. If none is specified, discover
+available programs by looking for `<name>/methods/guest/Cargo.toml` and ask the user to pick one.
+
+After deploying, confirm success by inspecting the binary and reporting the ProgramId to the user.
+
+## Gotchas
+
+- **Docker must be running.** `cargo risczero build` cross-compiles via Docker. Fail fast if not.
+- **The output binary path follows a fixed convention** — derive it from the program name, don't guess.

.claude/skills/program-id/skill.md

@@ -0,0 +1,17 @@
+---
+description: Get the program ID (Image ID) for a LEZ program. Use when the user asks for a program's ID, image ID, or program address (e.g. "what's the token program id", "get the amm program id").
+---
+
+# program-id
+
+The program ID is the RISC Zero Image ID derived from the compiled guest ELF binary.
+
+The program name corresponds to a top-level workspace directory. If none is specified, discover
+available programs by looking for `<name>/methods/guest/Cargo.toml` and ask the user to pick one.
+
+## Steps
+
+1. **Check if the binary exists** at `<name>/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/<name>.bin`.
+2. **If missing, build it first** using `cargo risczero build --manifest-path <name>/methods/guest/Cargo.toml`.
+   - Docker must be running for this step. Fail fast if not.
+3. **Inspect the binary** with `lez-cli inspect <path-to-binary>` and report the program ID to the user.

.github/workflows/ci.yml

@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+  RISC0_DEV_MODE: 1
+
+jobs:
+  check:
+    name: Check & Test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: "1.91.1"
+          components: clippy, rustfmt
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-cargo-
+
+      - name: Format check
+        run: cargo fmt --all -- --check
+
+      - name: Clippy (workspace, skip guest builds)
+        run: RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings
+
+      - name: Tests (dev mode, skip ZK proof generation)
+        run: cargo test --workspace
+        env:
+          RISC0_DEV_MODE: 1

.gitignore

@@ -0,0 +1,4 @@
+target/
+token/methods/guest/target/
+amm/methods/guest/target/
+*.bin

CLAUDE.md

@@ -0,0 +1,93 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+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:
+- **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)
+
+## Build Commands
+
+```bash
+# Check all workspace crates (skips expensive guest ZK builds)
+RISC0_SKIP_BUILD=1 cargo clippy --workspace --all-targets -- -D warnings
+
+# Run all tests (dev mode skips ZK proof generation)
+RISC0_DEV_MODE=1 cargo test --workspace
+
+# Run tests for a single package
+RISC0_DEV_MODE=1 cargo test -p token_program
+RISC0_DEV_MODE=1 cargo test -p amm_program
+
+# Format
+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
+```
+
+Built binaries output to: `<program>/methods/guest/target/riscv32im-risc0-zkvm-elf/docker/<program>.bin`
+
+## IDL Generation
+
+```bash
+lez-cli generate-idl token/methods/guest/src/bin/token.rs > token/token-idl.json
+lez-cli generate-idl amm/methods/guest/src/bin/amm.rs > amm/amm-idl.json
+```
+
+## Deployment
+
+`wallet` and `lez-cli` are CLI tools that ship with the [SPEL](https://github.com/logos-co/spel.git) toolchain. `wallet` requires `NSSA_WALLET_HOME_DIR` to point to a directory containing the wallet config.
+
+**Note:** `lez-cli` and `wallet` may use different versions of the wallet package. If `lez-cli --idl <IDL> <PROGRAM_FUNCTION> ...` fails, ensure `seq_poll_timeout_millis` is set in the wallet config at `~/.nssa/wallet`.
+
+```bash
+# Deploy a program binary to the sequencer
+wallet deploy-program <path-to-binary>
+
+# Inspect the ProgramId of a built binary
+lez-cli inspect <path-to-binary>
+```
+
+## Workspace Structure
+
+```
+Cargo.toml              # Workspace root (excludes guest crates)
+token/
+  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/
+  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
+
+Each program follows a layered pattern:
+
+1. **`*_core` crate** — shared types (Instructions, account data structs) serialized with Borsh for on-chain storage, serde for instruction passing. Also contains PDA seed computation (amm_core).
+
+2. **Program crate** — pure functions that take `AccountWithMetadata` inputs and return `Vec<AccountPostState>` (and `Vec<ChainedCall>` for AMM). No I/O or state — all state transitions are deterministic and testable without the zkVM.
+
+3. **`methods/guest`** — the guest binary wired to the LEZ framework via `lez-framework` using the `#[lez_program]` and `#[instruction]` proc macros. This is what gets compiled to RISC-V and ZK-proven.
+
+4. **`methods`** — host crate that embeds the guest ELF for use in tests and deployment.
+
+## Key Patterns
+
+**Account data serialization**: On-chain account data uses Borsh (`BorshSerialize`/`BorshDeserialize`). Instructions use serde JSON. Both implement `TryFrom<&Data>` and `From<&T> for Data` for conversion.
+
+**Program-Derived Addresses (PDAs)**: The AMM uses SHA-256-based PDAs (`compute_pool_pda`, `compute_vault_pda`, `compute_liquidity_token_pda` in `amm_core`) to derive deterministic account addresses for pools, vaults, and liquidity tokens.
+
+**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.91.1**.

Cargo.toml

@@ -0,0 +1,30 @@
+[workspace]
+members = [
+    "token/token_core",
+    "token",
+    "token/methods",
+    "amm/amm_core",
+    "amm",
+    "amm/methods",
+]
+exclude = [
+    "token/methods/guest",
+    "amm/methods/guest",
+]
+resolver = "2"
+
+[workspace.dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", features = ["host"] }
+nssa = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", features = ["test-utils"] }
+token_core = { path = "token/token_core" }
+token_program = { path = "token" }
+amm_core = { path = "amm/amm_core" }
+amm_program = { path = "amm" }
+serde = { version = "1.0", features = ["derive"] }
+borsh = { version = "1.0", features = ["derive"] }
+risc0-zkvm = { version = "=3.0.5" }
+serde_json = "1.0"
+tokio = { version = "1.28.2", features = ["net", "rt-multi-thread", "sync", "macros"] }
+
+[patch."https://github.com/logos-blockchain/lssa.git"]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git" }

README.md

@@ -1,2 +1,81 @@
 # lez-programs
-Essential programs for the Logos Execution Zone built by Logos.
+
+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.
+
+## Prerequisites
+
+- **Rust** — install via [rustup](https://rustup.rs/). The pinned toolchain version is `1.91.1` (set in `rust-toolchain.toml`).
+- **RISC Zero toolchain** — required to build guest ZK binaries:
+
+  ```bash
+  cargo install cargo-risczero
+  cargo risczero install
+  ```
+- **SPEL toolchain** — provides `lez-cli` tools. Install from [logos-co/spel](https://github.com/logos-co/spel).
+- **LEZ** — provides `wallet` CLI. Install from [logos-blockchain/logos-execution-zone](https://github.com/logos-blockchain/logos-execution-zone)
+
+## Build & Test
+
+```bash
+# 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 all tests (dev mode skips ZK proof generation)
+RISC0_DEV_MODE=1 cargo test --workspace
+
+```
+
+## Compile Guest Binaries
+
+The guest binaries are compiled to the `riscv32im-risc0-zkvm-elf` target. This requires the RISC Zero toolchain.
+
+```bash
+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
+
+```bash
+# 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:
+
+```bash
+lez-cli inspect <path-to-binary>
+```
+
+## Interacting with Programs via `lez-cli`
+
+### Generate an IDL
+
+The IDL describes the program's instructions and can be used to interact with a deployed program.
+
+```bash
+# Example
+lez-cli generate-idl token/methods/guest/src/bin/token.rs > token/token-idl.json
+lez-cli generate-idl amm/methods/guest/src/bin/amm.rs > amm/amm-idl.json
+```
+
+### Invoke Instructions
+
+Use `lez-cli --idl <IDL> <INSTRUCTION> [ARGS...]` to call a deployed program instruction:
+
+```bash
+lez-cli --idl token/token-idl.json <instruction> [args...]
+lez-cli --idl amm/amm-idl.json <instruction> [args...]
+```

amm/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "amm_program"
+version = "0.1.0"
+edition = "2021"
+
+[features]
+nssa = ["dep:nssa"]
+
+[dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", features = ["host"] }
+nssa = { workspace = true, optional = true }
+amm_core = { path = "amm_core" }
+token_core = { path = "../token/token_core" }

amm/amm-idl.json

@@ -0,0 +1,239 @@
+{
+  "version": "0.1.0",
+  "name": "amm",
+  "instructions": [
+    {
+      "name": "new_definition",
+      "accounts": [
+        {
+          "name": "pool",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "pool_definition_lp",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_lp",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "token_a_amount",
+          "type": "u128"
+        },
+        {
+          "name": "token_b_amount",
+          "type": "u128"
+        },
+        {
+          "name": "amm_program_id",
+          "type": "program_id"
+        }
+      ]
+    },
+    {
+      "name": "add_liquidity",
+      "accounts": [
+        {
+          "name": "pool",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "pool_definition_lp",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_lp",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "min_amount_liquidity",
+          "type": "u128"
+        },
+        {
+          "name": "max_amount_to_add_token_a",
+          "type": "u128"
+        },
+        {
+          "name": "max_amount_to_add_token_b",
+          "type": "u128"
+        }
+      ]
+    },
+    {
+      "name": "remove_liquidity",
+      "accounts": [
+        {
+          "name": "pool",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "pool_definition_lp",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_lp",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "remove_liquidity_amount",
+          "type": "u128"
+        },
+        {
+          "name": "min_amount_to_remove_token_a",
+          "type": "u128"
+        },
+        {
+          "name": "min_amount_to_remove_token_b",
+          "type": "u128"
+        }
+      ]
+    },
+    {
+      "name": "swap",
+      "accounts": [
+        {
+          "name": "pool",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "vault_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_a",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_b",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "swap_amount_in",
+          "type": "u128"
+        },
+        {
+          "name": "min_amount_out",
+          "type": "u128"
+        },
+        {
+          "name": "token_definition_id_in",
+          "type": "account_id"
+        }
+      ]
+    }
+  ],
+  "instruction_type": "amm_core::Instruction"
+}

amm/amm_core/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "amm_core"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", features = ["host"] }
+borsh = { version = "1.5", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"] }
+risc0-zkvm = { version = "=3.0.5", default-features = false }

amm/amm_core/src/lib.rs

@@ -0,0 +1,197 @@
+//! This crate contains core data structures and utilities for the AMM Program.
+
+use borsh::{BorshDeserialize, BorshSerialize};
+use nssa_core::{
+    account::{AccountId, Data},
+    program::{PdaSeed, ProgramId},
+};
+use serde::{Deserialize, Serialize};
+
+/// AMM Program Instruction.
+#[derive(Serialize, Deserialize)]
+pub enum Instruction {
+    /// Initializes a new Pool (or re-initializes an inactive Pool).
+    ///
+    /// Required accounts:
+    /// - AMM Pool
+    /// - Vault Holding Account for Token A
+    /// - Vault Holding Account for Token B
+    /// - Pool Liquidity Token Definition
+    /// - User Holding Account for Token A (authorized)
+    /// - User Holding Account for Token B (authorized)
+    /// - User Holding Account for Pool Liquidity
+    NewDefinition {
+        token_a_amount: u128,
+        token_b_amount: u128,
+        amm_program_id: ProgramId,
+    },
+
+    /// Adds liquidity to the Pool
+    ///
+    /// Required accounts:
+    /// - AMM Pool (initialized)
+    /// - Vault Holding Account for Token A (initialized)
+    /// - Vault Holding Account for Token B (initialized)
+    /// - Pool Liquidity Token Definition (initialized)
+    /// - User Holding Account for Token A (authorized)
+    /// - User Holding Account for Token B (authorized)
+    /// - User Holding Account for Pool Liquidity
+    AddLiquidity {
+        min_amount_liquidity: u128,
+        max_amount_to_add_token_a: u128,
+        max_amount_to_add_token_b: u128,
+    },
+
+    /// Removes liquidity from the Pool
+    ///
+    /// Required accounts:
+    /// - AMM Pool (initialized)
+    /// - Vault Holding Account for Token A (initialized)
+    /// - Vault Holding Account for Token B (initialized)
+    /// - Pool Liquidity Token Definition (initialized)
+    /// - User Holding Account for Token A (initialized)
+    /// - User Holding Account for Token B (initialized)
+    /// - User Holding Account for Pool Liquidity (authorized)
+    RemoveLiquidity {
+        remove_liquidity_amount: u128,
+        min_amount_to_remove_token_a: u128,
+        min_amount_to_remove_token_b: u128,
+    },
+
+    /// Swap some quantity of Tokens (either Token A or Token B)
+    /// while maintaining the Pool constant product.
+    ///
+    /// Required accounts:
+    /// - AMM Pool (initialized)
+    /// - Vault Holding Account for Token A (initialized)
+    /// - Vault Holding Account for Token B (initialized)
+    /// - User Holding Account for Token A
+    /// - User Holding Account for Token B Either User Holding Account for Token A or Token B is
+    ///   authorized.
+    Swap {
+        swap_amount_in: u128,
+        min_amount_out: u128,
+        token_definition_id_in: AccountId,
+    },
+}
+
+#[derive(Clone, Default, Serialize, Deserialize, BorshSerialize, BorshDeserialize)]
+pub struct PoolDefinition {
+    pub definition_token_a_id: AccountId,
+    pub definition_token_b_id: AccountId,
+    pub vault_a_id: AccountId,
+    pub vault_b_id: AccountId,
+    pub liquidity_pool_id: AccountId,
+    pub liquidity_pool_supply: u128,
+    pub reserve_a: u128,
+    pub reserve_b: u128,
+    /// Fees are currently not used
+    pub fees: u128,
+    /// A pool becomes inactive (active = false)
+    /// once all of its liquidity has been removed (e.g., reserves are emptied and
+    /// liquidity_pool_supply = 0)
+    pub active: bool,
+}
+
+impl TryFrom<&Data> for PoolDefinition {
+    type Error = std::io::Error;
+
+    fn try_from(data: &Data) -> Result<Self, Self::Error> {
+        PoolDefinition::try_from_slice(data.as_ref())
+    }
+}
+
+impl From<&PoolDefinition> for Data {
+    fn from(definition: &PoolDefinition) -> Self {
+        // Using size_of_val as size hint for Vec allocation
+        let mut data = Vec::with_capacity(std::mem::size_of_val(definition));
+
+        BorshSerialize::serialize(definition, &mut data)
+            .expect("Serialization to Vec should not fail");
+
+        Data::try_from(data).expect("Token definition encoded data should fit into Data")
+    }
+}
+
+pub fn compute_pool_pda(
+    amm_program_id: ProgramId,
+    definition_token_a_id: AccountId,
+    definition_token_b_id: AccountId,
+) -> AccountId {
+    AccountId::from((
+        &amm_program_id,
+        &compute_pool_pda_seed(definition_token_a_id, definition_token_b_id),
+    ))
+}
+
+pub fn compute_pool_pda_seed(
+    definition_token_a_id: AccountId,
+    definition_token_b_id: AccountId,
+) -> PdaSeed {
+    use risc0_zkvm::sha::{Impl, Sha256};
+
+    let (token_1, token_2) = match definition_token_a_id
+        .value()
+        .cmp(definition_token_b_id.value())
+    {
+        std::cmp::Ordering::Less => (definition_token_b_id, definition_token_a_id),
+        std::cmp::Ordering::Greater => (definition_token_a_id, definition_token_b_id),
+        std::cmp::Ordering::Equal => panic!("Definitions match"),
+    };
+
+    let mut bytes = [0; 64];
+    bytes[0..32].copy_from_slice(&token_1.to_bytes());
+    bytes[32..].copy_from_slice(&token_2.to_bytes());
+
+    PdaSeed::new(
+        Impl::hash_bytes(&bytes)
+            .as_bytes()
+            .try_into()
+            .expect("Hash output must be exactly 32 bytes long"),
+    )
+}
+
+pub fn compute_vault_pda(
+    amm_program_id: ProgramId,
+    pool_id: AccountId,
+    definition_token_id: AccountId,
+) -> AccountId {
+    AccountId::from((
+        &amm_program_id,
+        &compute_vault_pda_seed(pool_id, definition_token_id),
+    ))
+}
+
+pub fn compute_vault_pda_seed(pool_id: AccountId, definition_token_id: AccountId) -> PdaSeed {
+    use risc0_zkvm::sha::{Impl, Sha256};
+
+    let mut bytes = [0; 64];
+    bytes[0..32].copy_from_slice(&pool_id.to_bytes());
+    bytes[32..].copy_from_slice(&definition_token_id.to_bytes());
+
+    PdaSeed::new(
+        Impl::hash_bytes(&bytes)
+            .as_bytes()
+            .try_into()
+            .expect("Hash output must be exactly 32 bytes long"),
+    )
+}
+
+pub fn compute_liquidity_token_pda(amm_program_id: ProgramId, pool_id: AccountId) -> AccountId {
+    AccountId::from((&amm_program_id, &compute_liquidity_token_pda_seed(pool_id)))
+}
+
+pub fn compute_liquidity_token_pda_seed(pool_id: AccountId) -> PdaSeed {
+    use risc0_zkvm::sha::{Impl, Sha256};
+
+    let mut bytes = [0; 64];
+    bytes[0..32].copy_from_slice(&pool_id.to_bytes());
+    bytes[32..].copy_from_slice(&[0; 32]);
+
+    PdaSeed::new(
+        Impl::hash_bytes(&bytes)
+            .as_bytes()
+            .try_into()
+            .expect("Hash output must be exactly 32 bytes long"),
+    )
+}

amm/methods/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "amm-methods"
+version = "0.1.0"
+edition = "2021"
+
+[build-dependencies]
+risc0-build = "=3.0.5"
+
+[dependencies]
+risc0-zkvm = { version = "=3.0.5", features = ["std"] }
+amm_core = { path = "../amm_core" }
+
+[package.metadata.risc0]
+methods = ["guest"]

amm/methods/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    risc0_build::embed_methods();
+}

amm/methods/guest/Cargo.toml

@@ -0,0 +1,23 @@
+[package]
+name = "amm-guest"
+version = "0.1.0"
+edition = "2021"
+
+[workspace]
+
+[patch."https://github.com/logos-blockchain/lssa.git"]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git" }
+
+[[bin]]
+name = "amm"
+path = "src/bin/amm.rs"
+
+[dependencies]
+lez-framework = { git = "https://github.com/logos-co/spel.git", package = "lez-framework" }
+nssa_core = { git = "https://github.com/logos-blockchain/lssa.git", rev = "767b5afd388c7981bcdf6f5b5c80159607e07e5b" }
+risc0-zkvm = { version = "=3.0.5", default-features = false }
+amm_core = { path = "../../amm_core" }
+amm_program = { path = "../..", package = "amm_program" }
+token_core = { path = "../../../token/token_core" }
+serde = { version = "1.0", features = ["derive"] }
+borsh = "1.5"

amm/methods/guest/src/bin/amm.rs

@@ -0,0 +1,130 @@
+#![no_main]
+
+use std::num::NonZeroU128;
+
+use lez_framework::prelude::*;
+use nssa_core::{
+    account::{AccountId, AccountWithMetadata},
+    program::ProgramId,
+};
+
+risc0_zkvm::guest::entry!(main);
+
+#[lez_program(instruction = "amm_core::Instruction")]
+mod amm {
+    #[allow(unused_imports)]
+    use super::*;
+
+    /// Initializes a new Pool (or re-initializes an inactive Pool).
+    #[instruction]
+    pub fn new_definition(
+        pool: AccountWithMetadata,
+        vault_a: AccountWithMetadata,
+        vault_b: AccountWithMetadata,
+        pool_definition_lp: AccountWithMetadata,
+        user_holding_a: AccountWithMetadata,
+        user_holding_b: AccountWithMetadata,
+        user_holding_lp: AccountWithMetadata,
+        token_a_amount: u128,
+        token_b_amount: u128,
+        amm_program_id: ProgramId,
+    ) -> LezResult {
+        let (post_states, chained_calls) = amm_program::new_definition::new_definition(
+            pool,
+            vault_a,
+            vault_b,
+            pool_definition_lp,
+            user_holding_a,
+            user_holding_b,
+            user_holding_lp,
+            NonZeroU128::new(token_a_amount).expect("token_a_amount must be nonzero"),
+            NonZeroU128::new(token_b_amount).expect("token_b_amount must be nonzero"),
+            amm_program_id,
+        );
+        Ok(LezOutput::with_chained_calls(post_states, chained_calls))
+    }
+
+    /// Adds liquidity to the Pool.
+    #[instruction]
+    pub fn add_liquidity(
+        pool: AccountWithMetadata,
+        vault_a: AccountWithMetadata,
+        vault_b: AccountWithMetadata,
+        pool_definition_lp: AccountWithMetadata,
+        user_holding_a: AccountWithMetadata,
+        user_holding_b: AccountWithMetadata,
+        user_holding_lp: AccountWithMetadata,
+        min_amount_liquidity: u128,
+        max_amount_to_add_token_a: u128,
+        max_amount_to_add_token_b: u128,
+    ) -> LezResult {
+        let (post_states, chained_calls) = amm_program::add::add_liquidity(
+            pool,
+            vault_a,
+            vault_b,
+            pool_definition_lp,
+            user_holding_a,
+            user_holding_b,
+            user_holding_lp,
+            NonZeroU128::new(min_amount_liquidity).expect("min_amount_liquidity must be nonzero"),
+            max_amount_to_add_token_a,
+            max_amount_to_add_token_b,
+        );
+        Ok(LezOutput::with_chained_calls(post_states, chained_calls))
+    }
+
+    /// Removes liquidity from the Pool.
+    #[instruction]
+    pub fn remove_liquidity(
+        pool: AccountWithMetadata,
+        vault_a: AccountWithMetadata,
+        vault_b: AccountWithMetadata,
+        pool_definition_lp: AccountWithMetadata,
+        user_holding_a: AccountWithMetadata,
+        user_holding_b: AccountWithMetadata,
+        user_holding_lp: AccountWithMetadata,
+        remove_liquidity_amount: u128,
+        min_amount_to_remove_token_a: u128,
+        min_amount_to_remove_token_b: u128,
+    ) -> LezResult {
+        let (post_states, chained_calls) = amm_program::remove::remove_liquidity(
+            pool,
+            vault_a,
+            vault_b,
+            pool_definition_lp,
+            user_holding_a,
+            user_holding_b,
+            user_holding_lp,
+            NonZeroU128::new(remove_liquidity_amount)
+                .expect("remove_liquidity_amount must be nonzero"),
+            min_amount_to_remove_token_a,
+            min_amount_to_remove_token_b,
+        );
+        Ok(LezOutput::with_chained_calls(post_states, chained_calls))
+    }
+
+    /// Swap some quantity of tokens while maintaining the pool constant product.
+    #[instruction]
+    pub fn swap(
+        pool: AccountWithMetadata,
+        vault_a: AccountWithMetadata,
+        vault_b: AccountWithMetadata,
+        user_holding_a: AccountWithMetadata,
+        user_holding_b: AccountWithMetadata,
+        swap_amount_in: u128,
+        min_amount_out: u128,
+        token_definition_id_in: AccountId,
+    ) -> LezResult {
+        let (post_states, chained_calls) = amm_program::swap::swap(
+            pool,
+            vault_a,
+            vault_b,
+            user_holding_a,
+            user_holding_b,
+            swap_amount_in,
+            min_amount_out,
+            token_definition_id_in,
+        );
+        Ok(LezOutput::with_chained_calls(post_states, chained_calls))
+    }
+}

amm/methods/src/lib.rs

@@ -0,0 +1 @@
+include!(concat!(env!("OUT_DIR"), "/methods.rs"));

amm/src/add.rs

@@ -0,0 +1,178 @@
+use std::num::NonZeroU128;
+
+use amm_core::{PoolDefinition, compute_liquidity_token_pda_seed};
+use nssa_core::{
+    account::{AccountWithMetadata, Data},
+    program::{AccountPostState, ChainedCall},
+};
+
+#[expect(clippy::too_many_arguments, reason = "TODO: Fix later")]
+pub fn add_liquidity(
+    pool: AccountWithMetadata,
+    vault_a: AccountWithMetadata,
+    vault_b: AccountWithMetadata,
+    pool_definition_lp: AccountWithMetadata,
+    user_holding_a: AccountWithMetadata,
+    user_holding_b: AccountWithMetadata,
+    user_holding_lp: AccountWithMetadata,
+    min_amount_liquidity: NonZeroU128,
+    max_amount_to_add_token_a: u128,
+    max_amount_to_add_token_b: u128,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    // 1. Fetch Pool state
+    let pool_def_data = PoolDefinition::try_from(&pool.account.data)
+        .expect("Add liquidity: AMM Program expects valid Pool Definition Account");
+
+    assert_eq!(
+        vault_a.account_id, pool_def_data.vault_a_id,
+        "Vault A was not provided"
+    );
+
+    assert_eq!(
+        pool_def_data.liquidity_pool_id, pool_definition_lp.account_id,
+        "LP definition mismatch"
+    );
+
+    assert_eq!(
+        vault_b.account_id, pool_def_data.vault_b_id,
+        "Vault B was not provided"
+    );
+
+    assert!(
+        max_amount_to_add_token_a != 0 && max_amount_to_add_token_b != 0,
+        "Both max-balances must be nonzero"
+    );
+
+    // 2. Determine deposit amount
+    let vault_b_token_holding = token_core::TokenHolding::try_from(&vault_b.account.data)
+        .expect("Add liquidity: AMM Program expects valid Token Holding Account for Vault B");
+    let token_core::TokenHolding::Fungible {
+        definition_id: _,
+        balance: vault_b_balance,
+    } = vault_b_token_holding
+    else {
+        panic!(
+            "Add liquidity: AMM Program expects valid Fungible Token Holding Account for Vault B"
+        );
+    };
+
+    let vault_a_token_holding = token_core::TokenHolding::try_from(&vault_a.account.data)
+        .expect("Add liquidity: AMM Program expects valid Token Holding Account for Vault A");
+    let token_core::TokenHolding::Fungible {
+        definition_id: _,
+        balance: vault_a_balance,
+    } = vault_a_token_holding
+    else {
+        panic!(
+            "Add liquidity: AMM Program expects valid Fungible Token Holding Account for Vault A"
+        );
+    };
+
+    assert!(pool_def_data.reserve_a != 0, "Reserves must be nonzero");
+    assert!(pool_def_data.reserve_b != 0, "Reserves must be nonzero");
+    assert!(
+        vault_a_balance >= pool_def_data.reserve_a,
+        "Vaults' balances must be at least the reserve amounts"
+    );
+    assert!(
+        vault_b_balance >= pool_def_data.reserve_b,
+        "Vaults' balances must be at least the reserve amounts"
+    );
+
+    // Calculate actual_amounts
+    let ideal_a: u128 =
+        (pool_def_data.reserve_a * max_amount_to_add_token_b) / pool_def_data.reserve_b;
+    let ideal_b: u128 =
+        (pool_def_data.reserve_b * max_amount_to_add_token_a) / pool_def_data.reserve_a;
+
+    let actual_amount_a = if ideal_a > max_amount_to_add_token_a {
+        max_amount_to_add_token_a
+    } else {
+        ideal_a
+    };
+    let actual_amount_b = if ideal_b > max_amount_to_add_token_b {
+        max_amount_to_add_token_b
+    } else {
+        ideal_b
+    };
+
+    // 3. Validate amounts
+    assert!(
+        max_amount_to_add_token_a >= actual_amount_a,
+        "Actual trade amounts cannot exceed max_amounts"
+    );
+    assert!(
+        max_amount_to_add_token_b >= actual_amount_b,
+        "Actual trade amounts cannot exceed max_amounts"
+    );
+
+    assert!(actual_amount_a != 0, "A trade amount is 0");
+    assert!(actual_amount_b != 0, "A trade amount is 0");
+
+    // 4. Calculate LP to mint
+    let delta_lp = std::cmp::min(
+        pool_def_data.liquidity_pool_supply * actual_amount_a / pool_def_data.reserve_a,
+        pool_def_data.liquidity_pool_supply * actual_amount_b / pool_def_data.reserve_b,
+    );
+
+    assert!(delta_lp != 0, "Payable LP must be nonzero");
+
+    assert!(
+        delta_lp >= min_amount_liquidity.get(),
+        "Payable LP is less than provided minimum LP amount"
+    );
+
+    // 5. Update pool account
+    let mut pool_post = pool.account.clone();
+    let pool_post_definition = PoolDefinition {
+        liquidity_pool_supply: pool_def_data.liquidity_pool_supply + delta_lp,
+        reserve_a: pool_def_data.reserve_a + actual_amount_a,
+        reserve_b: pool_def_data.reserve_b + actual_amount_b,
+        ..pool_def_data
+    };
+
+    pool_post.data = Data::from(&pool_post_definition);
+    let token_program_id = user_holding_a.account.program_owner;
+
+    // Chain call for Token A (UserHoldingA -> Vault_A)
+    let call_token_a = ChainedCall::new(
+        token_program_id,
+        vec![user_holding_a.clone(), vault_a.clone()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: actual_amount_a,
+        },
+    );
+    // Chain call for Token B (UserHoldingB -> Vault_B)
+    let call_token_b = ChainedCall::new(
+        token_program_id,
+        vec![user_holding_b.clone(), vault_b.clone()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: actual_amount_b,
+        },
+    );
+    // Chain call for LP (mint new tokens for user_holding_lp)
+    let mut pool_definition_lp_auth = pool_definition_lp.clone();
+    pool_definition_lp_auth.is_authorized = true;
+    let call_token_lp = ChainedCall::new(
+        token_program_id,
+        vec![pool_definition_lp_auth.clone(), user_holding_lp.clone()],
+        &token_core::Instruction::Mint {
+            amount_to_mint: delta_lp,
+        },
+    )
+    .with_pda_seeds(vec![compute_liquidity_token_pda_seed(pool.account_id)]);
+
+    let chained_calls = vec![call_token_lp, call_token_b, call_token_a];
+
+    let post_states = vec![
+        AccountPostState::new(pool_post),
+        AccountPostState::new(vault_a.account.clone()),
+        AccountPostState::new(vault_b.account.clone()),
+        AccountPostState::new(pool_definition_lp.account.clone()),
+        AccountPostState::new(user_holding_a.account.clone()),
+        AccountPostState::new(user_holding_b.account.clone()),
+        AccountPostState::new(user_holding_lp.account.clone()),
+    ];
+
+    (post_states, chained_calls)
+}

amm/src/lib.rs

@@ -0,0 +1,10 @@
+//! The AMM Program implementation.
+
+pub use amm_core as core;
+
+pub mod add;
+pub mod new_definition;
+pub mod remove;
+pub mod swap;
+
+mod tests;

amm/src/new_definition.rs

@@ -0,0 +1,158 @@
+use std::num::NonZeroU128;
+
+use amm_core::{
+    PoolDefinition, compute_liquidity_token_pda, compute_liquidity_token_pda_seed,
+    compute_pool_pda, compute_vault_pda,
+};
+use nssa_core::{
+    account::{Account, AccountWithMetadata, Data},
+    program::{AccountPostState, ChainedCall, ProgramId},
+};
+
+#[expect(clippy::too_many_arguments, reason = "TODO: Fix later")]
+pub fn new_definition(
+    pool: AccountWithMetadata,
+    vault_a: AccountWithMetadata,
+    vault_b: AccountWithMetadata,
+    pool_definition_lp: AccountWithMetadata,
+    user_holding_a: AccountWithMetadata,
+    user_holding_b: AccountWithMetadata,
+    user_holding_lp: AccountWithMetadata,
+    token_a_amount: NonZeroU128,
+    token_b_amount: NonZeroU128,
+    amm_program_id: ProgramId,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    // Verify token_a and token_b are different
+    let definition_token_a_id = token_core::TokenHolding::try_from(&user_holding_a.account.data)
+        .expect("New definition: AMM Program expects valid Token Holding account for Token A")
+        .definition_id();
+    let definition_token_b_id = token_core::TokenHolding::try_from(&user_holding_b.account.data)
+        .expect("New definition: AMM Program expects valid Token Holding account for Token B")
+        .definition_id();
+
+    // both instances of the same token program
+    let token_program = user_holding_a.account.program_owner;
+
+    assert_eq!(
+        user_holding_b.account.program_owner, token_program,
+        "User Token holdings must use the same Token Program"
+    );
+    assert!(
+        definition_token_a_id != definition_token_b_id,
+        "Cannot set up a swap for a token with itself"
+    );
+    assert_eq!(
+        pool.account_id,
+        compute_pool_pda(amm_program_id, definition_token_a_id, definition_token_b_id),
+        "Pool Definition Account ID does not match PDA"
+    );
+    assert_eq!(
+        vault_a.account_id,
+        compute_vault_pda(amm_program_id, pool.account_id, definition_token_a_id),
+        "Vault ID does not match PDA"
+    );
+    assert_eq!(
+        vault_b.account_id,
+        compute_vault_pda(amm_program_id, pool.account_id, definition_token_b_id),
+        "Vault ID does not match PDA"
+    );
+    assert_eq!(
+        pool_definition_lp.account_id,
+        compute_liquidity_token_pda(amm_program_id, pool.account_id),
+        "Liquidity pool Token Definition Account ID does not match PDA"
+    );
+
+    // TODO: return here
+    // Verify that Pool Account is not active
+    let pool_account_data = if pool.account == Account::default() {
+        PoolDefinition::default()
+    } else {
+        PoolDefinition::try_from(&pool.account.data)
+            .expect("AMM program expects a valid Pool account")
+    };
+
+    assert!(
+        !pool_account_data.active,
+        "Cannot initialize an active Pool Definition"
+    );
+
+    // LP Token minting calculation
+    let initial_lp = (token_a_amount.get() * token_b_amount.get()).isqrt();
+
+    // Update pool account
+    let mut pool_post = pool.account.clone();
+    let pool_post_definition = PoolDefinition {
+        definition_token_a_id,
+        definition_token_b_id,
+        vault_a_id: vault_a.account_id,
+        vault_b_id: vault_b.account_id,
+        liquidity_pool_id: pool_definition_lp.account_id,
+        liquidity_pool_supply: initial_lp,
+        reserve_a: token_a_amount.into(),
+        reserve_b: token_b_amount.into(),
+        fees: 0u128, // TODO: we assume all fees are 0 for now.
+        active: true,
+    };
+
+    pool_post.data = Data::from(&pool_post_definition);
+    let pool_post: AccountPostState = if pool.account == Account::default() {
+        AccountPostState::new_claimed(pool_post.clone())
+    } else {
+        AccountPostState::new(pool_post.clone())
+    };
+
+    let token_program_id = user_holding_a.account.program_owner;
+
+    // Chain call for Token A (user_holding_a -> Vault_A)
+    let call_token_a = ChainedCall::new(
+        token_program_id,
+        vec![user_holding_a.clone(), vault_a.clone()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: token_a_amount.into(),
+        },
+    );
+    // Chain call for Token B (user_holding_b -> Vault_B)
+    let call_token_b = ChainedCall::new(
+        token_program_id,
+        vec![user_holding_b.clone(), vault_b.clone()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: token_b_amount.into(),
+        },
+    );
+
+    // Chain call for liquidity token (TokenLP definition -> User LP Holding)
+    let instruction = if pool.account == Account::default() {
+        token_core::Instruction::NewFungibleDefinition {
+            name: String::from("LP Token"),
+            total_supply: initial_lp,
+        }
+    } else {
+        token_core::Instruction::Mint {
+            amount_to_mint: initial_lp,
+        }
+    };
+
+    let mut pool_lp_auth = pool_definition_lp.clone();
+    pool_lp_auth.is_authorized = true;
+
+    let call_token_lp = ChainedCall::new(
+        token_program_id,
+        vec![pool_lp_auth.clone(), user_holding_lp.clone()],
+        &instruction,
+    )
+    .with_pda_seeds(vec![compute_liquidity_token_pda_seed(pool.account_id)]);
+
+    let chained_calls = vec![call_token_lp, call_token_b, call_token_a];
+
+    let post_states = vec![
+        pool_post.clone(),
+        AccountPostState::new(vault_a.account.clone()),
+        AccountPostState::new(vault_b.account.clone()),
+        AccountPostState::new(pool_definition_lp.account.clone()),
+        AccountPostState::new(user_holding_a.account.clone()),
+        AccountPostState::new(user_holding_b.account.clone()),
+        AccountPostState::new(user_holding_lp.account.clone()),
+    ];
+
+    (post_states.clone(), chained_calls)
+}

amm/src/remove.rs

@@ -0,0 +1,166 @@
+use std::num::NonZeroU128;
+
+use amm_core::{PoolDefinition, compute_liquidity_token_pda_seed, compute_vault_pda_seed};
+use nssa_core::{
+    account::{AccountWithMetadata, Data},
+    program::{AccountPostState, ChainedCall},
+};
+
+#[expect(clippy::too_many_arguments, reason = "TODO: Fix later")]
+pub fn remove_liquidity(
+    pool: AccountWithMetadata,
+    vault_a: AccountWithMetadata,
+    vault_b: AccountWithMetadata,
+    pool_definition_lp: AccountWithMetadata,
+    user_holding_a: AccountWithMetadata,
+    user_holding_b: AccountWithMetadata,
+    user_holding_lp: AccountWithMetadata,
+    remove_liquidity_amount: NonZeroU128,
+    min_amount_to_remove_token_a: u128,
+    min_amount_to_remove_token_b: u128,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    let remove_liquidity_amount: u128 = remove_liquidity_amount.into();
+
+    // 1. Fetch Pool state
+    let pool_def_data = PoolDefinition::try_from(&pool.account.data)
+        .expect("Remove liquidity: AMM Program expects a valid Pool Definition Account");
+
+    assert!(pool_def_data.active, "Pool is inactive");
+    assert_eq!(
+        pool_def_data.liquidity_pool_id, pool_definition_lp.account_id,
+        "LP definition mismatch"
+    );
+    assert_eq!(
+        vault_a.account_id, pool_def_data.vault_a_id,
+        "Vault A was not provided"
+    );
+    assert_eq!(
+        vault_b.account_id, pool_def_data.vault_b_id,
+        "Vault B was not provided"
+    );
+
+    // Vault addresses do not need to be checked with PDA
+    // calculation for setting authorization since stored
+    // in the Pool Definition.
+    let mut running_vault_a = vault_a.clone();
+    let mut running_vault_b = vault_b.clone();
+    running_vault_a.is_authorized = true;
+    running_vault_b.is_authorized = true;
+
+    assert!(
+        min_amount_to_remove_token_a != 0,
+        "Minimum withdraw amount must be nonzero"
+    );
+    assert!(
+        min_amount_to_remove_token_b != 0,
+        "Minimum withdraw amount must be nonzero"
+    );
+
+    // 2. Compute withdrawal amounts
+    let user_holding_lp_data = token_core::TokenHolding::try_from(&user_holding_lp.account.data)
+        .expect("Remove liquidity: AMM Program expects a valid Token Account for liquidity token");
+    let token_core::TokenHolding::Fungible {
+        definition_id: _,
+        balance: user_lp_balance,
+    } = user_holding_lp_data
+    else {
+        panic!(
+            "Remove liquidity: AMM Program expects a valid Fungible Token Holding Account for liquidity token"
+        );
+    };
+
+    assert!(
+        user_lp_balance <= pool_def_data.liquidity_pool_supply,
+        "Invalid liquidity account provided"
+    );
+    assert_eq!(
+        user_holding_lp_data.definition_id(),
+        pool_def_data.liquidity_pool_id,
+        "Invalid liquidity account provided"
+    );
+
+    let withdraw_amount_a =
+        (pool_def_data.reserve_a * remove_liquidity_amount) / pool_def_data.liquidity_pool_supply;
+    let withdraw_amount_b =
+        (pool_def_data.reserve_b * remove_liquidity_amount) / pool_def_data.liquidity_pool_supply;
+
+    // 3. Validate and slippage check
+    assert!(
+        withdraw_amount_a >= min_amount_to_remove_token_a,
+        "Insufficient minimal withdraw amount (Token A) provided for liquidity amount"
+    );
+    assert!(
+        withdraw_amount_b >= min_amount_to_remove_token_b,
+        "Insufficient minimal withdraw amount (Token B) provided for liquidity amount"
+    );
+
+    // 4. Calculate LP to reduce cap by
+    let delta_lp: u128 = (pool_def_data.liquidity_pool_supply * remove_liquidity_amount)
+        / pool_def_data.liquidity_pool_supply;
+
+    let active: bool = pool_def_data.liquidity_pool_supply - delta_lp != 0;
+
+    // 5. Update pool account
+    let mut pool_post = pool.account.clone();
+    let pool_post_definition = PoolDefinition {
+        liquidity_pool_supply: pool_def_data.liquidity_pool_supply - delta_lp,
+        reserve_a: pool_def_data.reserve_a - withdraw_amount_a,
+        reserve_b: pool_def_data.reserve_b - withdraw_amount_b,
+        active,
+        ..pool_def_data.clone()
+    };
+
+    pool_post.data = Data::from(&pool_post_definition);
+
+    let token_program_id = user_holding_a.account.program_owner;
+
+    // Chaincall for Token A withdraw
+    let call_token_a = ChainedCall::new(
+        token_program_id,
+        vec![running_vault_a, user_holding_a.clone()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: withdraw_amount_a,
+        },
+    )
+    .with_pda_seeds(vec![compute_vault_pda_seed(
+        pool.account_id,
+        pool_def_data.definition_token_a_id,
+    )]);
+    // Chaincall for Token B withdraw
+    let call_token_b = ChainedCall::new(
+        token_program_id,
+        vec![running_vault_b, user_holding_b.clone()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: withdraw_amount_b,
+        },
+    )
+    .with_pda_seeds(vec![compute_vault_pda_seed(
+        pool.account_id,
+        pool_def_data.definition_token_b_id,
+    )]);
+    // Chaincall for LP adjustment
+    let mut pool_definition_lp_auth = pool_definition_lp.clone();
+    pool_definition_lp_auth.is_authorized = true;
+    let call_token_lp = ChainedCall::new(
+        token_program_id,
+        vec![pool_definition_lp_auth, user_holding_lp.clone()],
+        &token_core::Instruction::Burn {
+            amount_to_burn: delta_lp,
+        },
+    )
+    .with_pda_seeds(vec![compute_liquidity_token_pda_seed(pool.account_id)]);
+
+    let chained_calls = vec![call_token_lp, call_token_b, call_token_a];
+
+    let post_states = vec![
+        AccountPostState::new(pool_post.clone()),
+        AccountPostState::new(vault_a.account.clone()),
+        AccountPostState::new(vault_b.account.clone()),
+        AccountPostState::new(pool_definition_lp.account.clone()),
+        AccountPostState::new(user_holding_a.account.clone()),
+        AccountPostState::new(user_holding_b.account.clone()),
+        AccountPostState::new(user_holding_lp.account.clone()),
+    ];
+
+    (post_states, chained_calls)
+}

amm/src/swap.rs

@@ -0,0 +1,176 @@
+pub use amm_core::{PoolDefinition, compute_liquidity_token_pda_seed, compute_vault_pda_seed};
+use nssa_core::{
+    account::{AccountId, AccountWithMetadata, Data},
+    program::{AccountPostState, ChainedCall},
+};
+
+#[expect(clippy::too_many_arguments, reason = "TODO: Fix later")]
+pub fn swap(
+    pool: AccountWithMetadata,
+    vault_a: AccountWithMetadata,
+    vault_b: AccountWithMetadata,
+    user_holding_a: AccountWithMetadata,
+    user_holding_b: AccountWithMetadata,
+    swap_amount_in: u128,
+    min_amount_out: u128,
+    token_in_id: AccountId,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    // Verify vaults are in fact vaults
+    let pool_def_data = PoolDefinition::try_from(&pool.account.data)
+        .expect("Swap: AMM Program expects a valid Pool Definition Account");
+
+    assert!(pool_def_data.active, "Pool is inactive");
+    assert_eq!(
+        vault_a.account_id, pool_def_data.vault_a_id,
+        "Vault A was not provided"
+    );
+    assert_eq!(
+        vault_b.account_id, pool_def_data.vault_b_id,
+        "Vault B was not provided"
+    );
+
+    // fetch pool reserves
+    // validates reserves is at least the vaults' balances
+    let vault_a_token_holding = token_core::TokenHolding::try_from(&vault_a.account.data)
+        .expect("Swap: AMM Program expects a valid Token Holding Account for Vault A");
+    let token_core::TokenHolding::Fungible {
+        definition_id: _,
+        balance: vault_a_balance,
+    } = vault_a_token_holding
+    else {
+        panic!("Swap: AMM Program expects a valid Fungible Token Holding Account for Vault A");
+    };
+
+    assert!(
+        vault_a_balance >= pool_def_data.reserve_a,
+        "Reserve for Token A exceeds vault balance"
+    );
+
+    let vault_b_token_holding = token_core::TokenHolding::try_from(&vault_b.account.data)
+        .expect("Swap: AMM Program expects a valid Token Holding Account for Vault B");
+    let token_core::TokenHolding::Fungible {
+        definition_id: _,
+        balance: vault_b_balance,
+    } = vault_b_token_holding
+    else {
+        panic!("Swap: AMM Program expects a valid Fungible Token Holding Account for Vault B");
+    };
+
+    assert!(
+        vault_b_balance >= pool_def_data.reserve_b,
+        "Reserve for Token B exceeds vault balance"
+    );
+
+    let (chained_calls, [deposit_a, withdraw_a], [deposit_b, withdraw_b]) =
+        if token_in_id == pool_def_data.definition_token_a_id {
+            let (chained_calls, deposit_a, withdraw_b) = swap_logic(
+                user_holding_a.clone(),
+                vault_a.clone(),
+                vault_b.clone(),
+                user_holding_b.clone(),
+                swap_amount_in,
+                min_amount_out,
+                pool_def_data.reserve_a,
+                pool_def_data.reserve_b,
+                pool.account_id,
+            );
+
+            (chained_calls, [deposit_a, 0], [0, withdraw_b])
+        } else if token_in_id == pool_def_data.definition_token_b_id {
+            let (chained_calls, deposit_b, withdraw_a) = swap_logic(
+                user_holding_b.clone(),
+                vault_b.clone(),
+                vault_a.clone(),
+                user_holding_a.clone(),
+                swap_amount_in,
+                min_amount_out,
+                pool_def_data.reserve_b,
+                pool_def_data.reserve_a,
+                pool.account_id,
+            );
+
+            (chained_calls, [0, withdraw_a], [deposit_b, 0])
+        } else {
+            panic!("AccountId is not a token type for the pool");
+        };
+
+    // Update pool account
+    let mut pool_post = pool.account.clone();
+    let pool_post_definition = PoolDefinition {
+        reserve_a: pool_def_data.reserve_a + deposit_a - withdraw_a,
+        reserve_b: pool_def_data.reserve_b + deposit_b - withdraw_b,
+        ..pool_def_data
+    };
+
+    pool_post.data = Data::from(&pool_post_definition);
+
+    let post_states = vec![
+        AccountPostState::new(pool_post.clone()),
+        AccountPostState::new(vault_a.account.clone()),
+        AccountPostState::new(vault_b.account.clone()),
+        AccountPostState::new(user_holding_a.account.clone()),
+        AccountPostState::new(user_holding_b.account.clone()),
+    ];
+
+    (post_states, chained_calls)
+}
+
+#[expect(clippy::too_many_arguments, reason = "TODO: Fix later")]
+fn swap_logic(
+    user_deposit: AccountWithMetadata,
+    vault_deposit: AccountWithMetadata,
+    vault_withdraw: AccountWithMetadata,
+    user_withdraw: AccountWithMetadata,
+    swap_amount_in: u128,
+    min_amount_out: u128,
+    reserve_deposit_vault_amount: u128,
+    reserve_withdraw_vault_amount: u128,
+    pool_id: AccountId,
+) -> (Vec<ChainedCall>, u128, u128) {
+    // Compute withdraw amount
+    // Maintains pool constant product
+    // k = pool_def_data.reserve_a * pool_def_data.reserve_b;
+    let withdraw_amount = (reserve_withdraw_vault_amount * swap_amount_in)
+        / (reserve_deposit_vault_amount + swap_amount_in);
+
+    // Slippage check
+    assert!(
+        min_amount_out <= withdraw_amount,
+        "Withdraw amount is less than minimal amount out"
+    );
+    assert!(withdraw_amount != 0, "Withdraw amount should be nonzero");
+
+    let token_program_id = user_deposit.account.program_owner;
+
+    let mut chained_calls = Vec::new();
+    chained_calls.push(ChainedCall::new(
+        token_program_id,
+        vec![user_deposit, vault_deposit],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: swap_amount_in,
+        },
+    ));
+
+    let mut vault_withdraw = vault_withdraw.clone();
+    vault_withdraw.is_authorized = true;
+
+    let pda_seed = compute_vault_pda_seed(
+        pool_id,
+        token_core::TokenHolding::try_from(&vault_withdraw.account.data)
+            .expect("Swap Logic: AMM Program expects valid token data")
+            .definition_id(),
+    );
+
+    chained_calls.push(
+        ChainedCall::new(
+            token_program_id,
+            vec![vault_withdraw, user_withdraw],
+            &token_core::Instruction::Transfer {
+                amount_to_transfer: withdraw_amount,
+            },
+        )
+        .with_pda_seeds(vec![pda_seed]),
+    );
+
+    (chained_calls, swap_amount_in, withdraw_amount)
+}

token/Cargo.toml

@@ -0,0 +1,8 @@
+[package]
+name = "token_program"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", features = ["host"] }
+token_core = { path = "token_core" }

token/methods/Cargo.toml

@@ -0,0 +1,14 @@
+[package]
+name = "token-methods"
+version = "0.1.0"
+edition = "2021"
+
+[build-dependencies]
+risc0-build = "=3.0.5"
+
+[dependencies]
+risc0-zkvm = { version = "=3.0.5", features = ["std"] }
+token_core = { path = "../token_core" }
+
+[package.metadata.risc0]
+methods = ["guest"]

token/methods/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    risc0_build::embed_methods();
+}

token/methods/guest/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "token-guest"
+version = "0.1.0"
+edition = "2021"
+
+[workspace]
+
+[patch."https://github.com/logos-blockchain/lssa.git"]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git" }
+
+[[bin]]
+name = "token"
+path = "src/bin/token.rs"
+
+[dependencies]
+lez-framework = { git = "https://github.com/logos-co/spel.git", package = "lez-framework" }
+nssa_core = { git = "https://github.com/logos-blockchain/lssa.git", rev = "767b5afd388c7981bcdf6f5b5c80159607e07e5b" }
+risc0-zkvm = { version = "=3.0.5", default-features = false }
+token_core = { path = "../../token_core" }
+token_program = { path = "../..", package = "token_program" }
+serde = { version = "1.0", features = ["derive"] }
+borsh = "1.5"

token/methods/guest/src/bin/token.rs

@@ -0,0 +1,118 @@
+#![no_main]
+
+use lez_framework::prelude::*;
+use nssa_core::account::AccountWithMetadata;
+
+risc0_zkvm::guest::entry!(main);
+
+#[lez_program(instruction = "token_core::Instruction")]
+mod token {
+    #[allow(unused_imports)]
+    use super::*;
+
+    /// Transfer tokens from sender to recipient.
+    #[instruction]
+    pub fn transfer(
+        sender: AccountWithMetadata,
+        recipient: AccountWithMetadata,
+        amount_to_transfer: u128,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(token_program::transfer::transfer(
+            sender,
+            recipient,
+            amount_to_transfer,
+        )))
+    }
+
+    /// Create a new fungible token definition without metadata.
+    #[instruction]
+    pub fn new_fungible_definition(
+        definition_target_account: AccountWithMetadata,
+        holding_target_account: AccountWithMetadata,
+        name: String,
+        total_supply: u128,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(
+            token_program::new_definition::new_fungible_definition(
+                definition_target_account,
+                holding_target_account,
+                name,
+                total_supply,
+            ),
+        ))
+    }
+
+    /// Create a new fungible or non-fungible token definition with metadata.
+    #[instruction]
+    pub fn new_definition_with_metadata(
+        definition_target_account: AccountWithMetadata,
+        holding_target_account: AccountWithMetadata,
+        metadata_target_account: AccountWithMetadata,
+        new_definition: token_core::NewTokenDefinition,
+        metadata: Box<token_core::NewTokenMetadata>,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(
+            token_program::new_definition::new_definition_with_metadata(
+                definition_target_account,
+                holding_target_account,
+                metadata_target_account,
+                new_definition,
+                *metadata,
+            ),
+        ))
+    }
+
+    /// Initialize a token holding account for a given token definition.
+    #[instruction]
+    pub fn initialize_account(
+        definition_account: AccountWithMetadata,
+        account_to_initialize: AccountWithMetadata,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(
+            token_program::initialize::initialize_account(
+                definition_account,
+                account_to_initialize,
+            ),
+        ))
+    }
+
+    /// Burn tokens from the holder's account.
+    #[instruction]
+    pub fn burn(
+        definition_account: AccountWithMetadata,
+        user_holding_account: AccountWithMetadata,
+        amount_to_burn: u128,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(token_program::burn::burn(
+            definition_account,
+            user_holding_account,
+            amount_to_burn,
+        )))
+    }
+
+    /// Mint new tokens to the holder's account.
+    #[instruction]
+    pub fn mint(
+        definition_account: AccountWithMetadata,
+        user_holding_account: AccountWithMetadata,
+        amount_to_mint: u128,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(token_program::mint::mint(
+            definition_account,
+            user_holding_account,
+            amount_to_mint,
+        )))
+    }
+
+    /// Print a new NFT from the master copy.
+    #[instruction]
+    pub fn print_nft(
+        master_account: AccountWithMetadata,
+        printed_account: AccountWithMetadata,
+    ) -> LezResult {
+        Ok(LezOutput::states_only(token_program::print_nft::print_nft(
+            master_account,
+            printed_account,
+        )))
+    }
+}

token/methods/src/lib.rs

@@ -0,0 +1 @@
+include!(concat!(env!("OUT_DIR"), "/methods.rs"));

token/src/burn.rs

@@ -0,0 +1,104 @@
+use nssa_core::{
+    account::{AccountWithMetadata, Data},
+    program::AccountPostState,
+};
+use token_core::{TokenDefinition, TokenHolding};
+
+pub fn burn(
+    definition_account: AccountWithMetadata,
+    user_holding_account: AccountWithMetadata,
+    amount_to_burn: u128,
+) -> Vec<AccountPostState> {
+    assert!(
+        user_holding_account.is_authorized,
+        "Authorization is missing"
+    );
+
+    let mut definition = TokenDefinition::try_from(&definition_account.account.data)
+        .expect("Token Definition account must be valid");
+    let mut holding = TokenHolding::try_from(&user_holding_account.account.data)
+        .expect("Token Holding account must be valid");
+
+    assert_eq!(
+        definition_account.account_id,
+        holding.definition_id(),
+        "Mismatch Token Definition and Token Holding"
+    );
+
+    match (&mut definition, &mut holding) {
+        (
+            TokenDefinition::Fungible {
+                name: _,
+                metadata_id: _,
+                total_supply,
+            },
+            TokenHolding::Fungible {
+                definition_id: _,
+                balance,
+            },
+        ) => {
+            *balance = balance
+                .checked_sub(amount_to_burn)
+                .expect("Insufficient balance to burn");
+
+            *total_supply = total_supply
+                .checked_sub(amount_to_burn)
+                .expect("Total supply underflow");
+        }
+        (
+            TokenDefinition::NonFungible {
+                name: _,
+                printable_supply,
+                metadata_id: _,
+            },
+            TokenHolding::NftMaster {
+                definition_id: _,
+                print_balance,
+            },
+        ) => {
+            *printable_supply = printable_supply
+                .checked_sub(amount_to_burn)
+                .expect("Printable supply underflow");
+
+            *print_balance = print_balance
+                .checked_sub(amount_to_burn)
+                .expect("Insufficient balance to burn");
+        }
+        (
+            TokenDefinition::NonFungible {
+                name: _,
+                printable_supply,
+                metadata_id: _,
+            },
+            TokenHolding::NftPrintedCopy {
+                definition_id: _,
+                owned,
+            },
+        ) => {
+            assert_eq!(
+                amount_to_burn, 1,
+                "Invalid balance to burn for NFT Printed Copy"
+            );
+
+            assert!(*owned, "Cannot burn unowned NFT Printed Copy");
+
+            *printable_supply = printable_supply
+                .checked_sub(1)
+                .expect("Printable supply underflow");
+
+            *owned = false;
+        }
+        _ => panic!("Mismatched Token Definition and Token Holding types"),
+    }
+
+    let mut definition_post = definition_account.account;
+    definition_post.data = Data::from(&definition);
+
+    let mut holding_post = user_holding_account.account;
+    holding_post.data = Data::from(&holding);
+
+    vec![
+        AccountPostState::new(definition_post),
+        AccountPostState::new(holding_post),
+    ]
+}

token/src/initialize.rs

@@ -0,0 +1,34 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata, Data},
+    program::AccountPostState,
+};
+use token_core::{TokenDefinition, TokenHolding};
+
+pub fn initialize_account(
+    definition_account: AccountWithMetadata,
+    account_to_initialize: AccountWithMetadata,
+) -> Vec<AccountPostState> {
+    assert_eq!(
+        account_to_initialize.account,
+        Account::default(),
+        "Only Uninitialized accounts can be initialized"
+    );
+
+    // TODO: #212 We should check that this is an account owned by the token program.
+    // This check can't be done here since the ID of the program is known only after compiling it
+    //
+    // Check definition account is valid
+    let definition = TokenDefinition::try_from(&definition_account.account.data)
+        .expect("Definition account must be valid");
+    let holding =
+        TokenHolding::zeroized_from_definition(definition_account.account_id, &definition);
+
+    let definition_post = definition_account.account;
+    let mut account_to_initialize = account_to_initialize.account;
+    account_to_initialize.data = Data::from(&holding);
+
+    vec![
+        AccountPostState::new(definition_post),
+        AccountPostState::new_claimed(account_to_initialize),
+    ]
+}

token/src/lib.rs

@@ -0,0 +1,12 @@
+//! The Token Program implementation.
+
+pub use token_core as core;
+
+pub mod burn;
+pub mod initialize;
+pub mod mint;
+pub mod new_definition;
+pub mod print_nft;
+pub mod transfer;
+
+mod tests;

token/src/mint.rs

@@ -0,0 +1,71 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata, Data},
+    program::AccountPostState,
+};
+use token_core::{TokenDefinition, TokenHolding};
+
+pub fn mint(
+    definition_account: AccountWithMetadata,
+    user_holding_account: AccountWithMetadata,
+    amount_to_mint: u128,
+) -> Vec<AccountPostState> {
+    assert!(
+        definition_account.is_authorized,
+        "Definition authorization is missing"
+    );
+
+    let mut definition = TokenDefinition::try_from(&definition_account.account.data)
+        .expect("Token Definition account must be valid");
+    let mut holding = if user_holding_account.account == Account::default() {
+        TokenHolding::zeroized_from_definition(definition_account.account_id, &definition)
+    } else {
+        TokenHolding::try_from(&user_holding_account.account.data)
+            .expect("Token Holding account must be valid")
+    };
+
+    assert_eq!(
+        definition_account.account_id,
+        holding.definition_id(),
+        "Mismatch Token Definition and Token Holding"
+    );
+
+    match (&mut definition, &mut holding) {
+        (
+            TokenDefinition::Fungible {
+                name: _,
+                metadata_id: _,
+                total_supply,
+            },
+            TokenHolding::Fungible {
+                definition_id: _,
+                balance,
+            },
+        ) => {
+            *balance = balance
+                .checked_add(amount_to_mint)
+                .expect("Balance overflow on minting");
+
+            *total_supply = total_supply
+                .checked_add(amount_to_mint)
+                .expect("Total supply overflow");
+        }
+        (
+            TokenDefinition::NonFungible { .. },
+            TokenHolding::NftMaster { .. } | TokenHolding::NftPrintedCopy { .. },
+        ) => {
+            panic!("Cannot mint additional supply for Non-Fungible Tokens");
+        }
+        _ => panic!("Mismatched Token Definition and Token Holding types"),
+    }
+
+    let mut definition_post = definition_account.account;
+    definition_post.data = Data::from(&definition);
+
+    let mut holding_post = user_holding_account.account;
+    holding_post.data = Data::from(&holding);
+
+    vec![
+        AccountPostState::new(definition_post),
+        AccountPostState::new_claimed_if_default(holding_post),
+    ]
+}

token/src/new_definition.rs

@@ -0,0 +1,124 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata, Data},
+    program::AccountPostState,
+};
+use token_core::{
+    NewTokenDefinition, NewTokenMetadata, TokenDefinition, TokenHolding, TokenMetadata,
+};
+
+pub fn new_fungible_definition(
+    definition_target_account: AccountWithMetadata,
+    holding_target_account: AccountWithMetadata,
+    name: String,
+    total_supply: u128,
+) -> Vec<AccountPostState> {
+    assert_eq!(
+        definition_target_account.account,
+        Account::default(),
+        "Definition target account must have default values"
+    );
+
+    assert_eq!(
+        holding_target_account.account,
+        Account::default(),
+        "Holding target account must have default values"
+    );
+
+    let token_definition = TokenDefinition::Fungible {
+        name,
+        total_supply,
+        metadata_id: None,
+    };
+    let token_holding = TokenHolding::Fungible {
+        definition_id: definition_target_account.account_id,
+        balance: total_supply,
+    };
+
+    let mut definition_target_account_post = definition_target_account.account;
+    definition_target_account_post.data = Data::from(&token_definition);
+
+    let mut holding_target_account_post = holding_target_account.account;
+    holding_target_account_post.data = Data::from(&token_holding);
+
+    vec![
+        AccountPostState::new_claimed(definition_target_account_post),
+        AccountPostState::new_claimed(holding_target_account_post),
+    ]
+}
+
+pub fn new_definition_with_metadata(
+    definition_target_account: AccountWithMetadata,
+    holding_target_account: AccountWithMetadata,
+    metadata_target_account: AccountWithMetadata,
+    new_definition: NewTokenDefinition,
+    metadata: NewTokenMetadata,
+) -> Vec<AccountPostState> {
+    assert_eq!(
+        definition_target_account.account,
+        Account::default(),
+        "Definition target account must have default values"
+    );
+
+    assert_eq!(
+        holding_target_account.account,
+        Account::default(),
+        "Holding target account must have default values"
+    );
+
+    assert_eq!(
+        metadata_target_account.account,
+        Account::default(),
+        "Metadata target account must have default values"
+    );
+
+    let (token_definition, token_holding) = match new_definition {
+        NewTokenDefinition::Fungible { name, total_supply } => (
+            TokenDefinition::Fungible {
+                name,
+                total_supply,
+                metadata_id: Some(metadata_target_account.account_id),
+            },
+            TokenHolding::Fungible {
+                definition_id: definition_target_account.account_id,
+                balance: total_supply,
+            },
+        ),
+        NewTokenDefinition::NonFungible {
+            name,
+            printable_supply,
+        } => (
+            TokenDefinition::NonFungible {
+                name,
+                printable_supply,
+                metadata_id: metadata_target_account.account_id,
+            },
+            TokenHolding::NftMaster {
+                definition_id: definition_target_account.account_id,
+                print_balance: printable_supply,
+            },
+        ),
+    };
+
+    let token_metadata = TokenMetadata {
+        definition_id: definition_target_account.account_id,
+        standard: metadata.standard,
+        uri: metadata.uri,
+        creators: metadata.creators,
+        primary_sale_date: 0u64, // TODO #261: future works to implement this
+    };
+
+    let mut definition_target_account_post = definition_target_account.account.clone();
+    definition_target_account_post.data = Data::from(&token_definition);
+
+    let mut holding_target_account_post = holding_target_account.account.clone();
+    holding_target_account_post.data = Data::from(&token_holding);
+
+    let mut metadata_target_account_post = metadata_target_account.account.clone();
+    metadata_target_account_post.data = Data::from(&token_metadata);
+
+    vec![
+        AccountPostState::new_claimed(definition_target_account_post),
+        AccountPostState::new_claimed(holding_target_account_post),
+        AccountPostState::new_claimed(metadata_target_account_post),
+    ]
+}

token/src/print_nft.rs

@@ -0,0 +1,54 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata, Data},
+    program::AccountPostState,
+};
+use token_core::TokenHolding;
+
+pub fn print_nft(
+    master_account: AccountWithMetadata,
+    printed_account: AccountWithMetadata,
+) -> Vec<AccountPostState> {
+    assert!(
+        master_account.is_authorized,
+        "Master NFT Account must be authorized"
+    );
+
+    assert_eq!(
+        printed_account.account,
+        Account::default(),
+        "Printed Account must be uninitialized"
+    );
+
+    let mut master_account_data =
+        TokenHolding::try_from(&master_account.account.data).expect("Invalid Token Holding data");
+
+    let TokenHolding::NftMaster {
+        definition_id,
+        print_balance,
+    } = &mut master_account_data
+    else {
+        panic!("Invalid Token Holding provided as NFT Master Account");
+    };
+
+    let definition_id = *definition_id;
+
+    assert!(
+        *print_balance > 1,
+        "Insufficient balance to print another NFT copy"
+    );
+    *print_balance -= 1;
+
+    let mut master_account_post = master_account.account;
+    master_account_post.data = Data::from(&master_account_data);
+
+    let mut printed_account_post = printed_account.account;
+    printed_account_post.data = Data::from(&TokenHolding::NftPrintedCopy {
+        definition_id,
+        owned: true,
+    });
+
+    vec![
+        AccountPostState::new(master_account_post),
+        AccountPostState::new_claimed(printed_account_post),
+    ]
+}

token/src/transfer.rs

@@ -0,0 +1,110 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata, Data},
+    program::AccountPostState,
+};
+use token_core::TokenHolding;
+
+pub fn transfer(
+    sender: AccountWithMetadata,
+    recipient: AccountWithMetadata,
+    balance_to_move: u128,
+) -> Vec<AccountPostState> {
+    assert!(sender.is_authorized, "Sender authorization is missing");
+
+    let mut sender_holding =
+        TokenHolding::try_from(&sender.account.data).expect("Invalid sender data");
+
+    let mut recipient_holding = if recipient.account == Account::default() {
+        TokenHolding::zeroized_clone_from(&sender_holding)
+    } else {
+        TokenHolding::try_from(&recipient.account.data).expect("Invalid recipient data")
+    };
+
+    assert_eq!(
+        sender_holding.definition_id(),
+        recipient_holding.definition_id(),
+        "Sender and recipient definition id mismatch"
+    );
+
+    match (&mut sender_holding, &mut recipient_holding) {
+        (
+            TokenHolding::Fungible {
+                definition_id: _,
+                balance: sender_balance,
+            },
+            TokenHolding::Fungible {
+                definition_id: _,
+                balance: recipient_balance,
+            },
+        ) => {
+            *sender_balance = sender_balance
+                .checked_sub(balance_to_move)
+                .expect("Insufficient balance");
+
+            *recipient_balance = recipient_balance
+                .checked_add(balance_to_move)
+                .expect("Recipient balance overflow");
+        }
+        (
+            TokenHolding::NftMaster {
+                definition_id: _,
+                print_balance: sender_print_balance,
+            },
+            TokenHolding::NftMaster {
+                definition_id: _,
+                print_balance: recipient_print_balance,
+            },
+        ) => {
+            assert_eq!(
+                *recipient_print_balance, 0,
+                "Invalid balance in recipient account for NFT transfer"
+            );
+
+            assert_eq!(
+                *sender_print_balance, balance_to_move,
+                "Invalid balance for NFT Master transfer"
+            );
+
+            std::mem::swap(sender_print_balance, recipient_print_balance);
+        }
+        (
+            TokenHolding::NftPrintedCopy {
+                definition_id: _,
+                owned: sender_owned,
+            },
+            TokenHolding::NftPrintedCopy {
+                definition_id: _,
+                owned: recipient_owned,
+            },
+        ) => {
+            assert_eq!(
+                balance_to_move, 1,
+                "Invalid balance for NFT Printed Copy transfer"
+            );
+
+            assert!(*sender_owned, "Sender does not own the NFT Printed Copy");
+
+            assert!(
+                !*recipient_owned,
+                "Recipient already owns the NFT Printed Copy"
+            );
+
+            *sender_owned = false;
+            *recipient_owned = true;
+        }
+        _ => {
+            panic!("Mismatched token holding types for transfer");
+        }
+    };
+
+    let mut sender_post = sender.account;
+    sender_post.data = Data::from(&sender_holding);
+
+    let mut recipient_post = recipient.account;
+    recipient_post.data = Data::from(&recipient_holding);
+
+    vec![
+        AccountPostState::new(sender_post),
+        AccountPostState::new_claimed_if_default(recipient_post),
+    ]
+}

token/token-idl.json

@@ -0,0 +1,176 @@
+{
+  "version": "0.1.0",
+  "name": "token",
+  "instructions": [
+    {
+      "name": "transfer",
+      "accounts": [
+        {
+          "name": "sender",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "recipient",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "amount_to_transfer",
+          "type": "u128"
+        }
+      ]
+    },
+    {
+      "name": "new_fungible_definition",
+      "accounts": [
+        {
+          "name": "definition_target_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "holding_target_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "name",
+          "type": "string"
+        },
+        {
+          "name": "total_supply",
+          "type": "u128"
+        }
+      ]
+    },
+    {
+      "name": "new_definition_with_metadata",
+      "accounts": [
+        {
+          "name": "definition_target_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "holding_target_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "metadata_target_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "new_definition",
+          "type": {
+            "defined": "NewTokenDefinition"
+          }
+        },
+        {
+          "name": "metadata",
+          "type": {
+            "defined": "Box"
+          }
+        }
+      ]
+    },
+    {
+      "name": "initialize_account",
+      "accounts": [
+        {
+          "name": "definition_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "account_to_initialize",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": []
+    },
+    {
+      "name": "burn",
+      "accounts": [
+        {
+          "name": "definition_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "amount_to_burn",
+          "type": "u128"
+        }
+      ]
+    },
+    {
+      "name": "mint",
+      "accounts": [
+        {
+          "name": "definition_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "user_holding_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": [
+        {
+          "name": "amount_to_mint",
+          "type": "u128"
+        }
+      ]
+    },
+    {
+      "name": "print_nft",
+      "accounts": [
+        {
+          "name": "master_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        },
+        {
+          "name": "printed_account",
+          "writable": false,
+          "signer": false,
+          "init": false
+        }
+      ],
+      "args": []
+    }
+  ],
+  "instruction_type": "token_core::Instruction"
+}

token/token_core/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "token_core"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", features = ["host"] }
+borsh = { version = "1.5", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"] }

token/token_core/src/lib.rs

@@ -0,0 +1,241 @@
+//! This crate contains core data structures and utilities for the Token Program.
+
+use borsh::{BorshDeserialize, BorshSerialize};
+use nssa_core::account::{AccountId, Data};
+use serde::{Deserialize, Serialize};
+
+/// Token Program Instruction.
+#[derive(Serialize, Deserialize)]
+pub enum Instruction {
+    /// Transfer tokens from sender to recipient.
+    ///
+    /// Required accounts:
+    /// - Sender's Token Holding account (authorized),
+    /// - Recipient's Token Holding account.
+    Transfer { amount_to_transfer: u128 },
+
+    /// Create a new fungible token definition without metadata.
+    ///
+    /// Required accounts:
+    /// - Token Definition account (uninitialized),
+    /// - Token Holding account (uninitialized).
+    NewFungibleDefinition { name: String, total_supply: u128 },
+
+    /// Create a new fungible or non-fungible token definition with metadata.
+    ///
+    /// Required accounts:
+    /// - Token Definition account (uninitialized),
+    /// - Token Holding account (uninitialized),
+    /// - Token Metadata account (uninitialized).
+    NewDefinitionWithMetadata {
+        new_definition: NewTokenDefinition,
+        /// Boxed to avoid large enum variant size
+        metadata: Box<NewTokenMetadata>,
+    },
+
+    /// Initialize a token holding account for a given token definition.
+    ///
+    /// Required accounts:
+    /// - Token Definition account (initialized),
+    /// - Token Holding account (uninitialized),
+    InitializeAccount,
+
+    /// Burn tokens from the holder's account.
+    ///
+    /// Required accounts:
+    /// - Token Definition account (initialized),
+    /// - Token Holding account (authorized).
+    Burn { amount_to_burn: u128 },
+
+    /// Mint new tokens to the holder's account.
+    ///
+    /// Required accounts:
+    /// - Token Definition account (authorized),
+    /// - Token Holding account (uninitialized or initialized).
+    Mint { amount_to_mint: u128 },
+
+    /// Print a new NFT from the master copy.
+    ///
+    /// Required accounts:
+    /// - NFT Master Token Holding account (authorized),
+    /// - NFT Printed Copy Token Holding account (uninitialized).
+    PrintNft,
+}
+
+#[derive(Serialize, Deserialize)]
+pub enum NewTokenDefinition {
+    Fungible {
+        name: String,
+        total_supply: u128,
+    },
+    NonFungible {
+        name: String,
+        printable_supply: u128,
+    },
+}
+
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, BorshSerialize, BorshDeserialize)]
+pub enum TokenDefinition {
+    Fungible {
+        name: String,
+        total_supply: u128,
+        metadata_id: Option<AccountId>,
+    },
+    NonFungible {
+        name: String,
+        printable_supply: u128,
+        metadata_id: AccountId,
+    },
+}
+
+impl TryFrom<&Data> for TokenDefinition {
+    type Error = std::io::Error;
+
+    fn try_from(data: &Data) -> Result<Self, Self::Error> {
+        TokenDefinition::try_from_slice(data.as_ref())
+    }
+}
+
+impl From<&TokenDefinition> for Data {
+    fn from(definition: &TokenDefinition) -> Self {
+        // Using size_of_val as size hint for Vec allocation
+        let mut data = Vec::with_capacity(std::mem::size_of_val(definition));
+
+        BorshSerialize::serialize(definition, &mut data)
+            .expect("Serialization to Vec should not fail");
+
+        Data::try_from(data).expect("Token definition encoded data should fit into Data")
+    }
+}
+
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, BorshSerialize, BorshDeserialize)]
+pub enum TokenHolding {
+    Fungible {
+        definition_id: AccountId,
+        balance: u128,
+    },
+    NftMaster {
+        definition_id: AccountId,
+        /// The amount of printed copies left - 1 (1 reserved for master copy itself).
+        print_balance: u128,
+    },
+    NftPrintedCopy {
+        definition_id: AccountId,
+        /// Whether nft is owned by the holder.
+        owned: bool,
+    },
+}
+
+impl TokenHolding {
+    pub fn zeroized_clone_from(other: &Self) -> Self {
+        match other {
+            TokenHolding::Fungible { definition_id, .. } => TokenHolding::Fungible {
+                definition_id: *definition_id,
+                balance: 0,
+            },
+            TokenHolding::NftMaster { definition_id, .. } => TokenHolding::NftMaster {
+                definition_id: *definition_id,
+                print_balance: 0,
+            },
+            TokenHolding::NftPrintedCopy { definition_id, .. } => TokenHolding::NftPrintedCopy {
+                definition_id: *definition_id,
+                owned: false,
+            },
+        }
+    }
+
+    pub fn zeroized_from_definition(
+        definition_id: AccountId,
+        definition: &TokenDefinition,
+    ) -> Self {
+        match definition {
+            TokenDefinition::Fungible { .. } => TokenHolding::Fungible {
+                definition_id,
+                balance: 0,
+            },
+            TokenDefinition::NonFungible { .. } => TokenHolding::NftPrintedCopy {
+                definition_id,
+                owned: false,
+            },
+        }
+    }
+
+    pub fn definition_id(&self) -> AccountId {
+        match self {
+            TokenHolding::Fungible { definition_id, .. } => *definition_id,
+            TokenHolding::NftMaster { definition_id, .. } => *definition_id,
+            TokenHolding::NftPrintedCopy { definition_id, .. } => *definition_id,
+        }
+    }
+}
+
+impl TryFrom<&Data> for TokenHolding {
+    type Error = std::io::Error;
+
+    fn try_from(data: &Data) -> Result<Self, Self::Error> {
+        TokenHolding::try_from_slice(data.as_ref())
+    }
+}
+
+impl From<&TokenHolding> for Data {
+    fn from(holding: &TokenHolding) -> Self {
+        // Using size_of_val as size hint for Vec allocation
+        let mut data = Vec::with_capacity(std::mem::size_of_val(holding));
+
+        BorshSerialize::serialize(holding, &mut data)
+            .expect("Serialization to Vec should not fail");
+
+        Data::try_from(data).expect("Token holding encoded data should fit into Data")
+    }
+}
+
+#[derive(Serialize, Deserialize)]
+pub struct NewTokenMetadata {
+    /// Metadata standard.
+    pub standard: MetadataStandard,
+    /// Pointer to off-chain metadata
+    pub uri: String,
+    /// Creators of the token.
+    pub creators: String,
+}
+
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, BorshSerialize, BorshDeserialize)]
+pub struct TokenMetadata {
+    /// Token Definition account id.
+    pub definition_id: AccountId,
+    /// Metadata standard .
+    pub standard: MetadataStandard,
+    /// Pointer to off-chain metadata.
+    pub uri: String,
+    /// Creators of the token.
+    pub creators: String,
+    /// Block id of primary sale.
+    pub primary_sale_date: u64,
+}
+
+/// Metadata standard defining the expected format of JSON located off-chain.
+#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, BorshSerialize, BorshDeserialize)]
+pub enum MetadataStandard {
+    Simple,
+    Expanded,
+}
+
+impl TryFrom<&Data> for TokenMetadata {
+    type Error = std::io::Error;
+
+    fn try_from(data: &Data) -> Result<Self, Self::Error> {
+        TokenMetadata::try_from_slice(data.as_ref())
+    }
+}
+
+impl From<&TokenMetadata> for Data {
+    fn from(metadata: &TokenMetadata) -> Self {
+        // Using size_of_val as size hint for Vec allocation
+        let mut data = Vec::with_capacity(std::mem::size_of_val(metadata));
+
+        BorshSerialize::serialize(metadata, &mut data)
+            .expect("Serialization to Vec should not fail");
+
+        Data::try_from(data).expect("Token metadata encoded data should fit into Data")
+    }
+}