lez-programs/programs/token/core/src/lib.rs

//! 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};
use spel_framework_macros::account_type;

/// Token Program Instruction.
#[derive(Serialize, Deserialize)]
pub enum Instruction {
    /// Transfer tokens from sender to recipient.
    ///
    /// Required accounts:
    /// - Sender's Token Holding account (initialized, authorized),
    /// - Recipient's Token Holding account (initialized, or uninitialized with recipient
    ///   authorization in the same transaction).
    Transfer { amount_to_transfer: u128 },

    /// Create a new fungible token definition without metadata.
    ///
    /// `mint_authority` decides the supply model:
    /// - `Some(id)` — `id` may mint additional supply and rotate/renounce the authority,
    /// - `None` — supply is permanently fixed at `total_supply`.
    ///
    /// Required accounts:
    /// - Token Definition account (uninitialized, authorized),
    /// - Token Holding account (uninitialized, authorized).
    NewFungibleDefinition {
        name: String,
        total_supply: u128,
        mint_authority: Option<AccountId>,
    },

    /// Create a new fungible or non-fungible token definition with metadata.
    ///
    /// Required accounts:
    /// - Token Definition account (uninitialized, authorized),
    /// - Token Holding account (uninitialized, authorized),
    /// - Token Metadata account (uninitialized, authorized).
    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, authorized),
    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 under **self/PDA authority**: the
    /// Token Definition account itself is the current mint authority and must be
    /// authorized in this transaction (signer, or a PDA authorized under its
    /// seeds). A definition with no authority has a fixed supply and rejects
    /// minting.
    ///
    /// Required accounts:
    /// - Token Definition account (initialized, authorized as the current mint authority),
    /// - Token Holding account (uninitialized or authorized and initialized).
    Mint { amount_to_mint: u128 },

    /// Mint new tokens under an **external authority**: a distinct authority
    /// account (the account the mint authority was rotated to) authorizes the
    /// mint by signing, while the Token Definition account is mutated but does
    /// not sign. Its account id must match the definition's stored authority.
    ///
    /// Required accounts:
    /// - Token Definition account (initialized),
    /// - Token Holding account (uninitialized or authorized and initialized),
    /// - Authority account (authorized as the current mint authority).
    MintWithAuthority { 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, authorized).
    PrintNft,

    /// Rotate or renounce the mint authority under **self/PDA authority**: the
    /// Token Definition account itself is the current authority and must be
    /// authorized in this transaction. Pass `new_authority: None` to permanently
    /// renounce minting (fixed supply).
    ///
    /// Required accounts:
    /// - Token Definition account (initialized, authorized as the current mint authority).
    SetAuthority { new_authority: Option<AccountId> },

    /// Rotate or renounce the mint authority under an **external authority**: a
    /// distinct authority account (the account the authority was rotated to)
    /// authorizes the change by signing, while the Token Definition account is
    /// mutated but does not sign. Pass `new_authority: None` to permanently renounce.
    ///
    /// Required accounts:
    /// - Token Definition account (initialized),
    /// - Authority account (authorized as the current mint authority).
    SetAuthorityWithAuthority { new_authority: Option<AccountId> },
}

#[derive(Serialize, Deserialize)]
pub enum NewTokenDefinition {
    Fungible {
        name: String,
        total_supply: u128,
        /// Mint authority. `Some(id)` makes the token mintable by `id`; `None`
        /// fixes the supply.
        mint_authority: Option<AccountId>,
    },
    NonFungible {
        name: String,
        printable_supply: u128,
    },
}

#[account_type]
#[derive(Debug, PartialEq, Eq, Serialize, Deserialize, BorshSerialize, BorshDeserialize)]
pub enum TokenDefinition {
    Fungible {
        name: String,
        total_supply: u128,
        metadata_id: Option<AccountId>,
        /// Mint authority slot. `Some(id)` may mint and rotate/renounce;
        /// `None` means the supply is permanently fixed.
        ///
        /// Stored directly as `Option<AccountId>` (Borsh-identical to a custom
        /// authority newtype) so account state stays decodable by `spel inspect`.
        /// The require/rotate/renounce guard logic lives inline in the `mint` and
        /// `set_authority` handlers.
        authority: 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")
    }
}

#[account_type]
#[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,
}

#[account_type]
#[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")
    }
}