pinocchio_tkn/

lib.rs

//! # pinocchio-tkn
//!
//! **The complete Token toolkit for Pinocchio programs on Solana.**
//!
//! `pinocchio-tkn` provides zero-copy, zero-allocation CPI helpers for both SPL Token (legacy)
//! and Token-2022 programs, with full support for Token-2022 extensions.
//!
//! ## Features
//!
//! - **Complete Coverage**: 60 instructions across SPL Token and Token-2022
//!   - 19 common instructions (work with both programs)
//!   - 41 Token-2022 exclusive extension instructions
//! - **All 22 Token-2022 Extensions**: Full implementation of 19 extensions, documented stubs for 3 confidential extensions
//! - **Unified API**: Single interface for both SPL Token and Token-2022
//! - **Zero Allocations**: Stack-only operations, perfect for Solana's compute budget
//! - **Type-Safe**: Builder-style APIs with compile-time guarantees
//! - **State Parsing**: Zero-copy deserialization of Mint and TokenAccount data
//! - **Comprehensive Helpers**: Calculations, validations, and detection utilities
//! - **Production Ready**: Extensively tested with 100+ integration and E2E tests
//!
//! ## Why pinocchio-tkn?
//!
//! While official packages are fragmented across multiple crates:
//! - `pinocchio-token`: Legacy SPL Token only
//! - `pinocchio-token-2022`: Core instructions only, no extensions
//! - No unified interface between the two
//!
//! `pinocchio-tkn` unifies everything into a single, complete package with a consistent API.
//!
//! ## Quick Start
//!
//! Add to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! pinocchio-tkn = "0.2"
//! ```
//!
//! ### Basic Transfer
//!
//! ```rust,ignore
//! # fn main() -> pinocchio::ProgramResult {
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio_tkn::prelude::*;
//! # let source: &AccountInfo = todo!();
//! # let destination: &AccountInfo = todo!();
//! # let authority: &AccountInfo = todo!();
//! // Works with both SPL Token and Token-2022
//! // Defaults to Token-2022 if program_id is None
//! Transfer {
//!     source,
//!     destination,
//!     authority,
//!     amount: 1_000_000,
//!     program_id: None,
//! }.invoke()?;
//! # Ok(())
//! # }
//! ```
//!
//! ### Using Token-2022 Extensions
//!
//! ```rust,ignore
//! use pinocchio::account_info::AccountInfo;
//! use pinocchio_tkn::prelude::*;
//! use pinocchio_tkn::extensions::*;
//!
//! // Initialize a mint with transfer fees
//! InitializeTransferFeeConfig {
//!     mint,
//!     transfer_fee_config_authority: Some(authority_key),
//!     withdraw_withheld_authority: Some(authority_key),
//!     transfer_fee_basis_points: 100,  // 1%
//!     maximum_fee: 5000,
//! }.invoke()?;
//!
//! // Transfer with fees
//! TransferCheckedWithFee {
//!     source,
//!     mint,
//!     destination,
//!     authority,
//!     amount: 1_000_000,
//!     decimals: 9,
//!     fee: 10_000,
//! }.invoke()?;
//! ```
//!
//! ### State Parsing
//!
//! ```rust,ignore
//! # fn main() -> pinocchio::ProgramResult {
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio::program_error::ProgramError;
//! # use pinocchio_tkn::state::{Mint, TokenAccount};
//! # let mint_account: &AccountInfo = todo!();
//! # let account: &AccountInfo = todo!();
//! # let required_amount: u64 = 1;
//! // Zero-copy parsing of account data
//! let mint = Mint::from_account_info(&mint_account)?;
//! let supply = mint.supply();
//! let decimals = mint.decimals();
//!
//! let token_account = TokenAccount::from_account_info(&account)?;
//! if token_account.amount() < required_amount {
//!     return Err(ProgramError::InsufficientFunds);
//! }
//! # Ok(())
//! # }
//! ```
//!
//! ## Module Organization
//!
//! The crate is organized into feature-gated modules:
//!
//! - [`common`]: Instructions that work with both SPL Token and Token-2022 (19 instructions)
//! - [`extensions`]: Token-2022 exclusive extensions (41 instructions across 22 extensions)
//! - [`state`]: Zero-copy state parsing for Mint and TokenAccount
//! - [`helpers`]: Utility functions for calculations, validation, and detection
//! - [`prelude`]: Convenient re-exports of commonly used items
//!
//! ## Architecture Overview
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────────┐
//! │                      pinocchio-tkn                          │
//! ├─────────────────────────────────────────────────────────────┤
//! │                                                             │
//! │  ┌───────────┐  ┌──────────────┐  ┌───────┐  ┌─────────┐ │
//! │  │  common   │  │  extensions  │  │ state │  │ helpers │ │
//! │  ├───────────┤  ├──────────────┤  ├───────┤  ├─────────┤ │
//! │  │Transfer   │  │TransferFee   │  │ Mint  │  │  calc   │ │
//! │  │MintTo     │  │Metadata      │  │Token  │  │  valid  │ │
//! │  │Burn       │  │Interest      │  │Account│  │ detect  │ │
//! │  │Approve    │  │Pointers      │  └───────┘  └─────────┘ │
//! │  │...        │  │Misc (13+)    │                          │
//! │  └───────────┘  └──────────────┘                          │
//! │                                                             │
//! ├─────────────────────────────────────────────────────────────┤
//! │              Pinocchio (zero-alloc runtime)                │
//! ├─────────────────────────────────────────────────────────────┤
//! │         SPL Token          │      Token-2022               │
//! │   (TokenkegQfe...VQ5DA)   │  (TokenzQdBNb...xuEb)        │
//! └─────────────────────────────────────────────────────────────┘
//! ```
//!
//! ## Feature Flags
//!
//! The crate uses granular feature flags for optimal compile times and binary size:
//!
//! ```toml
//! # Default features (most commonly used)
//! default = ["common", "state", "helpers"]
//!
//! # Core features
//! common = ["state"]        # Common instructions (both programs)
//! state = []                 # State parsing (Mint, TokenAccount)
//! helpers = []               # Calculation & validation utilities
//!
//! # Extension groups (Token-2022 only)
//! ext-transfer-fee = []      # Transfer fee instructions (6)
//! ext-metadata = []          # On-chain metadata (5)
//! ext-interest = []          # Interest-bearing tokens (2)
//! ext-pointers = []          # Metadata/Group/Hook pointers (8)
//! ext-misc = []              # CPI Guard, Memo, Pause, etc (13)
//!
//! # Convenience features
//! extensions = [             # All Token-2022 extensions
//!     "ext-transfer-fee",
//!     "ext-metadata",
//!     "ext-interest",
//!     "ext-pointers",
//!     "ext-misc"
//! ]
//! full = [                   # Everything
//!     "common",
//!     "state",
//!     "helpers",
//!     "extensions"
//! ]
//! ```
//!
//! ## Security Considerations
//!
//! When building Solana programs with token operations, always:
//!
//! 1. **Validate account ownership**: Use [`helpers::assert_owned_by`] to ensure accounts
//!    are owned by the correct token program
//! 2. **Check account state**: Use [`helpers::assert_is_mint`] and [`helpers::assert_is_token_account`]
//!    to validate account structure
//! 3. **Verify authorities**: Use [`helpers::assert_mint_authority`] and similar validators
//! 4. **Handle frozen accounts**: Check [`helpers::assert_account_not_frozen`] before transfers
//! 5. **Validate amounts**: Use `TransferChecked` instead of `Transfer` to verify decimals
//!
//! ## Token-2022 Extension Coverage
//!
//! ### Fully Implemented (19 extensions, 42 instructions)
//!
//! - **Transfer Fee** (6 instructions): Assess fees on transfers
//! - **Metadata Pointer** (2): Point to on-chain or off-chain metadata
//! - **Token Metadata** (5): Store name, symbol, URI on-chain
//! - **Transfer Hook** (2): Custom program hooks on transfers
//! - **Group Pointer** (2): Token collection/grouping
//! - **Group Member Pointer** (2): Collection membership
//! - **Default Account State** (2): Auto-freeze new accounts
//! - **Permanent Delegate** (1): Immutable delegate authority
//! - **Non-Transferable** (1): Soul-bound tokens
//! - **Interest Bearing** (2): Accrue interest over time
//! - **CPI Guard** (2): Prevent CPI access to accounts
//! - **Memo Transfer** (2): Require memos on transfers
//! - **Pausable** (3): Pause/resume all token operations
//! - **Scaled UI Amount** (2): Non-standard decimal display
//! - **Mint Close Authority** (1): Allow mints to be closed
//! - **Immutable Owner** (1): Prevent ownership changes
//! - **Reallocate** (1): Resize accounts for new extensions
//! - **Withdraw Excess Lamports** (1): Clean up account rent
//!
//! ### Documented (3 extensions - ZK proof required)
//!
//! These extensions require zero-knowledge cryptography and are provided as
//! documented stubs with full explanations:
//!
//! - **Confidential Transfer**: Private balance transfers using ElGamal encryption
//! - **Confidential Transfer Fee**: Fee collection with confidential amounts
//! - **Confidential Mint/Burn**: Private minting and burning operations
//!
//! ## Performance
//!
//! All operations are designed for Solana's constrained environment:
//!
//! - **Zero heap allocations**: All data structures are stack-allocated
//! - **Minimal compute units**: Optimized instruction building
//! - **Compile-time optimizations**: Extensive use of `#[inline]` and const functions
//! - **Small binary size**: Granular feature flags reduce code size
//!
//! ## Usage Guides
//!
//! ### A. Basic Token Creation (SPL Token & Token-2022)
//!
//! Creating a simple token without extensions works with both programs:
//!
//! ```rust,ignore
//! # fn main() -> pinocchio::ProgramResult {
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio::pubkey::Pubkey;
//! use pinocchio_tkn::prelude::*;
//! use pinocchio::system::CreateAccount;
//! # let payer: &AccountInfo = todo!();
//! # let mint: &AccountInfo = todo!();
//! # let authority: &AccountInfo = todo!();
//! # let mint_authority: &Pubkey = todo!();
//! # let freeze_authority: &Pubkey = todo!();
//! # let user_token_account: &AccountInfo = todo!();
//! # let user: &AccountInfo = todo!();
//! # let user_owner: &Pubkey = todo!();
//! # let recipient_token_account: &AccountInfo = todo!();
//!
//! // Step 1: Create and allocate the mint account
//! // For SPL Token or Token-2022 without extensions, mint size is 82 bytes
//! let mint_space = 82;
//! let rent_lamports = 0; /* calculate rent for 82 bytes */
//!
//! // Create the mint account (using system program)
//! CreateAccount {
//!     from: payer,
//!     to: mint,
//!     lamports: rent_lamports,
//!     space: mint_space,
//!     owner: &TOKEN_2022_PROGRAM_ID, // or &TOKEN_PROGRAM_ID for legacy
//! }.invoke()?;
//!
//! // Step 2: Initialize the mint
//! InitializeMint2 {
//!     mint,
//!     mint_authority,
//!     freeze_authority: Some(freeze_authority),
//!     decimals: 9, // 9 decimals like SOL
//! }.invoke()?;
//!
//! // Step 3: Create a token account for a user
//! let account_space = 165;
//! let account_rent = 0; /* calculate rent for 165 bytes */
//!
//! CreateAccount {
//!     from: payer,
//!     to: user_token_account,
//!     lamports: account_rent,
//!     space: account_space,
//!     owner: &TOKEN_2022_PROGRAM_ID,
//! }.invoke()?;
//!
//! InitializeAccount3 {
//!     account: user_token_account,
//!     mint,
//!     owner: user_owner,
//! }.invoke()?;
//!
//! // Step 4: Mint tokens to the user
//! MintToChecked {
//!     mint,
//!     account: user_token_account,
//!     mint_authority: authority,
//!     amount: 1_000_000_000, // 1 token with 9 decimals
//!     decimals: 9,
//! }.invoke()?;
//!
//! // Step 5: Transfer tokens between accounts
//! TransferChecked {
//!     source: user_token_account,
//!     mint,
//!     destination: recipient_token_account,
//!     authority: user,
//!     amount: 100_000_000, // 0.1 token
//!     decimals: 9,
//! }.invoke()?;
//! # Ok(())
//! # }
//! ```
//!
//! **Key Points:**
//! - Use `InitializeMint2` (preferred) instead of `InitializeMint` for cleaner API
//! - Use `InitializeAccount3` (preferred) for token accounts
//! - Always use "Checked" variants (`MintToChecked`, `TransferChecked`) for safety
//! - Program ID (`TOKEN_PROGRAM_ID` vs `TOKEN_2022_PROGRAM_ID`) must match account owner
//!
//! ### B. Token-2022 with Single Extension
//!
//! Adding transfer fees to a token:
//!
//! ```rust,ignore
//! # fn main() -> pinocchio::ProgramResult {
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio::pubkey::Pubkey;
//! use pinocchio_tkn::prelude::*;
//! use pinocchio_tkn::helpers::{mint_space_for_extensions, ExtensionType, account_space_for_extensions};
//! use pinocchio::system::CreateAccount;
//! # let payer: &AccountInfo = todo!();
//! # let mint: &AccountInfo = todo!();
//! # let authority: &AccountInfo = todo!();
//! # let authority_key: &Pubkey = todo!();
//! # let mint_authority: &Pubkey = todo!();
//! # let freeze_authority: &Pubkey = todo!();
//! # let user: &AccountInfo = todo!();
//! # let user_owner: &Pubkey = todo!();
//! # let user_account: &AccountInfo = todo!();
//! # let recipient_account: &AccountInfo = todo!();
//! # let fee_vault: &AccountInfo = todo!();
//!
//! // Step 1: Calculate space needed for mint with TransferFeeConfig extension
//! let extensions = &[ExtensionType::TransferFeeConfig];
//! let mint_space = mint_space_for_extensions(extensions);
//! // Result: 82 (base) + 3 (header) + 108 (fee config) = 193 bytes
//!
//! let rent_lamports = 0; /* calculate rent for mint_space */
//!
//! // Step 2: Create the mint account with correct size
//! CreateAccount {
//!     from: payer,
//!     to: mint,
//!     lamports: rent_lamports,
//!     space: mint_space,
//!     owner: &TOKEN_2022_PROGRAM_ID, // Must use Token-2022 for extensions!
//! }.invoke()?;
//!
//! // Step 3: Initialize the TransferFee extension BEFORE initializing the mint
//! InitializeTransferFeeConfig {
//!     mint,
//!     transfer_fee_config_authority: Some(authority_key),
//!     withdraw_withheld_authority: Some(authority_key),
//!     transfer_fee_basis_points: 100, // 1% fee (100 basis points)
//!     maximum_fee: 5_000_000, // 0.005 token max fee (with 9 decimals)
//! }.invoke()?;
//!
//! // Step 4: NOW initialize the mint (after extensions)
//! InitializeMint2 {
//!     mint,
//!     mint_authority,
//!     freeze_authority: Some(freeze_authority),
//!     decimals: 9,
//! }.invoke()?;
//!
//! // Step 5: Create token accounts (inherit TransferFeeAmount extension)
//! let account_extensions = &[ExtensionType::TransferFeeConfig];
//! let account_space = account_space_for_extensions(account_extensions);
//! // Accounts automatically get TransferFeeAmount extension
//! let account_rent = 0;
//!
//! CreateAccount {
//!     from: payer,
//!     to: user_account,
//!     lamports: account_rent,
//!     space: account_space,
//!     owner: &TOKEN_2022_PROGRAM_ID,
//! }.invoke()?;
//!
//! InitializeAccount3 {
//!     account: user_account,
//!     mint,
//!     owner: user_owner,
//! }.invoke()?;
//!
//! // Step 6: Transfer with fees
//! use pinocchio_tkn::helpers::calculate_transfer_fee;
//! let amount = 100_000_000; // 0.1 token
//! let fee = calculate_transfer_fee(amount, 100, 5_000_000); // Calculate fee first
//!
//! TransferCheckedWithFee {
//!     source: user_account,
//!     mint,
//!     destination: recipient_account,
//!     authority: user,
//!     amount,
//!     decimals: 9,
//!     fee, // Must provide calculated fee
//! }.invoke()?;
//!
//! // Step 7: Withdraw collected fees (authority only)
//! WithdrawWithheldTokensFromAccounts {
//!     mint,
//!     destination: fee_vault,
//!     withdraw_withheld_authority: authority,
//!     sources: &[user_account, recipient_account], // Accounts to withdraw from
//! }.invoke()?;
//! # Ok(())
//! # }
//! ```
//!
//! **Critical Order:**
//! 1. Calculate space with extensions
//! 2. Create account with correct size
//! 3. Initialize extensions FIRST
//! 4. Initialize mint LAST
//!
//! ### C. Token-2022 with Multiple Extensions (Advanced)
//!
//! Creating a premium token with Transfer Fees + Metadata + Mint Close Authority:
//!
//! ```rust,ignore
//! # fn main() -> pinocchio::ProgramResult {
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio::pubkey::Pubkey;
//! use pinocchio_tkn::prelude::*;
//! use pinocchio_tkn::helpers::{mint_space_for_extensions, ExtensionType, account_space_for_extensions};
//! use pinocchio::system::CreateAccount;
//! # let payer: &AccountInfo = todo!();
//! # let mint: &AccountInfo = todo!();
//! # let mint_key: &Pubkey = todo!();
//! # let authority: &AccountInfo = todo!();
//! # let authority_key: &Pubkey = todo!();
//! # let mint_authority: &Pubkey = todo!();
//! # let freeze_authority: &Pubkey = todo!();
//! # let user: &AccountInfo = todo!();
//! # let user_owner: &Pubkey = todo!();
//! # let user_account: &AccountInfo = todo!();
//!
//! // Step 1: Calculate space for ALL extensions
//! let extensions = &[
//!     ExtensionType::TransferFeeConfig,    // 108 bytes
//!     ExtensionType::MetadataPointer,      // 32 bytes
//!     ExtensionType::MintCloseAuthority,   // 32 bytes
//! ];
//! let mint_space = mint_space_for_extensions(extensions);
//! // = 82 + 3 + 108 + 32 + 32 = 257 bytes
//!
//! let rent_lamports = 0; /* calculate rent */
//!
//! // Step 2: Create mint account
//! CreateAccount {
//!     from: payer,
//!     to: mint,
//!     lamports: rent_lamports,
//!     space: mint_space,
//!     owner: &TOKEN_2022_PROGRAM_ID,
//! }.invoke()?;
//!
//! // Step 3a: Initialize TransferFee extension
//! InitializeTransferFeeConfig {
//!     mint,
//!     transfer_fee_config_authority: Some(authority_key),
//!     withdraw_withheld_authority: Some(authority_key),
//!     transfer_fee_basis_points: 50, // 0.5%
//!     maximum_fee: 10_000_000,
//! }.invoke()?;
//!
//! // Step 3b: Initialize MetadataPointer extension
//! InitializeMetadataPointer {
//!     mint,
//!     authority: Some(authority_key),
//!     metadata_address: Some(mint_key), // Store metadata on the mint itself
//! }.invoke()?;
//!
//! // Step 3c: Initialize MintCloseAuthority extension
//! InitializeMintCloseAuthority {
//!     mint,
//!     close_authority: Some(authority_key),
//! }.invoke()?;
//!
//! // Step 4: Initialize the mint (AFTER all extensions)
//! InitializeMint2 {
//!     mint,
//!     mint_authority,
//!     freeze_authority: Some(freeze_authority),
//!     decimals: 6, // USDC-style decimals
//! }.invoke()?;
//!
//! // Step 5: Initialize on-mint metadata (AFTER mint initialization)
//! InitializeTokenMetadata {
//!     metadata: mint, // Using the mint itself as metadata storage
//!     update_authority: authority,
//!     mint,
//!     mint_authority: authority,
//!     name: "Premium Token",
//!     symbol: "PREM",
//!     uri: "https://example.com/premium-token.json",
//! }.invoke()?;
//!
//! // Step 6: Create token accounts (with inherited extensions)
//! let account_space = account_space_for_extensions(extensions);
//! let account_rent = 0;
//!
//! CreateAccount {
//!     from: payer,
//!     to: user_account,
//!     lamports: account_rent,
//!     space: account_space,
//!     owner: &TOKEN_2022_PROGRAM_ID,
//! }.invoke()?;
//!
//! InitializeAccount3 {
//!     account: user_account,
//!     mint,
//!     owner: user_owner,
//! }.invoke()?;
//!
//! // Step 7: Use the token normally
//! MintToChecked {
//!     mint,
//!     account: user_account,
//!     mint_authority: authority,
//!     amount: 1_000_000, // 1 PREM
//!     decimals: 6,
//! }.invoke()?;
//!
//! // Step 8: Later, close the mint when done (requires MintCloseAuthority)
//! // First, burn all supply...
//! // Then close the mint:
//! CloseAccount {
//!     account: mint,
//!     destination: authority, // Rent refund destination
//!     authority,
//! }.invoke()?;
//! # Ok(())
//! # }
//! ```
//!
//! **Extension Initialization Order Rules:**
//!
//! ```text
//! ┌─────────────────────────────────────────────────────────┐
//! │ BEFORE InitializeMint2:                                 │
//! │ - TransferFeeConfig                                     │
//! │ - MetadataPointer                                       │
//! │ - GroupPointer                                          │
//! │ - GroupMemberPointer                                    │
//! │ - TransferHook                                          │
//! │ - InterestBearingConfig                                 │
//! │ - PermanentDelegate                                     │
//! │ - NonTransferableMint                                   │
//! │ - MintCloseAuthority                                    │
//! │ - DefaultAccountState                                   │
//! │ - Pausable                                              │
//! │ - ScaledUiAmount                                        │
//! └─────────────────────────────────────────────────────────┘
//!                           ↓
//! ┌─────────────────────────────────────────────────────────┐
//! │ InitializeMint2 or InitializeMint                       │
//! └─────────────────────────────────────────────────────────┘
//!                           ↓
//! ┌─────────────────────────────────────────────────────────┐
//! │ AFTER InitializeMint2:                                  │
//! │ - InitializeTokenMetadata (if using MetadataPointer)    │
//! └─────────────────────────────────────────────────────────┘
//! ```
//!
//! ### D. Common Patterns
//!
//! #### Detecting Which Program a Token Uses
//!
//! ```rust,ignore
//! # use pinocchio::account_info::AccountInfo;
//! use pinocchio_tkn::helpers::{is_token_2022, is_spl_token, has_extensions};
//! # let mint_account: &AccountInfo = todo!();
//!
//! if is_token_2022(&mint_account) {
//!     // This is a Token-2022 mint
//!     if has_extensions(&mint_account, true) {
//!         // Has extensions - might have fees, metadata, etc.
//!         // Be careful with transfers!
//!     } else {
//!         // Token-2022 but no extensions - same as legacy
//!     }
//! } else if is_spl_token(&mint_account) {
//!     // Legacy SPL Token - no extensions possible
//! }
//! ```
//!
//! #### Reading Token State and Extensions
//!
//! ```rust,ignore
//! # fn main() -> pinocchio::ProgramResult {
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio::program_error::ProgramError;
//! use pinocchio_tkn::state::{Mint, TokenAccount};
//! use pinocchio_tkn::helpers::has_extensions;
//! # let mint_account: &AccountInfo = todo!();
//! # let account: &AccountInfo = todo!();
//!
//! // Read mint state
//! let mint = Mint::from_account_info(&mint_account)?;
//! let supply = mint.supply();
//! let decimals = mint.decimals();
//!
//! if let Some(authority) = mint.mint_authority() {
//!     // Minting is enabled
//! } else {
//!     // Supply is fixed - no more minting possible
//! }
//!
//! // Read token account state
//! let token = TokenAccount::from_account_info(&account)?;
//! let balance = token.amount();
//! let owner = token.owner();
//!
//! if token.is_frozen() {
//!     return Err(ProgramError::InvalidAccountData); // Cannot transfer
//! }
//!
//! // Access extension data (Token-2022 only)
//! if has_extensions(&mint_account, true) {
//!     let raw_data = mint.raw_data();
//!     // Extension data starts at byte 82
//!     // Parse extension header and data manually if needed
//! }
//! # Ok(())
//! # }
//! ```
//!
//! #### Security Validation Pattern
//!
//! Always validate accounts before performing operations:
//!
//! ```rust,ignore
//! # use pinocchio::account_info::AccountInfo;
//! # use pinocchio::program_error::ProgramError;
//! use pinocchio_tkn::helpers::*;
//! use pinocchio_tkn::state::Mint;
//! use pinocchio_tkn::TransferChecked;
//!
//! fn secure_transfer(
//!     source: &AccountInfo,
//!     destination: &AccountInfo,
//!     mint: &AccountInfo,
//!     authority: &AccountInfo,
//!     amount: u64,
//! ) -> Result<(), ProgramError> {
//!     // 1. Validate ownership
//!     let program_id = get_token_program_id(mint);
//!     assert_owned_by(source, program_id)?;
//!     assert_owned_by(destination, program_id)?;
//!     assert_owned_by(mint, program_id)?;
//!
//!     // 2. Validate account types
//!     assert_is_mint(mint)?;
//!     assert_is_token_account(source, Some(mint.key()), None)?;
//!     assert_is_token_account(destination, Some(mint.key()), None)?;
//!
//!     // 3. Validate state
//!     assert_account_not_frozen(source)?;
//!     assert_account_not_frozen(destination)?;
//!
//!     // 4. Validate authority
//!     assert_token_account_owner(source, authority)?;
//!
//!     // 5. All checks passed - safe to transfer
//!     TransferChecked {
//!         source,
//!         mint,
//!         destination,
//!         authority,
//!         amount,
//!         decimals: Mint::from_account_info(mint)?.decimals(),
//!         program_id: None,
//!     }.invoke()?;
//!
//!     Ok(())
//! }
//! ```
//!
//! #### Fee Calculations
//!
//! ```rust,ignore
//! use pinocchio_tkn::helpers::{calculate_transfer_fee, calculate_inverse_transfer_fee};
//!
//! // Scenario 1: User wants to send 100 tokens, how much fee?
//! let amount = 100_000_000; // 100 tokens (6 decimals)
//! let fee_bps = 100; // 1%
//! let max_fee = 5_000_000; // 5 tokens max
//!
//! let fee = calculate_transfer_fee(amount, fee_bps, max_fee);
//! // fee = 1_000_000 (1 token)
//! // Recipient receives: 100_000_000 - 1_000_000 = 99_000_000
//!
//! // Scenario 2: User wants recipient to receive EXACTLY 100 tokens, how much to send?
//! let desired_amount = 100_000_000;
//! let (amount_to_send, fee) = calculate_inverse_transfer_fee(
//!     desired_amount,
//!     fee_bps,
//!     max_fee,
//! );
//! // amount_to_send = 101_010_101
//! // fee = 1_010_101
//! // Recipient receives: 101_010_101 - 1_010_101 = 100_000_000 ✓
//! ```
//!
//! ## Examples
//!
//! Check the `examples/` directory for complete working examples:
//!
//! - `01_basic_transfer.rs` - Simple SPL Token and Token-2022 transfers
//! - `02_transfer_fees.rs` - Setting up and using transfer fees
//! - `03_onchain_metadata.rs` - Adding metadata to tokens
//! - `04_full_workflow.rs` - Complete token lifecycle
//! - `05_validation_security.rs` - Security best practices
//!
//! ## Program IDs
//!
//! The crate provides constants for both token programs:
//!
//! - [`TOKEN_PROGRAM_ID`]: SPL Token (legacy) - `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`
//! - [`TOKEN_2022_PROGRAM_ID`]: Token-2022 - `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`
//! - [`ID`]: Alias for Token-2022 (default)
//!
//! ## Compatibility
//!
//! - **Rust Version**: 1.79 or later
//! - **no_std**: Fully compatible with no_std environments
//! - **Pinocchio**: Built on pinocchio 0.9+ for zero-allocation runtime
//! - **Solana**: Compatible with Solana SDK 3.0+

#![no_std]

use core::mem::MaybeUninit;
use pinocchio::pubkey::Pubkey;
use pinocchio_pubkey::pubkey;

/// SPL Token (legacy) Program ID: `TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`
pub const TOKEN_PROGRAM_ID: Pubkey = pubkey!("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");

/// Token-2022 Program ID: `TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`
pub const TOKEN_2022_PROGRAM_ID: Pubkey = pubkey!("TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb");

/// Alias for Token-2022 (default, backward compatibility)
pub const ID: Pubkey = TOKEN_2022_PROGRAM_ID;

/// Common instructions (work with both SPL Token and Token-2022)
#[cfg(feature = "common")]
pub mod common;

/// Token-2022 exclusive extensions
#[cfg(any(
    feature = "ext-transfer-fee",
    feature = "ext-metadata",
    feature = "ext-interest",
    feature = "ext-pointers",
    feature = "ext-misc"
))]
pub mod extensions;

/// Account state parsing (Mint, TokenAccount)
#[cfg(feature = "state")]
pub mod state;

/// Utility functions (calculations, validation, detection)
#[cfg(feature = "helpers")]
pub mod helpers;

/// Legacy module re-exports (backward compatibility)
#[deprecated(since = "0.2.0", note = "Use `common` or `extensions` modules instead")]
pub mod instructions {
    #[cfg(feature = "common")]
    pub use crate::common::*;

    #[cfg(any(
        feature = "ext-transfer-fee",
        feature = "ext-metadata",
        feature = "ext-interest",
        feature = "ext-pointers",
        feature = "ext-misc"
    ))]
    pub use crate::extensions::*;
}

/// Convenient prelude with all common types
pub mod prelude {
    #[cfg(feature = "common")]
    pub use crate::common::*;

    #[cfg(any(
        feature = "ext-transfer-fee",
        feature = "ext-metadata",
        feature = "ext-interest",
        feature = "ext-pointers",
        feature = "ext-misc"
    ))]
    pub use crate::extensions::*;

    #[cfg(feature = "state")]
    pub use crate::state::{AccountState, Mint, TokenAccount, MINT_SIZE, TOKEN_ACCOUNT_SIZE};

    #[cfg(feature = "helpers")]
    pub use crate::helpers::*;

    pub use crate::{ID, TOKEN_2022_PROGRAM_ID, TOKEN_PROGRAM_ID};
}

#[macro_use]
pub mod macros;

// Internal helpers for instruction building
const UNINIT_BYTE: MaybeUninit<u8> = MaybeUninit::<u8>::uninit();

#[inline(always)]
fn write_bytes(destination: &mut [MaybeUninit<u8>], source: &[u8]) {
    for (d, s) in destination.iter_mut().zip(source.iter()) {
        d.write(*s);
    }
}