### Mint Example Usage

Source: https://github.com/solana-program/token/blob/main/_autodocs/TYPES.md

Demonstrates how to unpack and access data from a Mint structure. Ensure the account data is correctly formatted before unpacking.

```rust
use spl_token_interface::state::Mint;
use solana_program_pack::Pack;

let mint_data = account.data.borrow();
let mint = Mint::unpack(&mint_data)?;

println!("Supply: {}", mint.supply);
println!("Decimals: {}", mint.decimals);
println!("Has mint authority: {}", mint.mint_authority.is_some());
```

--------------------------------

### Build and Test JS Clients

Source: https://github.com/solana-program/token/blob/main/clients/js/README.md

Builds the JavaScript client, installs dependencies, and runs the test suite using LiteSVM.

```shell
make test-js-clients-js
```

--------------------------------

### Install NPM Dependencies

Source: https://github.com/solana-program/token/blob/main/README.md

Install all necessary NPM dependencies to access the scripts and tools provided by the template. This command should be run in the project's root directory.

```sh
pnpm install
```

--------------------------------

### Multisig Usage Example

Source: https://github.com/solana-program/token/blob/main/_autodocs/TYPES.md

Demonstrates how to unpack and access data from a Multisig account, printing the required signatures and the list of signers.

```rust
use spl_token_interface::state::Multisig;
use solana_program_pack::Pack;

let multisig_data = account.data.borrow();
let multisig = Multisig::unpack(&multisig_data)?;

println!("Required signatures: {}/{}", multisig.m, multisig.n);
for (i, signer) in multisig.signers[..multisig.n as usize].iter().enumerate() {
    println!("Signer {}: {}", i, signer);
}
```

--------------------------------

### Account Example Usage

Source: https://github.com/solana-program/token/blob/main/_autodocs/TYPES.md

Shows how to unpack a token account's data and check its state, such as whether it is frozen. This is crucial for validating operations on token accounts.

```rust
use spl_token_interface::state::Account;
use solana_program_pack::Pack;

let account_data = account.data.borrow();
let token_account = Account::unpack(&account_data)?;

if token_account.is_frozen() {
    return Err("Account is frozen");
}

println!("Balance: {}", token_account.amount);
println!("Owner: {}", token_account.owner);
```

--------------------------------

### Build SBF Program and Run JS Client Tests

Source: https://github.com/solana-program/token/blob/main/clients/js/README.md

Builds the program's SBF shared object and then navigates to the client directory to install dependencies, build, and test the JavaScript client.

```shell
# Build the program `.so` that LiteSVM loads.
make build-sbf-pinocchio-program

# Go into the client directory and run the tests.
cd clients/js
pnpm install
pnpm build
pnpm test
```

--------------------------------

### Build and Test Rust Client

Source: https://github.com/solana-program/token/blob/main/clients/rust/README.md

Builds and tests the Rust client for the Token program. Starts a local validator if none is running.

```sh
pnpm clients:js:test
```

--------------------------------

### Start Local Solana Validator

Source: https://github.com/solana-program/token/blob/main/README.md

Use this script to start your local Solana validator. The script skips execution if a validator is already running.

```sh
pnpm validator:start
```

--------------------------------

### Get Account Data Size Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Use this instruction to query the required account size for a given mint. It requires the mint account and returns the size as a u64.

```rust
let ix = get_account_data_size(
    &token_program_id,
    &mint_pubkey
)?;
```

--------------------------------

### AccountState Usage Example

Source: https://github.com/solana-program/token/blob/main/_autodocs/TYPES.md

Illustrates how to use a match statement to handle different AccountState variants. This is useful for conditional logic based on an account's status.

```rust
use spl_token_interface::state::AccountState;

match account.state {
    AccountState::Uninitialized => println!("Not ready"),
    AccountState::Initialized => println!("Active"),
    AccountState::Frozen => println!("No operations allowed"),
}
```

--------------------------------

### SPL Token Program API Reference

Source: https://github.com/solana-program/token/blob/main/_autodocs/INDEX.md

This section provides a high-level overview of the SPL Token Program's architecture, module structure, and common patterns. It details core modules, instruction formats, authorization patterns, account lifecycles, and native SOL handling, along with quick start examples for common operations.

```APIDOC
## SPL Token Program API Reference

### Description
Provides a high-level architecture, module structure, and common patterns for the SPL Token Program. It covers core modules, instruction formats, authorization patterns, account lifecycles, and native SOL handling.

### Key Sections:
- Program overview and key features
- Module structure (instruction, state, error, native_mint)
- Quick start examples (create mint, transfer, mint, burn)
- Core modules detailed explanation
- Instruction format and binary layout
- Authorization patterns (single owner, multisig, delegation)
- Account lifecycle
- Batch instruction execution
- Native SOL handling
- Common operations with code examples
```

--------------------------------

### SPL Token Program Instruction Reference

Source: https://github.com/solana-program/token/blob/main/_autodocs/INDEX.md

This section offers a detailed reference for all 25 token instructions. For each instruction, it provides the full function signature, parameter details, account requirements, return types, error conditions, and realistic usage examples.

```APIDOC
## SPL Token Program Instruction Reference

### Description
Detailed documentation for all 25 token instructions, including full function signatures, parameter tables, account requirements, return types, error conditions, and usage examples.

### Instructions Covered:
- InitializeMint / InitializeMint2
- InitializeAccount / InitializeAccount2 / InitializeAccount3
- InitializeMultisig / InitializeMultisig2
- Transfer / TransferChecked
- Approve / ApproveChecked
- Revoke
- MintTo / MintToChecked
- Burn / BurnChecked
- SetAuthority (+ AuthorityType reference)
- CloseAccount
- FreezeAccount / ThawAccount
- SyncNative
- GetAccountDataSize
- InitializeImmutableOwner
- AmountToUiAmount / UiAmountToAmount
- WithdrawExcessLamports
- UnwrapLamports
- Batch
```

--------------------------------

### Little-Endian u64 Serialization Example

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Demonstrates how a u64 integer is serialized into its little-endian byte representation. This is a common format for multi-byte integers in Solana programs.

```rust
// u64 example: 1000000000 (1 billion)
// Bytes: [0x00, 0xCA, 0x9A, 0x3B, 0x00, 0x00, 0x00, 0x00]
let amount: u64 = 1_000_000_000;
let bytes = amount.to_le_bytes();
```

--------------------------------

### Rust Transfer Instruction with Single Owner

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Example of creating a transfer instruction where the owner of the source account must sign the transaction. No additional signers are required.

```rust
let ix = transfer(
    &token_program_id,
    &source,
    &destination,
    &owner_pubkey,      // Must sign
    &[],                // No additional signers
    amount
)?;
```

--------------------------------

### Rust Transfer Instruction by Delegate

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Example of a transfer instruction where the delegate acts as the signer. The transfer amount must not exceed the previously delegated amount.

```rust
let ix = transfer(
    &token_program_id,
    &source_account,
    &destination,
    &delegate_pubkey,   // Signer (delegate)
    &[],
    transfer_amount     // Must be <= delegated_amount
)?;
```

--------------------------------

### InitializeMint

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a new mint with optional freeze authority. Requires the Rent sysvar.

```APIDOC
## InitializeMint

### Description
Creates a new mint with optional freeze authority. This instruction requires the Rent sysvar to be provided.

### Method
Not applicable (Instruction)

### Endpoint
Not applicable (Instruction)

### Parameters
#### Instruction Data
- **decimals** (u8) - Required - Number of decimal places for token (0-255)
- **mint_authority** (Pubkey) - Required - Authority that can mint new tokens
- **freeze_authority** (COption<Pubkey>) - Optional - Authority that can freeze accounts

#### Accounts Required:
- 0: `[writable]` Mint account to initialize
- 1: `[]` Rent sysvar

### Response
#### Success Response
- Returns: `Instruction`

#### Error Handling:
- Throws: `ProgramError::IncorrectProgramId` if invalid program ID
```

--------------------------------

### InitializeMint Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a new mint account. Requires the Rent sysvar. Use when Rent is a necessary dependency.

```rust
InitializeMint {
    decimals: u8,
    mint_authority: Pubkey,
    freeze_authority: COption<Pubkey>,
}
```

```rust
use solana_program::pubkey::Pubkey;
use spl_token_interface::instruction::initialize_mint;

let token_program_id = Pubkey::new_from_array([/* ... */]);
let mint_pubkey = Pubkey::new_from_array([/* ... */]);
let mint_authority = Pubkey::new_from_array([/* ... */]);

let ix = initialize_mint(
    &token_program_id,
    &mint_pubkey,
    &mint_authority,
    None,
    6
)?;
```

--------------------------------

### InitializeMint2

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a new mint without requiring the Rent sysvar in accounts.

```APIDOC
## InitializeMint2

### Description
Creates a new mint without requiring the Rent sysvar. This is a more gas-efficient version of `InitializeMint`.

### Method
Not applicable (Instruction)

### Endpoint
Not applicable (Instruction)

### Parameters
#### Instruction Data
- **decimals** (u8) - Required - Number of decimal places for token
- **mint_authority** (Pubkey) - Required - Authority that can mint new tokens
- **freeze_authority** (COption<Pubkey>) - Optional - Authority that can freeze accounts

#### Accounts Required:
- 0: `[writable]` Mint account to initialize

### Response
#### Success Response
- Returns: `Instruction`
```

--------------------------------

### Get Program ID

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Retrieves the Program ID of the Solana Token Program. This function provides a convenient way to get the program ID for use in instruction construction.

```APIDOC
## Get Program ID

### Description
Retrieves the Program ID of the Solana Token Program.

### Signature
```rust
pub fn id() -> Pubkey;
```
```

--------------------------------

### InitializeMint2 Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a new mint account without requiring the Rent sysvar. Use when Rent is not a dependency.

```rust
InitializeMint2 {
    decimals: u8,
    mint_authority: Pubkey,
    freeze_authority: COption<Pubkey>,
}
```

```rust
let ix = initialize_mint2(
    &token_program_id,
    &mint_pubkey,
    &mint_authority,
    Some(&freeze_authority),
    6
)?;
```

--------------------------------

### Create a Mint

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

This snippet demonstrates how to create a new token mint using the `initialize_mint` instruction. It requires the token program ID, the new mint's public key, the mint's authority, an optional freeze authority, and the number of decimals for the token.

```APIDOC
## Create a Mint

### Description
Initializes a new token mint account. This instruction sets up the core parameters for a new token, including its supply, decimals, and authorities.

### Method
Instruction (within a transaction)

### Parameters
#### Instruction Parameters
- **token_program_id** (Pubkey) - Required - The program ID of the SPL Token program.
- **mint_pubkey** (Pubkey) - Required - The public key of the new mint account to be created.
- **mint_authority** (Pubkey) - Required - The public key that will have authority over the mint (e.g., to change supply).
- **freeze_authority** (Pubkey | None) - Optional - The public key that will have authority to freeze token accounts. If None, no freeze authority is set.
- **decimals** (u8) - Required - The number of decimal places for the token (0-18).

### Request Example
```rust
use spl_token_interface::instruction::initialize_mint;

let ix = initialize_mint(
    &token_program_id,
    &mint_pubkey,
    &mint_authority,
    None,  // freeze_authority
    6      // decimals
)?;
```
```

--------------------------------

### Native SOL Handling - Wrapping

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Demonstrates how to wrap native SOL into a SPL Token, creating a token account and initializing it to represent the native mint.

```APIDOC
## Native SOL Handling

### Wrapping SOL
```rust
use solana_system_interface::system_instruction;
use spl_token_interface::instruction::initialize_account;

// 1. Create account with SOL
let create_ix = system_instruction::create_account(
    &payer,
    &wrapped_account,
    lamports_to_wrap,
    165,  // Account size
    &token_program_id
);

// 2. Initialize as native token account
let init_ix = initialize_account(
    &token_program_id,
    &wrapped_account,
    &native_mint_id(),
    &owner
)?;

// Token balance = lamports in account
```
```

--------------------------------

### InitializeAccount Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Initializes a new token account associated with a mint. Requires the Rent sysvar. The account must not be already initialized.

```rust
InitializeAccount
```

```rust
let ix = initialize_account(
    &token_program_id,
    &token_account,
    &mint_pubkey,
    &owner_pubkey
)?;
```

--------------------------------

### Create a Token Account

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

This snippet shows how to create a new token account using the `initialize_account` instruction. It requires the token program ID, the new account's public key, the mint's public key that this account will hold tokens for, and the owner of the account.

```APIDOC
## Create a Token Account

### Description
Initializes a new token account to hold tokens for a specific mint. This instruction sets up an account that can store a balance of a particular token.

### Method
Instruction (within a transaction)

### Parameters
#### Instruction Parameters
- **token_program_id** (Pubkey) - Required - The program ID of the SPL Token program.
- **account_pubkey** (Pubkey) - Required - The public key of the new token account to be created.
- **mint_pubkey** (Pubkey) - Required - The public key of the token mint that this account will be associated with.
- **owner_pubkey** (Pubkey) - Required - The public key of the owner of this token account.

### Request Example
```rust
use spl_token_interface::instruction::initialize_account;

let ix = initialize_account(
    &token_program_id,
    &account_pubkey,
    &mint_pubkey,
    &owner_pubkey
)?;
```
```

--------------------------------

### Initialize Token Account Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Generates the instruction to initialize a new token account. This requires the token program ID, the new account's public key, the mint's public key, and the owner's public key.

```rust
use spl_token_interface::instruction::initialize_account;

let ix = initialize_account(
    &token_program_id,
    &account_pubkey,
    &mint_pubkey,
    &owner_pubkey
)?;
```

--------------------------------

### InitializeAccount

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Initializes a new token account associated with a mint. Requires the Rent sysvar.

```APIDOC
## InitializeAccount

### Description
Initializes a new token account associated with a mint. This instruction requires the Rent sysvar.

### Method
Not applicable (Instruction)

### Endpoint
Not applicable (Instruction)

### Parameters
#### Accounts Required:
- 0: `[writable]` Account to initialize
- 1: `[]` Mint this account is associated with
- 2: `[]` Account owner/multisignature
- 3: `[]` Rent sysvar

### Response
#### Success Response
- Returns: `Instruction`

#### Error Handling:
- Throws: Account must not already be initialized
```

--------------------------------

### Handle Authority Type Not Supported

Source: https://github.com/solana-program/token/blob/main/_autodocs/ERRORS.md

Ensure the correct authority type is used for Mint or Account. This example shows how to validate authority types to prevent 'AuthorityTypeNotSupported' errors.

```rust
use spl_token_interface::instruction::AuthorityType;
use spl_token_interface::state::{Mint, Account};

let is_mint = /* check if account is mint */; 

// Valid: MintTokens/FreezeAccount on Mint
// Valid: AccountOwner/CloseAccount on Account

if is_mint {
    match authority_type {
        AuthorityType::MintTokens | AuthorityType::FreezeAccount => {
            // OK
        }
        AuthorityType::AccountOwner | AuthorityType::CloseAccount => {
            return Err(TokenError::AuthorityTypeNotSupported)?;
        }
    }
}
```

--------------------------------

### Initialize Mint Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Generates the instruction to initialize a new token mint. Ensure the token program ID, mint account public key, and mint authority are correctly provided. The freeze authority is optional.

```rust
use spl_token_interface::instruction::initialize_mint;

let ix = initialize_mint(
    &token_program_id,
    &mint_pubkey,
    &mint_authority,
    None,  // freeze_authority
    6      // decimals
)?;
```

--------------------------------

### initialize_mint

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Creates a new mint account for a fungible token. Configurable with supply, decimals, and authorities.

```APIDOC
## initialize_mint

### Description
Creates a new mint account for a fungible token. Configurable with supply, decimals, and authorities.

### Method
Instruction Builder

### Parameters
- **token_program_id** (Pubkey) - The program ID of the SPL Token program.
- **mint_pubkey** (Pubkey) - The public key of the new mint account to be created.
- **mint_authority** (Pubkey) - The public key of the account that will be the mint authority.
- **freeze_authority** (COption<Pubkey>) - Optional public key of the account that will be the freeze authority.
- **decimals** (u8) - The number of decimal places for the token.

### Request Example
```rust
use spl_token_interface::instruction::initialize_mint;
use solana_pubkey::Pubkey;

let token_program_id = Pubkey::new_from_array([/* program ID */]);
let mint_pubkey = Pubkey::new_from_array([/* mint account */]);
let mint_authority = Pubkey::new_from_array([/* authority */]);

let ix = initialize_mint(
    &token_program_id,
    &mint_pubkey,
    &mint_authority,
    None,  // no freeze authority
    6      // 6 decimal places
)?;
```

### Response
- **Instruction** - The instruction to create the mint account.
```

--------------------------------

### Rust Transfer Instruction with Multisignature Owner

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Example of creating a transfer instruction for a multisignature account. The multisig account itself is not a signer; instead, a specified number of signers from its 'signers' array must be provided.

```rust
let ix = transfer(
    &token_program_id,
    &source,
    &destination,
    &multisig_pubkey,   // Not a signer
    &[&signer1, &signer2],  // M signers from multisig.signers array
    amount
)?;
```

--------------------------------

### SPL Token Program Error Catalog

Source: https://github.com/solana-program/token/blob/main/_autodocs/INDEX.md

This section offers a complete enumeration of the 20 error codes defined by the SPL Token Program, detailing the description, trigger conditions, affected instructions, and suggested fixes with code examples for each error.

```APIDOC
## SPL Token Program Error Catalog

### Description
Complete enumeration of 20 error codes with fixes, including descriptions, trigger conditions, affected instructions, and how to fix with code examples.

### Errors Covered (0-19):
- 0: NotRentExempt
- 1: InsufficientFunds
- 2: InvalidMint
- 3: MintMismatch
- 4: OwnerMismatch
- 5: FixedSupply
- 6: AlreadyInUse
- 7: InvalidNumberOfProvidedSigners
- 8: InvalidNumberOfRequiredSigners
- 9: UninitializedState
- 10: NativeNotSupported
- 11: NonNativeHasBalance
- 12: InvalidInstruction
- 13: InvalidState
- 14: Overflow
- 15: AuthorityTypeNotSupported
- 16: MintCannotFreeze
- 17: AccountFrozen
- 18: MintDecimalsMismatch
- 19: NonNativeNotSupported

### Error Handling Patterns
Includes code examples for common error handling scenarios.
```

--------------------------------

### InitializeAccount3

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Initializes a token account without Rent sysvar dependency.

```APIDOC
## InitializeAccount3

### Description
Initializes a token account without requiring the Rent sysvar. This is a more gas-efficient version of `InitializeAccount` and `InitializeAccount2`.

### Method
Not applicable (Instruction)

### Endpoint
Not applicable (Instruction)

### Parameters
#### Instruction Data
- **owner** (Pubkey) - Required - Account owner pubkey

#### Accounts Required:
- 0: `[writable]` Account to initialize
- 1: `[]` Mint this account is associated with

### Response
#### Success Response
- Returns: `Instruction`
```

--------------------------------

### SPL Token Program Type Definitions

Source: https://github.com/solana-program/token/blob/main/_autodocs/INDEX.md

This section provides a complete reference for all exported types and data structures used within the SPL Token Program, including detailed field layouts, serialization information, and usage examples for structures like Mint, Account, and Multisig.

```APIDOC
## SPL Token Program Type Definitions

### Description
Complete reference for all exported types and data structures, including detailed field layouts, serialization information, and usage examples.

### Types Covered:
- **Mint struct** (82 bytes)
  - Fields: mint_authority, supply, decimals, is_initialized, freeze_authority
  - Pack/serialization details
  - Usage examples
- **Account struct** (165 bytes)
  - Fields: mint, owner, amount, delegate, state, is_native, delegated_amount, close_authority
  - Methods: is_frozen(), is_native(), is_owned_by_system_program_or_incinerator()
  - Pack/serialization details
- **AccountState enum** (Uninitialized, Initialized, Frozen)
- **Multisig struct** (355 bytes)
  - Fields: m, n, is_initialized, signers array
  - Validation rules
- **AuthorityType enum** (MintTokens, FreezeAccount, AccountOwner, CloseAccount)
- **COption<T>** type (conditional options)
- **GenericTokenAccount trait** (6 methods for efficient unpacking)
- Program constants and initialization index
```

--------------------------------

### InitializeAccount Instruction Parameters

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Specifies the parameters for the InitializeAccount instruction, including token program ID, account, mint, and owner public keys. Highlights constraints such as the mint being initialized and the owner's role.

```rust
pub fn initialize_account(
    token_program_id: &Pubkey,
    account_pubkey: &Pubkey,
    mint_pubkey: &Pubkey,
    owner_pubkey: &Pubkey,
) -> Result<Instruction, ProgramError>
```

--------------------------------

### InitializeAccount2 Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Initializes a token account with the owner provided in instruction data. Requires the Rent sysvar.

```rust
InitializeAccount2 {
    owner: Pubkey,
}
```

```rust
let ix = initialize_account2(
    &token_program_id,
    &token_account,
    &mint_pubkey,
    &owner_pubkey
)?;
```

--------------------------------

### InitializeAccount3 Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Initializes a token account without Rent sysvar dependency. The owner is provided in instruction data.

```rust
InitializeAccount3 {
    owner: Pubkey,
}
```

--------------------------------

### Create Mint

Source: https://github.com/solana-program/token/blob/main/_autodocs/MANIFEST.txt

Initializes a new mint account. Requires the token program ID, mint account address, mint authority, supply decimals, and supply.

```Rust
initialize_mint(&token_program_id, &mint, &authority, None, 6)
```

--------------------------------

### Build Solana Programs

Source: https://github.com/solana-program/token/blob/main/README.md

Use this command to build all Solana programs in the repository. Ensure programs are added to the Cargo.toml members array.

```sh
pnpm programs:build
```

--------------------------------

### InitializeAccount2

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Initializes a token account with the owner provided in instruction data.

```APIDOC
## InitializeAccount2

### Description
Initializes a token account with the owner specified in the instruction data. Requires the Rent sysvar.

### Method
Not applicable (Instruction)

### Endpoint
Not applicable (Instruction)

### Parameters
#### Instruction Data
- **owner** (Pubkey) - Required - Account owner pubkey

#### Accounts Required:
- 0: `[writable]` Account to initialize
- 1: `[]` Mint this account is associated with
- 2: `[]` Rent sysvar

### Response
#### Success Response
- Returns: `Instruction`
```

--------------------------------

### Create Token Account

Source: https://github.com/solana-program/token/blob/main/_autodocs/MANIFEST.txt

Initializes a new token account. Requires the token program ID, the new account address, the mint account address, and the owner's public key.

```Rust
initialize_account(&token_program_id, &account, &mint, &owner)
```

--------------------------------

### Initialize Account Before Use

Source: https://github.com/solana-program/token/blob/main/_autodocs/ERRORS.md

Always ensure accounts are initialized before performing operations on them. Use the provided instruction constructors to create properly formatted instructions.

```rust
// Always initialize before use
let init_ix = initialize_account(
    &token_program_id,
    &account_pubkey,
    &mint_pubkey,
    &owner_pubkey
)?;
```

--------------------------------

### initialize_account

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Creates a new token account to hold tokens for a specific mint. Associated with an owner.

```APIDOC
## initialize_account

### Description
Creates a new token account to hold tokens for a specific mint. Associated with an owner.

### Method
Instruction Builder

### Parameters
- **token_program_id** (Pubkey) - The program ID of the SPL Token program.
- **account_pubkey** (Pubkey) - The public key of the new token account to be created.
- **mint_pubkey** (Pubkey) - The public key of the mint account this token account will be associated with.
- **owner_pubkey** (Pubkey) - The public key of the owner of this token account.

### Request Example
```rust
use spl_token_interface::instruction::initialize_account;

let ix = initialize_account(
    &token_program_id,
    &account_pubkey,
    &mint_pubkey,
    &owner_pubkey
)?;
```

### Response
- **Instruction** - The instruction to create the token account.
```

--------------------------------

### InitializeMint Instruction Parameters

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Defines the parameters required for the InitializeMint instruction, including token program ID, mint and authority public keys, optional freeze authority, and decimals. Notes constraints on decimals and authorities.

```rust
pub fn initialize_mint(
    token_program_id: &Pubkey,
    mint_pubkey: &Pubkey,
    mint_authority_pubkey: &Pubkey,
    freeze_authority_pubkey: Option<&Pubkey>,  // Can be None
    decimals: u8,                               // 0-255, typically 6-18
) -> Result<Instruction, ProgramError>
```

--------------------------------

### Mint Tokens Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Generates an instruction to mint new tokens to a specified account. Requires the token program ID, the mint's public key, the account to mint to, the mint authority, and the amount to mint.

```rust
use spl_token_interface::instruction::mint_to;

let ix = mint_to(
    &token_program_id,
    &mint_pubkey,
    &account_pubkey,
    &mint_authority,
    &[],
    1_000_000_000
)?;
```

--------------------------------

### Token Account Creation

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Creates a new Token account, calculating the required rent exemption based on its total size of 165 bytes. Uses system_instruction::create_account.

```rust
use solana_system_interface::system_instruction;

let space = 165;
let rent = Rent::get()?;
let lamports_required = rent.minimum_balance(space);

let create_ix = system_instruction::create_account(
    &payer,
    &token_account,
    lamports_required,
    space as u64,
    &token_program_id
);
```

--------------------------------

### Rust Wrap Native SOL

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Shows the process of wrapping native SOL into a token account. This involves creating an account with the system program and then initializing it as a native token account using the Token program.

```rust
use solana_system_interface::system_instruction;
use spl_token_interface::instruction::initialize_account;

// 1. Create account with SOL
let create_ix = system_instruction::create_account(
    &payer,
    &wrapped_account,
    lamports_to_wrap,
    165,  // Account size
    &token_program_id
);

// 2. Initialize as native token account
let init_ix = initialize_account(
    &token_program_id,
    &wrapped_account,
    &native_mint_id(),
    &owner
)?;

// Token balance = lamports in account
```

--------------------------------

### Burn Tokens Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Creates an instruction to burn tokens from a specified account. Requires the token program ID, the account to burn from, the mint's public key, the owner's public key, and the amount to burn.

```rust
use spl_token_interface::instruction::burn;

let ix = burn(
    &token_program_id,
    &account_pubkey,
    &mint_pubkey,
    &owner_pubkey,
    &[],
    500_000
)?;
```

--------------------------------

### Approve Delegate Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Creates an instruction to approve a delegate for a token account. This allows the delegate to transfer tokens on behalf of the owner. Specify the token program ID, source account, delegate's public key, owner's public key, and the amount the delegate can transfer.

```rust
use spl_token_interface::instruction::approve;

let ix = approve(
    &token_program_id,
    &source_account,
    &delegate_pubkey,
    &owner_pubkey,
    &[],
    5_000_000
)?;
```

--------------------------------

### Initialize Multisig Account (No Rent Sysvar)

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a multisignature authority account without requiring the Rent sysvar. This is an alternative to InitializeMultisig.

```rust
InitializeMultisig2 {
    m: u8,
}
```

--------------------------------

### Mint Account Creation

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Creates a new Mint account, calculating the required rent exemption based on its total size of 82 bytes. Uses system_instruction::create_account.

```rust
use spl_token_interface::instruction::initialize_mint;
use solana_system_interface::system_instruction;

let space = 82;
let rent = Rent::get()?;
let lamports_required = rent.minimum_balance(space);

let create_ix = system_instruction::create_account(
    &payer,
    &mint,
    lamports_required,
    space as u64,
    &token_program_id
);
```

--------------------------------

### Generate Clients for Solana Programs

Source: https://github.com/solana-program/token/blob/main/README.md

Generate clients for your Solana programs after their IDLs have been generated. This command simplifies interaction with your programs.

```sh
pnpm generate:clients
```

--------------------------------

### Rust Batch Instruction Execution

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Demonstrates how to group multiple token instructions into a single batch instruction for execution within one transaction. Each instruction's data must be 255 bytes or less, and nesting batch instructions is not allowed.

```rust
use spl_token_interface::instruction::batch;

let instructions = vec![
    transfer_ix,
    approve_ix,
    burn_ix,
];

let batch_ix = batch(&token_program_id, &instructions)?;
// Single transaction with batch_ix executes all three
```

--------------------------------

### Test Solana Programs

Source: https://github.com/solana-program/token/blob/main/README.md

Run this command to execute tests for all Solana programs. This is part of the standard development workflow.

```sh
pnpm programs:test
```

--------------------------------

### MintTo Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Mints new tokens to a specified account. Use this when you need to increase the supply of a token in a particular account.

```rust
MintTo {
    amount: u64,
}
```

```rust
let ix = mint_to(
    &token_program_id,
    &mint_pubkey,
    &dest_account,
    &mint_authority,
    &[],
    1_000_000_000
)?;
```

--------------------------------

### SPL Token Program Instructions

Source: https://github.com/solana-program/token/blob/main/_autodocs/MANIFEST.txt

The SPL Token Program exposes 25 distinct instruction builder functions that allow users to perform various operations on SPL tokens. These include initialization, token operations, account management, and utility functions.

```APIDOC
## SPL Token Program Instructions

### Description
The SPL Token Program provides a set of instructions to manage and interact with SPL tokens on the Solana blockchain. These instructions cover token creation, transfers, minting, burning, account management, and more.

### Instructions

**INITIALIZATION (6 variants)**
- InitializeMint
- InitializeMint2
- InitializeAccount
- InitializeAccount2
- InitializeAccount3
- InitializeMultisig
- InitializeMultisig2

**TOKEN OPERATIONS (10 variants)**
- Transfer
- TransferChecked
- Approve
- ApproveChecked
- Revoke
- MintTo
- MintToChecked
- Burn
- BurnChecked
- CloseAccount

**ACCOUNT MANAGEMENT (4 variants)**
- FreezeAccount
- ThawAccount
- SetAuthority
- SyncNative

**UTILITY OPERATIONS (5 variants)**
- GetAccountDataSize
- InitializeImmutableOwner
- AmountToUiAmount
- UiAmountToAmount
- WithdrawExcessLamports
- UnwrapLamports
- Batch

### Further Details
Detailed function signatures, parameter tables, account requirements, return types, error conditions, and usage examples for each instruction can be found in the `INSTRUCTIONS.md` file.
```

--------------------------------

### Instruction Format

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Details the structure of instructions for the Token Program, including the discriminator and the format for instruction-specific data.

```APIDOC
## Instruction Format

All instructions use discriminator-based format:

| Offset | Size   | Content                |
|--------|--------|------------------------|
| 0      | 1      | Instruction discriminator |
| 1+     | variable | Instruction-specific data |

**Serialization:**
- Discriminator: single byte
- Pubkeys: 32 bytes, little-endian
- Amounts: 8 bytes, little-endian
- Decimals: 1 byte
- Options: discriminator (0/1) + optional 32-byte or 8-byte value
```

--------------------------------

### Convert UI Amount to Amount Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Converts a UI format amount string (e.g., "1.5") to a raw token amount. Requires the mint account and returns a u64.

```rust
let ix = ui_amount_to_amount(
    &token_program_id,
    &mint_pubkey,
    "1.5"
)?;
```

--------------------------------

### Format Solana Programs

Source: https://github.com/solana-program/token/blob/main/README.md

Use this command to format the code for all Solana programs according to project standards.

```sh
pnpm programs:format
```

--------------------------------

### Multisig Account Creation

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Creates a new Multisig account, calculating the required rent exemption based on its total size of 355 bytes. Uses system_instruction::create_account.

```rust
use solana_system_interface::system_instruction;

let space = 355;
let rent = Rent::get()?;
let lamports_required = rent.minimum_balance(space);

let create_ix = system_instruction::create_account(
    &payer,
    &multisig_account,
    lamports_required,
    space as u64,
    &token_program_id
);
```

--------------------------------

### Close Account Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Creates an instruction to close a token account, returning any remaining SOL to the destination account. Requires the token program ID, the account to close, the destination account for remaining SOL, the owner's public key, and signers.

```rust
use spl_token_interface::instruction::close_account;

let ix = close_account(
    &token_program_id,
    &account_pubkey,
    &destination_pubkey,
    &owner_pubkey,
    &[]
)?;
```

--------------------------------

### Initialize Multisig Parameters

Source: https://github.com/solana-program/token/blob/main/_autodocs/CONFIGURATION.md

Defines the function signature for initializing multisig parameters. Constraints on the number of signers (n) and the required signatures (m) are specified.

```rust
pub fn initialize_multisig(
    token_program_id: &Pubkey,
    multisig_pubkey: &Pubkey,
    signer_pubkeys: &[&Pubkey],  // Length must match n
    m: u8,                        // 1-11
) -> Result<Instruction, ProgramError>
```

--------------------------------

### Initialize Multisig Account

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a multisignature authority account. Requires M-of-N signatures, where M is the number of required signers. The Rent sysvar is required.

```rust
InitializeMultisig {
    m: u8,
}
```

```rust
let signers = vec![&signer1, &signer2, &signer3];
let ix = initialize_multisig(
    &token_program_id,
    &multisig_pubkey,
    &signers,
    2
)?;
```

--------------------------------

### Rust Approve Delegate Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Creates an instruction to approve a delegate for a specified amount. The owner of the source account must sign this transaction.

```rust
let ix = approve(
    &token_program_id,
    &source_account,
    &delegate_pubkey,
    &owner_pubkey,
    &[],
    delegated_amount
)?;
```

--------------------------------

### Fix AlreadyInUse Error in Solana Token Program

Source: https://github.com/solana-program/token/blob/main/_autodocs/ERRORS.md

Checks if an account is already initialized before attempting to initialize it. Shows how to create a new account if it's not in use.

```rust
use spl_token_interface::state::Account;
use solana_program_pack::IsInitialized;
use solana_program::system_instruction;
use solana_program::pubkey::Pubkey;
use solana_program::account_info::AccountInfo;

// Assume account is an initialized Account struct, payer, new_account, token_program_id, lamports, space are defined
// let account: Account = ...;
// let payer: &AccountInfo = ...;
// let new_account: &AccountInfo = ...;
// let token_program_id: &Pubkey = ...;
// let lamports: u64 = 0;
// let space: u64 = 0;

if account.is_initialized() {
    return Err(TokenError::AlreadyInUse)?;
}

// Create new account before initialization
let create_ix = system_instruction::create_account(
    &payer.key(),
    &new_account.key(),
    lamports,
    space,
    token_program_id,
);
```

--------------------------------

### Convert Amount to UI Amount Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Converts a raw token amount to a UI string representation using the mint's decimal places. Requires the mint account and returns a UTF-8 string.

```rust
let ix = amount_to_ui_amount(
    &token_program_id,
    &mint_pubkey,
    1_000_000_000
)?;
```

--------------------------------

### Rust Unwrap Native SOL

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Demonstrates unwrapping native SOL from a token account back into native SOL. This can be done by transferring a specific amount or all available SOL using `unwrap_lamports`, or by syncing the account balance after a direct SOL transfer using `sync_native`.

```rust
use spl_token_interface::instruction::unwrap_lamports;

// Transfer SOL from wrapped account
let ix = unwrap_lamports(
    &token_program_id,
    &wrapped_account,
    &destination_pubkey,
    &owner_pubkey,
    &[],
    Some(lamports_to_unwrap)  // None = transfer all
)?;

// Or sync after direct transfer
let ix = sync_native(&token_program_id, &wrapped_account)?;
```

--------------------------------

### Freeze Account Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Generates an instruction to freeze a token account, preventing further token movements. Requires the token program ID, the account to freeze, the mint's public key, the freeze authority, and signers.

```rust
use spl_token_interface::instruction::freeze_account;

let ix = freeze_account(
    &token_program_id,
    &account_pubkey,
    &mint_pubkey,
    &freeze_authority,
    &[]
)?;
```

--------------------------------

### InitializeMultisig

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Creates a multisignature authority account requiring M-of-N signatures. This instruction initializes a new multisig account and specifies the number of required signers.

```APIDOC
## InitializeMultisig

### Description
Creates a multisignature authority account requiring M-of-N signatures.

### Method
Instruction

### Parameters
#### Path Parameters
- **m** (u8) - Required - Number of required signers (1-11)

### Accounts Required
- 0: `[writable]` Multisig account to initialize
- 1: `[]` Rent sysvar
- 2..2+N: `[]` Signer accounts (N = number of signers, 1-11)

### Validation
- m must be between 1 and 11
- N must be between 1 and 11
- m must be ≤ N

### Returns
`Instruction`

### Throws
`ProgramError::MissingRequiredSignature` if validation fails

### Example
```rust
let signers = vec![&signer1, &signer2, &signer3];
let ix = initialize_multisig(
    &token_program_id,
    &multisig_pubkey,
    &signers,
    2
)?;
```
```

--------------------------------

### WithdrawExcessLamports

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Rescues SOL from a token account, leaving only enough for rent exemption. This instruction can be used with single or multisig owners/delegates.

```APIDOC
## WithdrawExcessLamports

### Description
Rescues SOL from a token account leaving only rent exemption.

### Accounts Required (Single Owner/Delegate)
- 0: `[writable]` Source account
- 1: `[writable]` Destination account
- 2: `[signer]` Source account's owner/delegate

### Accounts Required (Multisig Owner/Delegate)
- 0: `[writable]` Source account
- 1: `[writable]` Destination account
- 2: `[]` Multisig owner/delegate
- 3..+M: `[signer]` M signer accounts

### Example
```rust
let ix = withdraw_excess_lamports(
    &token_program_id,
    &account_pubkey,
    &destination_pubkey,
    &owner_pubkey,
    &[] // For multisig signers
)?; // Assuming withdraw_excess_lamports is a wrapper function
```
```

--------------------------------

### Transfer Tokens Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/README.md

Generates an instruction to transfer tokens from one account to another. Requires the token program ID, source and destination accounts, owner's public key, and the amount to transfer.

```rust
use spl_token_interface::instruction::transfer;

let ix = transfer(
    &token_program_id,
    &source_account,
    &dest_account,
    &owner_pubkey,
    &[],           // signers
    1_000_000      // amount
)?;
```

--------------------------------

### Initialize Immutable Owner Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Marks a token account with an immutable owner for compatibility. This is a no-op in the current version but is necessary for Associated Token Account compatibility.

```rust
let ix = initialize_immutable_owner(
    &token_program_id,
    &account_pubkey
)?;
```

--------------------------------

### Authorization Patterns

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Explains the different authorization mechanisms supported by the Token Program, including single owner, multisignature, and delegation.

```APIDOC
## Authorization Patterns

### Single Owner/Authority
```rust
// Authority is signer
let ix = transfer(
    &token_program_id,
    &source,
    &destination,
    &owner_pubkey,      // Must sign
    &[],                // No additional signers
    amount
)?;
```

### Multisignature Owner/Authority
```rust
// Multisig authority requires M-of-N signatures
let ix = transfer(
    &token_program_id,
    &source,
    &destination,
    &multisig_pubkey,   // Not a signer
    &[&signer1, &signer2],  // M signers from multisig.signers array
    amount
)?;
```

### Delegation
```rust
// Approve delegate
let ix = approve(
    &token_program_id,
    &source_account,
    &delegate_pubkey,
    &owner_pubkey,
    &[],
    delegated_amount
)?;

// Delegate can transfer up to delegated_amount
let ix = transfer(
    &token_program_id,
    &source_account,
    &destination,
    &delegate_pubkey,   // Signer (delegate) 
    &[],
    transfer_amount     // Must be <= delegated_amount
)?;
```
```

--------------------------------

### Configure External Program Dependencies

Source: https://github.com/solana-program/token/blob/main/README.md

Add external program addresses to the `program-dependencies` array in your program's Cargo.toml to include them in your local validator.

```toml
program-dependencies = [
  "metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s",
  "noopb9bkMVfRPU8AsbpTUg8AQkHtKwMYZiFUjNRtMmV",
]
```

--------------------------------

### Add spl-token-interface Dependency

Source: https://github.com/solana-program/token/blob/main/pinocchio/interface/README.md

Add the spl-token-interface dependency to your project's Cargo.toml file to begin using the SPL Token interface.

```bash
cargo add spl-token-interface
```

--------------------------------

### Build and Restart Validator with External Programs

Source: https://github.com/solana-program/token/blob/main/README.md

After configuring external program dependencies, rebuild your program and restart the validator to include them.

```sh
pnpm programs:build
pnpm validator:restart
```

--------------------------------

### Generate IDLs and Clients

Source: https://github.com/solana-program/token/blob/main/README.md

This command generates both the Interface Definition Languages (IDLs) and the clients for your Solana programs simultaneously.

```sh
pnpm generate
```

--------------------------------

### Native SOL Handling - Unwrapping

Source: https://github.com/solana-program/token/blob/main/_autodocs/API_REFERENCE.md

Shows how to unwrap native SOL from a SPL Token account, either by transferring a specific amount or by syncing the balance after a direct SOL transfer.

```APIDOC
### Unwrapping SOL
```rust
use spl_token_interface::instruction::unwrap_lamports;

// Transfer SOL from wrapped account
let ix = unwrap_lamports(
    &token_program_id,
    &wrapped_account,
    &destination_pubkey,
    &owner_pubkey,
    &[],
    Some(lamports_to_unwrap)  // None = transfer all
)?;

// Or sync after direct transfer
let ix = sync_native(&token_program_id, &wrapped_account)?;
```
```

--------------------------------

### MintToChecked Instruction

Source: https://github.com/solana-program/token/blob/main/_autodocs/INSTRUCTIONS.md

Mints new tokens to a specified account with explicit decimals validation. Use this to ensure the minted amount correctly corresponds to the token's decimal places.

```rust
MintToChecked {
    amount: u64,
    decimals: u8,
}
```

```rust
let ix = mint_to_checked(
    &token_program_id,
    &mint_pubkey,
    &dest_account,
    &mint_authority,
    &[],
    1_000_000_000,
    9
)?;
```

--------------------------------

### Handle Native vs. Non-Native Token Operations

Source: https://github.com/solana-program/token/blob/main/_autodocs/ERRORS.md

Differentiate between native SOL accounts and regular token accounts. Use `CloseAccount` or `UnwrapLamports` for native SOL, and standard `Burn` for other tokens.

```rust
use spl_token_interface::state::Account;
use solana_program_pack::Pack;

let account = Account::unpack(&account_data)?;

if account.is_native() {
    // Use CloseAccount or UnwrapLamports instead
    let ix = close_account(
        &token_program_id,
        &account_pubkey,
        &destination,
        &owner,
        &[]
    )?;
} else {
    // Safe to burn
    let ix = burn(
        &token_program_id,
        &account_pubkey,
        &mint,
        &owner,
        &[],
        amount
    )?;
}
```

--------------------------------

### Format JavaScript Client

Source: https://github.com/solana-program/token/blob/main/clients/js/README.md

Formats the JavaScript client code according to predefined style rules.

```shell
pnpm format
```