refactor: split token program into crates

programs/token/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "token_program"
+version = "0.1.0"
+edition = "2024"
+license = { workspace = true }
+
+[dependencies]
+nssa_core.workspace = true
+token_core.workspace = true

programs/token/core/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "token_core"
+version = "0.1.0"
+edition = "2024"
+license = { workspace = true }
+
+[dependencies]
+nssa_core.workspace = true
+serde.workspace = true
+borsh.workspace = true

programs/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")
+    }
+}

programs/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),
+    ]
+}

programs/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),
+    ]
+}

programs/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;

programs/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),
+    ]
+}

programs/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),
+    ]
+}

programs/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),
+    ]
+}

programs/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),
+    ]
+}