refactor: move programs into programs and UIs into apps

This refactors the repository structure as it has grown over time.

programs/ata/Cargo.toml

@@ -0,0 +1,12 @@
+[package]
+name = "ata_program"
+version = "0.1.0"
+edition = "2021"
+
+[lints]
+workspace = true
+
+[dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", tag = "v0.2.0-rc3", features = ["host"] }
+ata_core = { path = "core" }
+token_core = { path = "../token/core" }

programs/ata/core/Cargo.toml

@@ -0,0 +1,13 @@
+[package]
+name = "ata_core"
+version = "0.1.0"
+edition = "2021"
+
+[lints]
+workspace = true
+
+[dependencies]
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", tag = "v0.2.0-rc3", features = ["host"] }
+borsh = { version = "1.5", features = ["derive"] }
+serde = { version = "1.0", features = ["derive"] }
+risc0-zkvm = { version = "=3.0.5", default-features = false }

programs/ata/core/src/lib.rs

@@ -0,0 +1,101 @@
+pub use nssa_core::program::PdaSeed;
+use nssa_core::{
+    account::{AccountId, AccountWithMetadata},
+    program::ProgramId,
+};
+use serde::{Deserialize, Serialize};
+
+#[derive(Serialize, Deserialize)]
+pub enum Instruction {
+    /// Create the Associated Token Account for (token program, owner, definition).
+    /// Idempotent: no-op if the account already exists.
+    ///
+    /// Required accounts (3):
+    /// - Owner account
+    /// - Token definition account
+    /// - Associated token account (default/uninitialized, or already initialized)
+    ///
+    /// `token_program_id` is explicit so callers can support multiple token programs without
+    /// letting account metadata choose downstream code.
+    Create { token_program_id: ProgramId },
+
+    /// Transfer tokens FROM owner's ATA to a recipient token holding account.
+    /// Uses ATA PDA seeds to authorize the chained Token::Transfer call.
+    ///
+    /// Required accounts (3):
+    /// - Owner account (authorized)
+    /// - Sender ATA (owner's token holding)
+    /// - Recipient token holding. Must be:
+    ///   - already initialized (not a default account),
+    ///   - owned by the same token program as the sender ATA,
+    ///   - and point at the same token definition as the sender.
+    ///
+    /// `token_program_id` is explicit so callers can support multiple token programs without
+    /// letting account metadata choose downstream code.
+    Transfer {
+        token_program_id: ProgramId,
+        amount: u128,
+    },
+
+    /// Burn tokens FROM owner's ATA.
+    /// Uses PDA seeds to authorize the ATA in the chained Token::Burn call.
+    ///
+    /// Required accounts (3):
+    /// - Owner account (authorized)
+    /// - Owner's ATA (the holding to burn from)
+    /// - Token definition account
+    ///
+    /// `token_program_id` is explicit so callers can support multiple token programs without
+    /// letting account metadata choose downstream code.
+    Burn {
+        token_program_id: ProgramId,
+        amount: u128,
+    },
+}
+
+pub fn compute_ata_seed(
+    token_program_id: ProgramId,
+    owner_id: AccountId,
+    definition_id: AccountId,
+) -> PdaSeed {
+    use risc0_zkvm::sha::{Impl, Sha256};
+    let mut bytes = [0u8; 96];
+    let (program_id_bytes, rest) = bytes.split_at_mut(32);
+    let (owner_bytes, definition_bytes) = rest.split_at_mut(32);
+    for (chunk, word) in program_id_bytes
+        .chunks_exact_mut(4)
+        .zip(token_program_id.iter())
+    {
+        chunk.copy_from_slice(&word.to_le_bytes());
+    }
+    owner_bytes.copy_from_slice(&owner_id.to_bytes());
+    definition_bytes.copy_from_slice(&definition_id.to_bytes());
+    PdaSeed::new(
+        Impl::hash_bytes(&bytes)
+            .as_bytes()
+            .try_into()
+            .expect("Hash output must be exactly 32 bytes long"),
+    )
+}
+
+pub fn get_associated_token_account_id(ata_program_id: &ProgramId, seed: &PdaSeed) -> AccountId {
+    AccountId::for_public_pda(ata_program_id, seed)
+}
+
+/// Verify the ATA's address matches `(ata_program_id, token_program_id, owner, definition)` and
+/// return the [`PdaSeed`] for use in chained calls.
+pub fn verify_ata_and_get_seed(
+    ata_account: &AccountWithMetadata,
+    owner: &AccountWithMetadata,
+    token_program_id: ProgramId,
+    definition_id: AccountId,
+    ata_program_id: ProgramId,
+) -> PdaSeed {
+    let seed = compute_ata_seed(token_program_id, owner.account_id, definition_id);
+    let expected_id = get_associated_token_account_id(&ata_program_id, &seed);
+    assert_eq!(
+        ata_account.account_id, expected_id,
+        "ATA account ID does not match expected derivation"
+    );
+    seed
+}

programs/ata/methods/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "ata-methods"
+version = "0.1.0"
+edition = "2021"
+
+[lints]
+workspace = true
+
+[build-dependencies]
+risc0-build = "=3.0.5"
+
+[dependencies]
+risc0-zkvm = { version = "=3.0.5", features = ["std"] }
+ata_core = { path = "../core" }
+
+[package.metadata.risc0]
+methods = ["guest"]

programs/ata/methods/build.rs

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

programs/ata/methods/guest/Cargo.toml

@@ -0,0 +1,62 @@
+[package]
+name = "ata-guest"
+version = "0.1.0"
+edition = "2021"
+
+[workspace]
+
+[lints.rust]
+rust_2018_idioms = { level = "deny", priority = -1 }
+# deny (not forbid) so a targeted per-item #[allow] remains possible if ever needed
+unsafe_code = "deny"
+
+[lints.clippy]
+# Deny only the groups where a new lint should always be a hard error.
+# style/pedantic lints default to warn so toolchain upgrades don't break the
+# build unexpectedly — they can be evaluated and addressed at our own pace.
+correctness = { level = "deny", priority = -1 }
+suspicious  = { level = "deny", priority = -1 }
+perf        = { level = "deny", priority = -1 }
+style       = { level = "warn", priority = -1 }
+
+# Generated-code / placeholder blockers.
+dbg_macro = "deny"
+todo = "deny"
+unimplemented = "deny"
+unwrap_used = "deny"
+
+# Lint suppression hygiene.
+allow_attributes = "warn"
+allow_attributes_without_reason = "deny"
+
+# Determinism, panic-safety, and arithmetic correctness.
+arithmetic_side_effects = "deny"
+indexing_slicing = "deny"
+
+# Cast discipline.
+as_conversions = "deny"
+cast_possible_truncation = "deny"
+cast_possible_wrap = "deny"
+cast_sign_loss = "deny"
+
+# API and enum evolution.
+large_enum_variant = "deny"
+wildcard_enum_match_arm = "deny"
+
+# Too noisy for this codebase unless enforced selectively.
+module_name_repetitions = "allow"
+similar_names = "allow"
+
+[[bin]]
+name = "ata"
+path = "src/bin/ata.rs"
+
+[dependencies]
+spel-framework = { git = "https://github.com/logos-co/spel.git", tag = "v0.3.0", package = "spel-framework" }
+nssa_core = { git = "https://github.com/logos-blockchain/logos-execution-zone.git", tag = "v0.2.0-rc3" }
+risc0-zkvm = { version = "=3.0.5", default-features = false }
+ata_core = { path = "../../core" }
+ata_program = { path = "../..", package = "ata_program" }
+token_core = { path = "../../../token/core" }
+serde = { version = "1.0", features = ["derive"] }
+borsh = "1.5"

programs/ata/methods/guest/src/bin/ata.rs

@@ -0,0 +1,89 @@
+#![cfg_attr(not(test), no_main)]
+
+use spel_framework::prelude::*;
+use spel_framework::context::ProgramContext;
+use nssa_core::{account::AccountWithMetadata, program::ProgramId};
+
+#[cfg(not(test))]
+risc0_zkvm::guest::entry!(main);
+
+#[lez_program(instruction = "ata_core::Instruction")]
+mod ata {
+    #[expect(
+        unused_imports,
+        reason = "SPEL instruction macro requires importing parent-scope handler types"
+    )]
+    use super::*;
+
+    /// Create the Associated Token Account for (token program, owner, definition).
+    /// Idempotent: no-op if the account already exists.
+    /// The token program is selected explicitly by `token_program_id`; the token definition and
+    /// any existing ATA occupant must be owned by that program.
+    #[instruction]
+    pub fn create(
+        ctx: ProgramContext,
+        owner: AccountWithMetadata,
+        token_definition: AccountWithMetadata,
+        ata_account: AccountWithMetadata,
+        token_program_id: ProgramId,
+    ) -> SpelResult {
+        let (post_states, chained_calls) = ata_program::create::create_associated_token_account(
+            owner,
+            token_definition,
+            ata_account,
+            ctx.self_program_id,
+            token_program_id,
+        );
+        Ok(spel_framework::SpelOutput::execute(post_states, chained_calls))
+    }
+
+    /// Transfer tokens FROM owner's ATA to a recipient token holding account.
+    /// The token program is selected explicitly by `token_program_id`; the sender ATA and recipient
+    /// holding must be owned by that program.
+    /// The recipient holding must already be initialized, be owned by the same token program
+    /// as the sender ATA, and point at the same token definition as the sender.
+    #[instruction]
+    pub fn transfer(
+        ctx: ProgramContext,
+        owner: AccountWithMetadata,
+        sender_ata: AccountWithMetadata,
+        recipient: AccountWithMetadata,
+        token_program_id: ProgramId,
+        amount: u128,
+    ) -> SpelResult {
+        let (post_states, chained_calls) =
+            ata_program::transfer::transfer_from_associated_token_account(
+                owner,
+                sender_ata,
+                recipient,
+                ctx.self_program_id,
+                token_program_id,
+                amount,
+            );
+        Ok(spel_framework::SpelOutput::execute(post_states, chained_calls))
+    }
+
+    /// Burn tokens FROM owner's ATA.
+    /// The token program is selected explicitly by `token_program_id`; the holder ATA and token
+    /// definition must be owned by that program.
+    #[instruction]
+    pub fn burn(
+        ctx: ProgramContext,
+        owner: AccountWithMetadata,
+        holder_ata: AccountWithMetadata,
+        token_definition: AccountWithMetadata,
+        token_program_id: ProgramId,
+        amount: u128,
+    ) -> SpelResult {
+        let (post_states, chained_calls) =
+            ata_program::burn::burn_from_associated_token_account(
+                owner,
+                holder_ata,
+                token_definition,
+                ctx.self_program_id,
+                token_program_id,
+                amount,
+            );
+        Ok(spel_framework::SpelOutput::execute(post_states, chained_calls))
+    }
+}

programs/ata/methods/src/lib.rs

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

programs/ata/src/burn.rs

@@ -0,0 +1,56 @@
+use nssa_core::{
+    account::AccountWithMetadata,
+    program::{AccountPostState, ChainedCall, ProgramId},
+};
+use token_core::TokenHolding;
+
+pub fn burn_from_associated_token_account(
+    owner: AccountWithMetadata,
+    holder_ata: AccountWithMetadata,
+    token_definition: AccountWithMetadata,
+    ata_program_id: ProgramId,
+    token_program_id: ProgramId,
+    amount: u128,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    assert!(owner.is_authorized, "Owner authorization is missing");
+    assert_eq!(
+        holder_ata.account.program_owner, token_program_id,
+        "Holder ATA must be owned by expected token program"
+    );
+    assert_eq!(
+        token_definition.account.program_owner, token_program_id,
+        "Token definition must be owned by expected token program"
+    );
+    let definition_id = TokenHolding::try_from(&holder_ata.account.data)
+        .expect("Holder ATA must hold a valid token")
+        .definition_id();
+    assert_eq!(
+        definition_id, token_definition.account_id,
+        "Holder ATA token definition does not match"
+    );
+    let seed = ata_core::verify_ata_and_get_seed(
+        &holder_ata,
+        &owner,
+        token_program_id,
+        definition_id,
+        ata_program_id,
+    );
+
+    let post_states = vec![
+        AccountPostState::new(owner.account.clone()),
+        AccountPostState::new(holder_ata.account.clone()),
+        AccountPostState::new(token_definition.account.clone()),
+    ];
+    let mut holder_ata_auth = holder_ata.clone();
+    holder_ata_auth.is_authorized = true;
+
+    let chained_call = ChainedCall::new(
+        token_program_id,
+        vec![token_definition.clone(), holder_ata_auth],
+        &token_core::Instruction::Burn {
+            amount_to_burn: amount,
+        },
+    )
+    .with_pda_seeds(vec![seed]);
+    (post_states, vec![chained_call])
+}

programs/ata/src/create.rs

@@ -0,0 +1,69 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata},
+    program::{AccountPostState, ChainedCall, Claim, ProgramId},
+};
+use token_core::{TokenDefinition, TokenHolding};
+
+pub fn create_associated_token_account(
+    owner: AccountWithMetadata,
+    token_definition: AccountWithMetadata,
+    ata_account: AccountWithMetadata,
+    ata_program_id: ProgramId,
+    token_program_id: ProgramId,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    // No explicit owner authorization check is needed here: ATA creation is idempotent, so the
+    // call itself may proceed without `owner.is_authorized`. If the owner account is still
+    // default, the returned post-state will still carry `Claim::Authorized` so the runtime can
+    // claim that owner account when needed.
+    assert_eq!(
+        token_definition.account.program_owner, token_program_id,
+        "Token definition must be owned by expected token program"
+    );
+    let _definition = TokenDefinition::try_from(&token_definition.account.data)
+        .expect("Token definition must be valid");
+    let seed = ata_core::verify_ata_and_get_seed(
+        &ata_account,
+        &owner,
+        token_program_id,
+        token_definition.account_id,
+        ata_program_id,
+    );
+
+    // Idempotent: already initialized → no-op
+    if ata_account.account != Account::default() {
+        assert_eq!(
+            ata_account.account.program_owner, token_program_id,
+            "Existing ATA must be owned by expected token program"
+        );
+        let holding = TokenHolding::try_from(&ata_account.account.data)
+            .expect("Existing ATA must hold a valid token");
+        assert_eq!(
+            holding.definition_id(),
+            token_definition.account_id,
+            "Existing ATA token definition does not match"
+        );
+        return (
+            vec![
+                AccountPostState::new_claimed_if_default(owner.account.clone(), Claim::Authorized),
+                AccountPostState::new(token_definition.account.clone()),
+                AccountPostState::new(ata_account.account.clone()),
+            ],
+            vec![],
+        );
+    }
+
+    let post_states = vec![
+        AccountPostState::new_claimed_if_default(owner.account.clone(), Claim::Authorized),
+        AccountPostState::new(token_definition.account.clone()),
+        AccountPostState::new(ata_account.account.clone()),
+    ];
+    let mut ata_account_auth = ata_account.clone();
+    ata_account_auth.is_authorized = true;
+    let chained_call = ChainedCall::new(
+        token_program_id,
+        vec![token_definition.clone(), ata_account_auth],
+        &token_core::Instruction::InitializeAccount,
+    )
+    .with_pda_seeds(vec![seed]);
+    (post_states, vec![chained_call])
+}

programs/ata/src/lib.rs

@@ -0,0 +1,10 @@
+//! The Associated Token Account Program implementation.
+
+pub use ata_core as core;
+
+pub mod burn;
+pub mod create;
+pub mod transfer;
+
+#[cfg(test)]
+mod tests;

programs/ata/src/tests.rs

@@ -0,0 +1,467 @@
+use ata_core::{compute_ata_seed, get_associated_token_account_id};
+use nssa_core::{
+    account::{Account, AccountId, AccountWithMetadata, Data},
+    program::{ChainedCall, Claim},
+};
+use token_core::{TokenDefinition, TokenHolding};
+
+const ATA_PROGRAM_ID: nssa_core::program::ProgramId = [1u32; 8];
+const TOKEN_PROGRAM_ID: nssa_core::program::ProgramId = [2u32; 8];
+const OTHER_TOKEN_PROGRAM_ID: nssa_core::program::ProgramId = [3u32; 8];
+
+fn owner_id() -> AccountId {
+    AccountId::new([0x01u8; 32])
+}
+
+fn definition_id() -> AccountId {
+    AccountId::new([0x02u8; 32])
+}
+
+fn ata_id() -> AccountId {
+    get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(TOKEN_PROGRAM_ID, owner_id(), definition_id()),
+    )
+}
+
+fn owner_account() -> AccountWithMetadata {
+    AccountWithMetadata {
+        account: Account::default(),
+        is_authorized: true,
+        account_id: owner_id(),
+    }
+}
+
+fn definition_account() -> AccountWithMetadata {
+    AccountWithMetadata {
+        account: Account {
+            program_owner: TOKEN_PROGRAM_ID,
+            balance: 0,
+            data: Data::from(&TokenDefinition::Fungible {
+                name: "TEST".to_string(),
+                total_supply: 1000,
+                metadata_id: None,
+            }),
+            nonce: nssa_core::account::Nonce(0),
+        },
+        is_authorized: false,
+        account_id: definition_id(),
+    }
+}
+
+fn uninitialized_ata_account() -> AccountWithMetadata {
+    AccountWithMetadata {
+        account: Account::default(),
+        is_authorized: false,
+        account_id: ata_id(),
+    }
+}
+
+fn initialized_ata_account() -> AccountWithMetadata {
+    AccountWithMetadata {
+        account: Account {
+            program_owner: TOKEN_PROGRAM_ID,
+            balance: 0,
+            data: Data::from(&TokenHolding::Fungible {
+                definition_id: definition_id(),
+                balance: 100,
+            }),
+            nonce: nssa_core::account::Nonce(0),
+        },
+        is_authorized: false,
+        account_id: ata_id(),
+    }
+}
+
+#[test]
+fn create_emits_chained_call_for_uninitialized_ata() {
+    let (post_states, chained_calls) = crate::create::create_associated_token_account(
+        owner_account(),
+        definition_account(),
+        uninitialized_ata_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+    );
+
+    assert_eq!(post_states.len(), 3);
+    assert_eq!(post_states[0].required_claim(), Some(Claim::Authorized));
+
+    let mut authorized_ata = uninitialized_ata_account();
+    authorized_ata.is_authorized = true;
+    let expected_call = ChainedCall::new(
+        TOKEN_PROGRAM_ID,
+        vec![definition_account(), authorized_ata],
+        &token_core::Instruction::InitializeAccount,
+    )
+    .with_pda_seeds(vec![compute_ata_seed(
+        TOKEN_PROGRAM_ID,
+        owner_id(),
+        definition_id(),
+    )]);
+
+    assert_eq!(chained_calls, vec![expected_call]);
+}
+
+#[test]
+fn create_is_idempotent_for_initialized_ata() {
+    let (post_states, chained_calls) = crate::create::create_associated_token_account(
+        owner_account(),
+        definition_account(),
+        initialized_ata_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+    );
+
+    assert_eq!(post_states.len(), 3);
+    assert!(
+        chained_calls.is_empty(),
+        "Should emit no chained call for already-initialized ATA"
+    );
+}
+
+#[test]
+#[should_panic(expected = "ATA account ID does not match expected derivation")]
+fn create_panics_on_wrong_ata_address() {
+    let wrong_ata = AccountWithMetadata {
+        account: Account::default(),
+        is_authorized: false,
+        account_id: AccountId::new([0xFFu8; 32]),
+    };
+
+    crate::create::create_associated_token_account(
+        owner_account(),
+        definition_account(),
+        wrong_ata,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+    );
+}
+
+#[test]
+fn get_associated_token_account_id_is_deterministic() {
+    let seed = compute_ata_seed(TOKEN_PROGRAM_ID, owner_id(), definition_id());
+    let id1 = get_associated_token_account_id(&ATA_PROGRAM_ID, &seed);
+    let id2 = get_associated_token_account_id(&ATA_PROGRAM_ID, &seed);
+    assert_eq!(id1, id2);
+}
+
+#[test]
+fn get_associated_token_account_id_differs_by_token_program() {
+    let id1 = get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(TOKEN_PROGRAM_ID, owner_id(), definition_id()),
+    );
+    let id2 = get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(OTHER_TOKEN_PROGRAM_ID, owner_id(), definition_id()),
+    );
+    assert_ne!(id1, id2);
+}
+
+#[test]
+fn get_associated_token_account_id_differs_by_owner() {
+    let other_owner = AccountId::new([0x99u8; 32]);
+    let id1 = get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(TOKEN_PROGRAM_ID, owner_id(), definition_id()),
+    );
+    let id2 = get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(TOKEN_PROGRAM_ID, other_owner, definition_id()),
+    );
+    assert_ne!(id1, id2);
+}
+
+#[test]
+fn get_associated_token_account_id_differs_by_definition() {
+    let other_def = AccountId::new([0x99u8; 32]);
+    let id1 = get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(TOKEN_PROGRAM_ID, owner_id(), definition_id()),
+    );
+    let id2 = get_associated_token_account_id(
+        &ATA_PROGRAM_ID,
+        &compute_ata_seed(TOKEN_PROGRAM_ID, owner_id(), other_def),
+    );
+    assert_ne!(id1, id2);
+}
+
+#[test]
+#[should_panic(expected = "Token definition must be owned by expected token program")]
+fn create_panics_when_definition_is_owned_by_unexpected_token_program() {
+    let mut definition = definition_account();
+    definition.account.program_owner = OTHER_TOKEN_PROGRAM_ID;
+
+    crate::create::create_associated_token_account(
+        owner_account(),
+        definition,
+        uninitialized_ata_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Existing ATA must be owned by expected token program")]
+fn create_panics_when_existing_ata_is_owned_by_unexpected_token_program() {
+    let mut ata = initialized_ata_account();
+    ata.account.program_owner = OTHER_TOKEN_PROGRAM_ID;
+
+    crate::create::create_associated_token_account(
+        owner_account(),
+        definition_account(),
+        ata,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Existing ATA token definition does not match")]
+fn create_panics_when_existing_ata_definition_mismatches_requested_definition() {
+    let mut ata = initialized_ata_account();
+    ata.account.data = Data::from(&TokenHolding::Fungible {
+        definition_id: AccountId::new([0xAAu8; 32]),
+        balance: 100,
+    });
+
+    crate::create::create_associated_token_account(
+        owner_account(),
+        definition_account(),
+        ata,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+    );
+}
+
+fn recipient_id() -> AccountId {
+    AccountId::new([0x03u8; 32])
+}
+
+fn initialized_recipient_account() -> AccountWithMetadata {
+    AccountWithMetadata {
+        account: Account {
+            program_owner: TOKEN_PROGRAM_ID,
+            balance: 0,
+            data: Data::from(&TokenHolding::Fungible {
+                definition_id: definition_id(),
+                balance: 0,
+            }),
+            nonce: nssa_core::account::Nonce(0),
+        },
+        is_authorized: false,
+        account_id: recipient_id(),
+    }
+}
+
+#[test]
+fn transfer_emits_chained_call_for_initialized_recipient() {
+    let (post_states, chained_calls) = crate::transfer::transfer_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        initialized_recipient_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        25,
+    );
+
+    assert_eq!(post_states.len(), 3);
+    assert_eq!(chained_calls.len(), 1);
+
+    let mut sender_auth = initialized_ata_account();
+    sender_auth.is_authorized = true;
+    let expected_call = ChainedCall::new(
+        TOKEN_PROGRAM_ID,
+        vec![sender_auth, initialized_recipient_account()],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: 25,
+        },
+    )
+    .with_pda_seeds(vec![compute_ata_seed(
+        TOKEN_PROGRAM_ID,
+        owner_id(),
+        definition_id(),
+    )]);
+
+    assert_eq!(chained_calls, vec![expected_call]);
+}
+
+#[test]
+#[should_panic(expected = "Owner authorization is missing")]
+fn transfer_panics_when_owner_not_authorized() {
+    let mut unauthorized_owner = owner_account();
+    unauthorized_owner.is_authorized = false;
+
+    crate::transfer::transfer_from_associated_token_account(
+        unauthorized_owner,
+        initialized_ata_account(),
+        initialized_recipient_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Recipient token holding must be initialized")]
+fn transfer_panics_when_recipient_is_default() {
+    let default_recipient = AccountWithMetadata {
+        account: Account::default(),
+        is_authorized: false,
+        account_id: recipient_id(),
+    };
+
+    crate::transfer::transfer_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        default_recipient,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Sender ATA must be owned by expected token program")]
+fn transfer_panics_when_sender_ata_is_owned_by_unexpected_token_program() {
+    let mut sender = initialized_ata_account();
+    sender.account.program_owner = OTHER_TOKEN_PROGRAM_ID;
+
+    crate::transfer::transfer_from_associated_token_account(
+        owner_account(),
+        sender,
+        initialized_recipient_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Recipient must be owned by the same token program as the sender ATA")]
+fn transfer_panics_when_recipient_is_foreign_owned() {
+    let mut foreign_recipient = initialized_recipient_account();
+    foreign_recipient.account.program_owner = [9u32; 8];
+
+    crate::transfer::transfer_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        foreign_recipient,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Recipient must hold a valid token")]
+fn transfer_panics_when_recipient_data_is_malformed() {
+    let mut malformed_recipient = initialized_recipient_account();
+    malformed_recipient.account.data = Data::try_from(vec![0xFFu8, 0xFE, 0xFD]).unwrap();
+
+    crate::transfer::transfer_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        malformed_recipient,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Recipient and sender token definitions do not match")]
+fn transfer_panics_when_recipient_definition_mismatches_sender() {
+    let mut mismatched_recipient = initialized_recipient_account();
+    mismatched_recipient.account.data = Data::from(&TokenHolding::Fungible {
+        definition_id: AccountId::new([0xAAu8; 32]),
+        balance: 0,
+    });
+
+    crate::transfer::transfer_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        mismatched_recipient,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+fn burn_emits_chained_call_for_initialized_ata() {
+    let (post_states, chained_calls) = crate::burn::burn_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        definition_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        25,
+    );
+
+    assert_eq!(post_states.len(), 3);
+    assert_eq!(chained_calls.len(), 1);
+
+    let mut holder_auth = initialized_ata_account();
+    holder_auth.is_authorized = true;
+    let expected_call = ChainedCall::new(
+        TOKEN_PROGRAM_ID,
+        vec![definition_account(), holder_auth],
+        &token_core::Instruction::Burn { amount_to_burn: 25 },
+    )
+    .with_pda_seeds(vec![compute_ata_seed(
+        TOKEN_PROGRAM_ID,
+        owner_id(),
+        definition_id(),
+    )]);
+
+    assert_eq!(chained_calls, vec![expected_call]);
+}
+
+#[test]
+#[should_panic(expected = "Holder ATA must be owned by expected token program")]
+fn burn_panics_when_holder_ata_is_owned_by_unexpected_token_program() {
+    let mut holder = initialized_ata_account();
+    holder.account.program_owner = OTHER_TOKEN_PROGRAM_ID;
+
+    crate::burn::burn_from_associated_token_account(
+        owner_account(),
+        holder,
+        definition_account(),
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Token definition must be owned by expected token program")]
+fn burn_panics_when_definition_is_owned_by_unexpected_token_program() {
+    let mut definition = definition_account();
+    definition.account.program_owner = OTHER_TOKEN_PROGRAM_ID;
+
+    crate::burn::burn_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        definition,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}
+
+#[test]
+#[should_panic(expected = "Holder ATA token definition does not match")]
+fn burn_panics_when_holder_definition_mismatches_supplied_definition() {
+    let mut definition = definition_account();
+    definition.account_id = AccountId::new([0xBBu8; 32]);
+
+    crate::burn::burn_from_associated_token_account(
+        owner_account(),
+        initialized_ata_account(),
+        definition,
+        ATA_PROGRAM_ID,
+        TOKEN_PROGRAM_ID,
+        1,
+    );
+}

programs/ata/src/transfer.rs

@@ -0,0 +1,71 @@
+use nssa_core::{
+    account::{Account, AccountWithMetadata},
+    program::{AccountPostState, ChainedCall, ProgramId},
+};
+use token_core::TokenHolding;
+
+pub fn transfer_from_associated_token_account(
+    owner: AccountWithMetadata,
+    sender_ata: AccountWithMetadata,
+    recipient: AccountWithMetadata,
+    ata_program_id: ProgramId,
+    token_program_id: ProgramId,
+    amount: u128,
+) -> (Vec<AccountPostState>, Vec<ChainedCall>) {
+    assert!(owner.is_authorized, "Owner authorization is missing");
+    assert_eq!(
+        sender_ata.account.program_owner, token_program_id,
+        "Sender ATA must be owned by expected token program"
+    );
+    let sender_definition_id = TokenHolding::try_from(&sender_ata.account.data)
+        .expect("Sender ATA must hold a valid token")
+        .definition_id();
+    let sender_seed = ata_core::verify_ata_and_get_seed(
+        &sender_ata,
+        &owner,
+        token_program_id,
+        sender_definition_id,
+        ata_program_id,
+    );
+
+    // The recipient contract: ATA::Transfer requires a recipient token holding that is already
+    // initialized, owned by the same token program as the sender ATA, and that points at the same
+    // token definition as the sender. Anything else fails here rather than being silently
+    // materialized by the downstream token transfer (e.g. via `Claim::Authorized` on a default
+    // recipient), so integrators get an ATA-level failure rather than having to reverse-engineer
+    // token/runtime semantics.
+    assert_ne!(
+        recipient.account,
+        Account::default(),
+        "Recipient token holding must be initialized"
+    );
+    assert_eq!(
+        recipient.account.program_owner, token_program_id,
+        "Recipient must be owned by the same token program as the sender ATA"
+    );
+    let recipient_definition_id = TokenHolding::try_from(&recipient.account.data)
+        .expect("Recipient must hold a valid token")
+        .definition_id();
+    assert_eq!(
+        recipient_definition_id, sender_definition_id,
+        "Recipient and sender token definitions do not match"
+    );
+
+    let post_states = vec![
+        AccountPostState::new(owner.account.clone()),
+        AccountPostState::new(sender_ata.account.clone()),
+        AccountPostState::new(recipient.account.clone()),
+    ];
+    let mut sender_ata_auth = sender_ata.clone();
+    sender_ata_auth.is_authorized = true;
+
+    let chained_call = ChainedCall::new(
+        token_program_id,
+        vec![sender_ata_auth, recipient],
+        &token_core::Instruction::Transfer {
+            amount_to_transfer: amount,
+        },
+    )
+    .with_pda_seeds(vec![sender_seed]);
+    (post_states, vec![chained_call])
+}