@rialo/spl-token 0.3.0-alpha.0 → 0.3.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { PublicKey, RialoClient, TransactionBuilder, Signer } from '@rialo/ts-cdk';
+import { PublicKey, RialoClient, TransactionBuilder, Signer, Keypair } from '@rialo/ts-cdk';
 
 /**
  * TransferChecked instruction for SPL Token-2022.
@@ -11,22 +11,16 @@ import { PublicKey, RialoClient, TransactionBuilder, Signer } from '@rialo/ts-cd
  * Account metadata for an instruction account.
  */
 interface AccountMeta {
-    /** The account's public key */
     pubkey: PublicKey;
-    /** Whether this account must sign the transaction */
     isSigner: boolean;
-    /** Whether this account's data can be modified */
     isWritable: boolean;
 }
 /**
  * A single instruction to be included in a transaction.
  */
 interface Instruction {
-    /** The program that will process this instruction */
     programId: PublicKey;
-    /** Accounts required by this instruction */
     accounts: AccountMeta[];
-    /** Instruction data */
     data: Uint8Array;
 }
 /**
@@ -47,6 +41,8 @@ interface TransferCheckedInstructionOptions {
     decimals: number;
     /** Token program ID (defaults to Token-2022) */
     programId?: PublicKey;
+    /** Optional multisig signer accounts */
+    signers?: PublicKey[];
 }
 /**
  * Creates a TransferChecked instruction.
@@ -76,7 +72,7 @@ interface TransferCheckedInstructionOptions {
  *   .build();
  * ```
  */
-declare function transferCheckedInstruction({ source, mint, destination, authority, amount, decimals, programId, }: TransferCheckedInstructionOptions): Instruction;
+declare function transferCheckedInstruction({ source, mint, destination, authority, amount, decimals, signers, programId, }: TransferCheckedInstructionOptions): Instruction;
 /**
  * Options for creating a Transfer instruction.
  */
@@ -91,6 +87,8 @@ interface TransferInstructionOptions {
     amount: bigint;
     /** Token program ID (defaults to Token-2022) */
     programId?: PublicKey;
+    /** Optional multisig signer accounts */
+    signers?: PublicKey[];
 }
 /**
  * Creates a Transfer instruction (deprecated, prefer TransferChecked).
@@ -101,7 +99,7 @@ interface TransferInstructionOptions {
  * @param options - Options for the instruction
  * @returns The Transfer instruction
  */
-declare function transferInstruction({ source, destination, authority, amount, programId, }: TransferInstructionOptions): Instruction;
+declare function transferInstruction({ source, destination, authority, amount, signers, programId, }: TransferInstructionOptions): Instruction;
 
 /**
  * Create Associated Token Account instruction for SPL Token-2022.
@@ -190,6 +188,49 @@ interface CreateAssociatedTokenAccountIdempotentInstructionOptions {
  */
 declare function createAssociatedTokenAccountIdempotentInstruction({ payer, associatedToken, owner, mint, programId, }: CreateAssociatedTokenAccountIdempotentInstructionOptions): Instruction;
 
+/**
+ * Options for creating a MetadataPointer Initialize instruction.
+ */
+interface InitializeMetadataPointerInstructionOptions {
+    /** Mint account to initialize */
+    mint: PublicKey;
+    /** Optional authority that can update the metadata address */
+    authority?: PublicKey | null;
+    /** Optional metadata address */
+    metadataAddress?: PublicKey | null;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a MetadataPointer Initialize instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), metadata_pointer_instruction(1), authority(32), metadata_address(32)]
+ */
+declare function initializeMetadataPointerInstruction({ mint, authority, metadataAddress, programId, }: InitializeMetadataPointerInstructionOptions): Instruction;
+/**
+ * Options for creating a MetadataPointer Update instruction.
+ */
+interface UpdateMetadataPointerInstructionOptions {
+    /** Mint account to update */
+    mint: PublicKey;
+    /** Authority that can update the metadata address */
+    authority: PublicKey;
+    /** Optional metadata address */
+    metadataAddress?: PublicKey | null;
+    /** Optional multisig signer accounts */
+    signers?: PublicKey[];
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a MetadataPointer Update instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), metadata_pointer_instruction(1), metadata_address(32)]
+ */
+declare function updateMetadataPointerInstruction({ mint, authority, metadataAddress, signers, programId, }: UpdateMetadataPointerInstructionOptions): Instruction;
+
 /**
  * Options for creating an InitializeMint2 instruction.
  *
@@ -246,6 +287,8 @@ interface MintToInstructionOptions {
     amount: bigint;
     /** Token program ID (defaults to Token-2022) */
     programId?: PublicKey;
+    /** Optional multisig signer accounts */
+    signers?: PublicKey[];
 }
 /**
  * Creates a MintTo instruction for Token-2022.
@@ -270,7 +313,196 @@ interface MintToInstructionOptions {
  * });
  * ```
  */
-declare function mintToInstruction({ mint, destination, authority, amount, programId, }: MintToInstructionOptions): Instruction;
+declare function mintToInstruction({ mint, destination, authority, amount, signers, programId, }: MintToInstructionOptions): Instruction;
+
+/**
+ * Options for creating an InitializeNonTransferableMint instruction.
+ */
+interface InitializeNonTransferableMintInstructionOptions {
+    /** Mint to initialize */
+    mint: PublicKey;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates an InitializeNonTransferableMint instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1)]
+ */
+declare function initializeNonTransferableMintInstruction({ mint, programId, }: InitializeNonTransferableMintInstructionOptions): Instruction;
+
+/**
+ * Options for creating an InitializePermanentDelegate instruction.
+ */
+interface InitializePermanentDelegateInstructionOptions {
+    /** Mint to initialize */
+    mint: PublicKey;
+    /** Permanent delegate authority */
+    delegate: PublicKey;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates an InitializePermanentDelegate instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), delegate_pubkey(32)]
+ */
+declare function initializePermanentDelegateInstruction({ mint, delegate, programId, }: InitializePermanentDelegateInstructionOptions): Instruction;
+
+/**
+ * Computes the size of TokenMetadata extension data.
+ */
+declare function getTokenMetadataDataSize({ name, symbol, uri, additionalMetadata, }: {
+    name: string;
+    symbol: string;
+    uri: string;
+    additionalMetadata?: Array<[string, string]>;
+}): number;
+/**
+ * Options for creating a TokenMetadata Initialize instruction.
+ */
+interface InitializeTokenMetadataInstructionOptions {
+    /** Mint account to initialize */
+    mint: PublicKey;
+    /** Authority allowed to update metadata */
+    updateAuthority: PublicKey;
+    /** Mint authority */
+    mintAuthority: PublicKey;
+    /** Token name */
+    name: string;
+    /** Token symbol */
+    symbol: string;
+    /** Token URI */
+    uri: string;
+    /** Optional additional metadata entries */
+    additionalMetadata?: Array<[string, string]>;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a TokenMetadata Initialize instruction.
+ *
+ * Instruction data format:
+ * [discriminator(8), name, symbol, uri]
+ * or with additional metadata:
+ * [discriminator(8), name, symbol, uri, additional_metadata]
+ */
+declare function initializeTokenMetadataInstruction({ mint, updateAuthority, mintAuthority, name, symbol, uri, additionalMetadata, programId, }: InitializeTokenMetadataInstructionOptions): {
+    programId: PublicKey;
+    accounts: Array<{
+        pubkey: PublicKey;
+        isSigner: boolean;
+        isWritable: boolean;
+    }>;
+    data: Uint8Array;
+};
+
+/**
+ * Options for creating a TransferFee InitializeConfig instruction.
+ */
+interface InitializeTransferFeeConfigInstructionOptions {
+    /** Mint to initialize */
+    mint: PublicKey;
+    /** Optional authority allowed to update transfer fees */
+    transferFeeConfigAuthority?: PublicKey | null;
+    /** Optional authority allowed to withdraw withheld fees */
+    withdrawWithheldAuthority?: PublicKey | null;
+    /** Fee rate in basis points */
+    transferFeeBasisPoints: number;
+    /** Maximum fee assessed on transfers */
+    maximumFee: bigint;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a TransferFee InitializeConfig instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), transfer_fee_instruction(1),
+ *  transfer_fee_config_authority(COption<Pubkey>),
+ *  withdraw_withheld_authority(COption<Pubkey>),
+ *  transfer_fee_basis_points(2), maximum_fee(8)]
+ */
+declare function initializeTransferFeeConfigInstruction({ mint, transferFeeConfigAuthority, withdrawWithheldAuthority, transferFeeBasisPoints, maximumFee, programId, }: InitializeTransferFeeConfigInstructionOptions): Instruction;
+/**
+ * Options for creating a TransferCheckedWithFee instruction.
+ */
+interface TransferCheckedWithFeeInstructionOptions {
+    /** Source token account */
+    source: PublicKey;
+    /** Mint address */
+    mint: PublicKey;
+    /** Destination token account */
+    destination: PublicKey;
+    /** Authority that can transfer (owner or delegate) */
+    authority: PublicKey;
+    /** Amount to transfer */
+    amount: bigint;
+    /** Expected number of decimals */
+    decimals: number;
+    /** Expected fee assessed */
+    fee: bigint;
+    /** Optional multisig signer accounts */
+    signers?: PublicKey[];
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a TransferCheckedWithFee instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), transfer_fee_instruction(1),
+ *  amount(8), decimals(1), fee(8)]
+ */
+declare function transferCheckedWithFeeInstruction({ source, mint, destination, authority, amount, decimals, fee, signers, programId, }: TransferCheckedWithFeeInstructionOptions): Instruction;
+/**
+ * Options for creating a TransferFee SetTransferFee instruction.
+ */
+interface SetTransferFeeInstructionOptions {
+    /** Mint to update */
+    mint: PublicKey;
+    /** Authority allowed to set transfer fees */
+    authority: PublicKey;
+    /** Fee rate in basis points */
+    transferFeeBasisPoints: number;
+    /** Maximum fee assessed on transfers */
+    maximumFee: bigint;
+    /** Optional multisig signer accounts */
+    signers?: PublicKey[];
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a TransferFee SetTransferFee instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), transfer_fee_instruction(1),
+ *  transfer_fee_basis_points(2), maximum_fee(8)]
+ */
+declare function setTransferFeeInstruction({ mint, authority, transferFeeBasisPoints, maximumFee, signers, programId, }: SetTransferFeeInstructionOptions): Instruction;
+
+/**
+ * Options for creating an InitializeTransferHook instruction.
+ */
+interface InitializeTransferHookInstructionOptions {
+    /** Mint to initialize */
+    mint: PublicKey;
+    /** Authority that can update the hook program */
+    authority: PublicKey;
+    /** The program invoked on every transfer */
+    hookProgramId: PublicKey;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates an InitializeTransferHook instruction.
+ *
+ * Instruction data format:
+ * [token_instruction(1), transfer_hook_instruction(1), authority(32), hook_program_id(32)]
+ */
+declare function initializeTransferHookInstruction({ mint, authority, hookProgramId, programId, }: InitializeTransferHookInstructionOptions): Instruction;
 
 /**
  * Constants for SPL Token-2022 operations.
@@ -409,11 +641,25 @@ declare enum TokenInstruction {
     /** Initialize multisig with rent sysvar */
     InitializeMultisig2 = 19,
     /** Initialize mint with rent sysvar */
-    InitializeMint2 = 20
+    InitializeMint2 = 20,
+    /** Transfer fee extension prefix */
+    TransferFeeExtension = 26,
+    /** Initialize non-transferable mint */
+    InitializeNonTransferableMint = 32,
+    /** Initialize permanent delegate */
+    InitializePermanentDelegate = 35,
+    /** Transfer hook extension prefix */
+    TransferHookExtension = 36,
+    /** Metadata pointer extension prefix */
+    MetadataPointerExtension = 39
 }
+/** Size of extension type field in TLV (2 bytes LE u16) */
+declare const TLV_TYPE_SIZE = 2;
+/** Size of extension length field in TLV (2 bytes LE u16) */
+declare const TLV_LENGTH_SIZE = 2;
 
 /**
- * TypeScript interfaces for SPL Token-2022 accounts and operations.
+ * TypeScript interfaces for MVP SPL Token-2022 accounts and operations.
  */
 
 /**
@@ -496,6 +742,15 @@ interface TransferParams {
     decimals: number;
     /** Whether to create destination ATA if it doesn't exist */
     createDestinationAta?: boolean;
+    /** Transfer fee to apply to the transfer */
+    transferFee?: {
+        fee: bigint;
+    };
+    /** Transfer hook configuration when the mint has a TransferHook extension */
+    transferHook?: {
+        /** The program invoked on every transfer (from TransferHook extension) */
+        hookProgramId: PublicKey;
+    };
 }
 /**
  * Result of deriving an Associated Token Address.
@@ -533,6 +788,73 @@ interface MetadataPointerExtension {
     /** Address where metadata is stored (usually same as mint for embedded) */
     metadataAddress: PublicKey | null;
 }
+interface TransferFee {
+    /** First epoch where the fee applies */
+    epoch: bigint;
+    /** Maximum fee assessed on transfers */
+    maximumFee: bigint;
+    /** Fee rate in basis points */
+    transferFeeBasisPoints: number;
+}
+interface TransferFeeConfigExtension {
+    /** Authority allowed to update fees */
+    transferFeeConfigAuthority: PublicKey | null;
+    /** Authority allowed to withdraw withheld fees */
+    withdrawWithheldAuthority: PublicKey | null;
+    /** Withheld fees already harvested to the mint */
+    withheldAmount: bigint;
+    /** Older transfer fee parameters */
+    olderTransferFee: TransferFee;
+    /** Newer transfer fee parameters */
+    newerTransferFee: TransferFee;
+}
+interface TransferFeeAmountExtension {
+    /** Withheld transfer fees on the account */
+    withheldAmount: bigint;
+}
+interface NonTransferableExtension {
+    /** Marker indicating the mint is non-transferable */
+    isNonTransferable: true;
+}
+interface NonTransferableAccountExtension {
+    /** Marker indicating the account belongs to a non-transferable mint */
+    isNonTransferableAccount: true;
+}
+interface PermanentDelegateExtension {
+    /** The permanent delegate authority (null if set to zero pubkey) */
+    delegate: PublicKey | null;
+}
+interface TransferHookExtension {
+    /** Authority that can update the hook program (null if set to zero pubkey) */
+    authority: PublicKey | null;
+    /** The program invoked on every transfer (null if set to zero pubkey) */
+    programId: PublicKey | null;
+}
+type ParsedExtension = {
+    type: ExtensionType.TransferFeeConfig;
+    value: TransferFeeConfigExtension;
+} | {
+    type: ExtensionType.TransferFeeAmount;
+    value: TransferFeeAmountExtension;
+} | {
+    type: ExtensionType.NonTransferable;
+    value: NonTransferableExtension;
+} | {
+    type: ExtensionType.NonTransferableAccount;
+    value: NonTransferableAccountExtension;
+} | {
+    type: ExtensionType.MetadataPointer;
+    value: MetadataPointerExtension;
+} | {
+    type: ExtensionType.TokenMetadata;
+    value: TokenMetadata;
+} | {
+    type: ExtensionType.PermanentDelegate;
+    value: PermanentDelegateExtension;
+} | {
+    type: ExtensionType.TransferHook;
+    value: TransferHookExtension;
+};
 
 /**
  * High-level SPL Token-2022 client for token operations.
@@ -541,6 +863,25 @@ interface MetadataPointerExtension {
  * balances, reading mint info, and building transfer transactions.
  */
 
+/**
+ * Complete mint account data from a single RPC call.
+ *
+ * Combines mint info, token metadata, and raw extension data
+ * to avoid redundant `getAccountInfo` calls per mint.
+ */
+interface MintAccountData {
+    /** Parsed mint information (supply, decimals, authorities) */
+    mintInfo: MintInfo;
+    /** Token metadata if the TokenMetadata extension exists, null otherwise */
+    metadata: TokenMetadata | null;
+    /** Raw TLV extensions present on this mint (all types, including unparsed ones) */
+    rawExtensions: RawExtension[];
+}
+/**
+ * Type alias for a built transaction from TransactionBuilder.
+ * Using a local alias for clarity rather than inline ReturnType extraction.
+ */
+type BuiltTransaction = ReturnType<typeof TransactionBuilder.prototype.build>;
 /**
  * Options for creating an SplTokenClient.
  */
@@ -583,9 +924,16 @@ declare class SplTokenClient {
      */
     constructor({ client, programId, }: SplTokenClientOptions);
     /**
-     * Gets the token program ID this client is configured to use.
+     * Returns the Token-2022 program ID used by this client.
      */
     getProgramId(): PublicKey;
+    /**
+     * Returns the underlying RialoClient.
+     *
+     * Useful for advanced operations that need direct RPC access,
+     * such as MintBuilder which needs to calculate rent.
+     */
+    getRialoClient(): RialoClient;
     /**
      * Retrieves mint account information.
      *
@@ -595,10 +943,8 @@ declare class SplTokenClient {
      *
      * @example
      * ```typescript
-     * const mintInfo = await tokenClient.getMintInfo({ mint: mintPubkey });
-     * console.log(`Supply: ${mintInfo.supply}`);
-     * console.log(`Decimals: ${mintInfo.decimals}`);
-     * console.log(`Mint Authority: ${mintInfo.mintAuthority?.toString() ?? 'disabled'}`);
+     * const mintInfo = await tokenClient.getMintInfo({ mint });
+     * console.log(mintInfo.decimals);
      * ```
      */
     getMintInfo({ mint }: {
@@ -613,17 +959,33 @@ declare class SplTokenClient {
      *
      * @example
      * ```typescript
-     * const metadata = await tokenClient.getTokenMetadata({ mint: mintPubkey });
+     * const metadata = await tokenClient.getTokenMetadata({ mint });
      * if (metadata) {
-     *   console.log(`Name: ${metadata.name}`);
-     *   console.log(`Symbol: ${metadata.symbol}`);
-     *   console.log(`URI: ${metadata.uri}`);
+     *   console.log(metadata.name, metadata.symbol);
      * }
      * ```
      */
-    getTokenMetadata({ mint }: {
+    getTokenMetadata({ mint, }: {
         mint: PublicKey;
     }): Promise<TokenMetadata | null>;
+    /**
+     * Retrieves complete mint account data in a single RPC call.
+     *
+     * Returns parsed mint info, token metadata, and raw extensions from one
+     * `getAccountInfo` call, avoiding the redundant RPC calls that occur when
+     * calling `getMintInfo()` and `getTokenMetadata()` separately.
+     *
+     * Raw extensions include ALL extension types (including PermanentDelegate,
+     * TransferHook, etc.) unlike `getMintExtensionStates()` which only parses
+     * a subset.
+     *
+     * @param options - Options containing the mint public key
+     * @returns Combined mint info, metadata, and raw extensions
+     * @throws {SplTokenError} If the mint account doesn't exist
+     */
+    getMintAccountData({ mint, }: {
+        mint: PublicKey;
+    }): Promise<MintAccountData>;
     /**
      * Retrieves token account information.
      *
@@ -649,7 +1011,7 @@ declare class SplTokenClient {
      * console.log(`Token balance: ${balance}`);
      * ```
      */
-    getBalance({ wallet, mint }: {
+    getBalance({ wallet, mint, }: {
         wallet: PublicKey;
         mint: PublicKey;
     }): Promise<bigint>;
@@ -658,6 +1020,7 @@ declare class SplTokenClient {
      *
      * @param options - Options containing wallet and mint public keys
      * @returns The derived ATA address and bump seed
+     * @throws {SplTokenError} If the ATA derivation fails
      *
      * @example
      * ```typescript
@@ -675,19 +1038,18 @@ declare class SplTokenClient {
      * @param options - Options containing wallet and mint public keys
      * @returns True if the ATA exists, false otherwise
      */
-    ataExists({ wallet, mint }: {
+    ataExists({ wallet, mint, }: {
         wallet: PublicKey;
         mint: PublicKey;
     }): Promise<boolean>;
     /**
      * Creates instructions for a token transfer.
      *
-     * This builds the necessary instructions for transferring tokens,
+     * Builds the necessary instructions for transferring tokens,
      * optionally creating the destination ATA if it doesn't exist.
      *
      * @param params - Transfer parameters
      * @returns Array of instructions to execute
-     * @throws {SplTokenError} If the mint doesn't exist
      *
      * @example
      * ```typescript
@@ -702,9 +1064,6 @@ declare class SplTokenClient {
      * ```
      */
     createTransferInstructions(params: TransferParams): Promise<Instruction[]>;
-    /**
-     * Options for creating a transfer transaction.
-     */
     /**
      * Creates a transaction for a token transfer.
      *
@@ -735,13 +1094,14 @@ declare class SplTokenClient {
      * const signature = await rialoClient.sendTransaction(signedTx.serialize());
      * ```
      */
-    createTransferTransaction({ params, validFrom, configHashPrefix, }: {
+    createTransferTransaction({ params, payer, validFrom, configHashPrefix, }: {
         params: TransferParams;
+        payer: PublicKey;
         validFrom: bigint;
         configHashPrefix: bigint;
-    }): Promise<ReturnType<typeof TransactionBuilder.prototype.build>>;
+    }): Promise<BuiltTransaction>;
     /**
-     * Transfers tokens from one wallet to another.
+     * Transfers tokens and sends the transaction.
      *
      * This is a high-level convenience method that:
      * 1. Creates the destination ATA if needed
@@ -749,7 +1109,7 @@ declare class SplTokenClient {
      * 3. Signs and sends the transaction
      * 4. Waits for confirmation
      *
-     * @param options - Options containing params, validFrom, and signer
+     * @param options - Transfer params, payer, validFrom, and signers
      * @returns Transaction signature
      *
      * @example
@@ -771,85 +1131,435 @@ declare class SplTokenClient {
      * console.log(`Transfer complete: ${signature}`);
      * ```
      */
-    transfer({ params, validFrom, configHashPrefix, signer, }: {
+    transfer({ params, payer, validFrom, configHashPrefix, signers, }: {
         params: TransferParams;
+        payer: PublicKey;
         validFrom: bigint;
         configHashPrefix: bigint;
-        signer: Signer;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Initializes a mint and sends the transaction.
+     *
+     * @param options - Initialize mint params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    initializeMint({ params, payer, validFrom, signers, }: {
+        params: InitializeMintInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Mints tokens and sends the transaction.
+     *
+     * @param options - Mint-to params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    mintTo({ params, payer, validFrom, signers, }: {
+        params: MintToInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Initializes token metadata on a mint.
+     *
+     * Use this for the on-mint TokenMetadata extension flow.
+     *
+     * @param options - Token metadata params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    initializeTokenMetadata({ params, payer, validFrom, signers, }: {
+        params: InitializeTokenMetadataInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Initializes a metadata pointer extension on a mint.
+     *
+     * Use this for the Metadata Pointer flow, where metadata lives in
+     * a separate account and the mint stores a pointer to it.
+     *
+     * @param options - Metadata pointer params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    initializeMetadataPointer({ params, payer, validFrom, signers, }: {
+        params: InitializeMetadataPointerInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Updates a metadata pointer extension on a mint.
+     *
+     * @param options - Metadata pointer params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    updateMetadataPointer({ params, payer, validFrom, signers, }: {
+        params: UpdateMetadataPointerInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Initializes a transfer fee config on a mint.
+     *
+     * @param options - Transfer fee config params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    initializeTransferFeeConfig({ params, payer, validFrom, signers, }: {
+        params: InitializeTransferFeeConfigInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Transfers tokens with a fee and sends the transaction.
+     *
+     * @param options - Transfer params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    transferCheckedWithFee({ params, payer, validFrom, signers, }: {
+        params: TransferCheckedWithFeeInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
+    }): Promise<string>;
+    /**
+     * Initializes a non-transferable mint.
+     *
+     * @param options - Non-transferable mint params, payer, validFrom, and signers
+     * @returns Transaction signature
+     */
+    initializeNonTransferableMint({ params, payer, validFrom, signers, }: {
+        params: InitializeNonTransferableMintInstructionOptions;
+        payer: PublicKey;
+        validFrom: bigint;
+        signers: Signer[];
     }): Promise<string>;
+    private signAndSend;
 }
 /**
- * Options for creating an SplTokenClient via the factory function.
+ * Factory function to create a SplTokenClient.
+ *
+ * @example
+ * ```typescript
+ * const tokenClient = createSplTokenClient({ client: rialoClient });
+ * ```
  */
-interface CreateSplTokenClientOptions {
-    /** The underlying RialoClient for RPC calls */
-    client: RialoClient;
-    /** Token program ID (defaults to Token-2022) */
-    programId?: PublicKey;
-}
+declare function createSplTokenClient(options: SplTokenClientOptions): SplTokenClient;
+
 /**
- * Creates a new SplTokenClient.
+ * Fluent builder for creating SPL Token-2022 mints with extensions.
  *
- * Factory function for creating an SplTokenClient instance.
- *
- * @param options - Options for creating the client
- * @returns Configured SplTokenClient instance
+ * MintBuilder simplifies the process of creating mints by providing a
+ * chainable API that handles:
+ * - Account size calculation
+ * - Rent-exempt balance calculation
+ * - Instruction ordering (extensions must be initialized before mint)
+ * - Transaction building
  *
  * @example
  * ```typescript
- * import { createRialoClient, RIALO_DEVNET_CHAIN } from '@rialo/ts-cdk';
- * import { createSplTokenClient } from '@rialo/spl-token';
+ * import { MintBuilder, createSplTokenClient } from "@rialo/spl-token";
  *
- * const rialoClient = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
- * const tokenClient = createSplTokenClient({ client: rialoClient });
+ * const tokenClient = createSplTokenClient({ client });
+ *
+ * const { signature, mintAddress } = await MintBuilder.create(tokenClient)
+ *   .withDecimals(9)
+ *   .withMintAuthority(authority)
+ *   .withMetadata({
+ *     name: "My Token",
+ *     symbol: "MTK",
+ *     uri: "https://example.com/metadata.json",
+ *   })
+ *   .send({
+ *     payer: authority,
+ *     mintKeypair,
+ *     validFrom: BigInt(Date.now()),
+ *     signers: [authorityKeypair, mintKeypair],
+ *   });
  * ```
  */
-declare function createSplTokenClient({ client, programId, }: CreateSplTokenClientOptions): SplTokenClient;
 
 /**
- * Error handling for SPL Token operations.
- *
- * This module defines the error types and factory methods for all
- * SPL Token-related operations, following the same pattern as RialoError.
+ * Token metadata configuration for MintBuilder.
  */
+interface MintMetadataConfig {
+    /** Token name */
+    name: string;
+    /** Token symbol */
+    symbol: string;
+    /** Token URI (typically points to JSON metadata) */
+    uri: string;
+    /** Optional additional metadata key-value pairs */
+    additionalMetadata?: Array<[string, string]>;
+}
 /**
- * Error codes for SPL Token operations.
+ * Transfer fee configuration for MintBuilder.
  */
-declare enum SplTokenErrorCode {
-    /** Invalid mint account data */
-    INVALID_MINT = "INVALID_MINT",
-    /** Invalid token account data */
-    INVALID_TOKEN_ACCOUNT = "INVALID_TOKEN_ACCOUNT",
-    /** Token account not found */
-    TOKEN_ACCOUNT_NOT_FOUND = "TOKEN_ACCOUNT_NOT_FOUND",
-    /** Mint account not found */
-    MINT_NOT_FOUND = "MINT_NOT_FOUND",
-    /** Token account is frozen */
-    ACCOUNT_FROZEN = "ACCOUNT_FROZEN",
-    /** Insufficient token balance */
-    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
-    /** Invalid extension data */
-    INVALID_EXTENSION = "INVALID_EXTENSION",
-    /** PDA derivation failed */
-    PDA_DERIVATION_FAILED = "PDA_DERIVATION_FAILED",
-    /** Invalid metadata */
-    INVALID_METADATA = "INVALID_METADATA",
-    /** Account not initialized */
-    ACCOUNT_NOT_INITIALIZED = "ACCOUNT_NOT_INITIALIZED"
+interface MintTransferFeeConfig {
+    /** Transfer fee authority */
+    transferFeeConfigAuthority: PublicKey;
+    /** Withdraw withheld authority */
+    withdrawWithheldAuthority: PublicKey;
+    /** Fee rate in basis points (100 = 1%) */
+    transferFeeBasisPoints: number;
+    /** Maximum fee in smallest units */
+    maximumFee: bigint;
 }
 /**
- * Constructor options for SplTokenError.
+ * Initial mint configuration for MintBuilder.
  */
-interface SplTokenErrorOptions {
-    code: SplTokenErrorCode;
-    message: string;
-    details?: Record<string, unknown>;
+interface MintInitialSupplyConfig {
+    /** Wallet address to receive initial tokens (ATA will be derived) */
+    destination: PublicKey;
+    /** Amount to mint in smallest units */
+    amount: bigint;
 }
 /**
- * Error class for SPL Token operations.
- *
- * Provides structured error handling with error codes and optional details.
- * Use the static factory methods for consistent error creation.
+ * Options for building a mint transaction.
+ */
+interface MintBuildOptions {
+    /** Fee payer for the transaction */
+    payer: PublicKey;
+    /** Keypair for the new mint account */
+    mintKeypair: Keypair;
+    /** Transaction validity timestamp */
+    validFrom: bigint;
+}
+/**
+ * Options for sending a mint transaction.
+ */
+interface MintSendOptions extends MintBuildOptions {
+    /** Keypairs for signing the transaction (must include payer and mintKeypair) */
+    signers: Keypair[];
+}
+/**
+ * Result of building a mint transaction.
+ */
+interface MintBuildResult {
+    /** The built transaction, ready for signing */
+    transaction: ReturnType<typeof TransactionBuilder.prototype.build>;
+    /** The mint address */
+    mintAddress: PublicKey;
+    /** The ATA address if initial supply was configured */
+    ataAddress?: PublicKey;
+}
+/**
+ * Result of sending a mint transaction.
+ */
+interface MintSendResult {
+    /** Transaction signature */
+    signature: string;
+    /** The mint address */
+    mintAddress: PublicKey;
+    /** The ATA address if initial supply was configured */
+    ataAddress?: PublicKey;
+}
+/**
+ * Fluent builder for creating SPL Token-2022 mints with extensions.
+ *
+ * Use `MintBuilder.create(tokenClient)` to start building.
+ */
+declare class MintBuilder {
+    private readonly client;
+    private readonly programId;
+    private decimals;
+    private mintAuthority;
+    private freezeAuthority;
+    private metadata;
+    private transferFee;
+    private nonTransferable;
+    private permanentDelegate;
+    private transferHook;
+    private initialSupply;
+    private constructor();
+    /**
+     * Creates a new MintBuilder instance.
+     *
+     * @param tokenClient - SplTokenClient instance
+     * @returns A new MintBuilder
+     *
+     * @example
+     * ```typescript
+     * const builder = MintBuilder.create(tokenClient);
+     * ```
+     */
+    static create(tokenClient: SplTokenClient): MintBuilder;
+    /**
+     * Sets the number of decimals for the token.
+     *
+     * SPL Token-2022 stores decimals as a u8, so values from 0 to 255 are
+     * valid at the protocol level. Common choices are 6 (USDC-style) or 9
+     * (SOL-style). Values above 9 are uncommon on Solana but fully supported.
+     *
+     * @param decimals - Number of decimals (0-255)
+     * @returns this for chaining
+     */
+    withDecimals(decimals: number): this;
+    /**
+     * Sets the mint authority.
+     *
+     * @param authority - Public key of the mint authority
+     * @returns this for chaining
+     */
+    withMintAuthority(authority: PublicKey): this;
+    /**
+     * Sets the freeze authority.
+     *
+     * @param authority - Public key of the freeze authority
+     * @returns this for chaining
+     */
+    withFreezeAuthority(authority: PublicKey): this;
+    /**
+     * Configures token metadata extension.
+     *
+     * This enables both MetadataPointer and TokenMetadata extensions,
+     * with the metadata stored directly on the mint account.
+     *
+     * @param metadata - Token metadata configuration
+     * @returns this for chaining
+     */
+    withMetadata(metadata: MintMetadataConfig): this;
+    /**
+     * Configures transfer fee extension.
+     *
+     * @param config - Transfer fee configuration
+     * @returns this for chaining
+     */
+    withTransferFee(config: MintTransferFeeConfig): this;
+    /**
+     * Makes the mint non-transferable.
+     *
+     * Non-transferable tokens (soulbound tokens) cannot be transferred
+     * after minting.
+     *
+     * @returns this for chaining
+     */
+    withNonTransferable(): this;
+    /**
+     * Configures permanent delegate extension.
+     *
+     * A permanent delegate has unrestricted transfer and burn authority
+     * over all token accounts for this mint.
+     *
+     * @param delegate - Public key of the permanent delegate
+     * @returns this for chaining
+     */
+    withPermanentDelegate(delegate: PublicKey): this;
+    /**
+     * Configures transfer hook extension.
+     *
+     * A transfer hook invokes a specified program on every token transfer,
+     * enabling custom transfer logic (e.g., compliance checks, royalties).
+     *
+     * @param config - Transfer hook configuration
+     * @returns this for chaining
+     */
+    withTransferHook(config: {
+        authority: PublicKey;
+        programId: PublicKey;
+    }): this;
+    /**
+     * Configures initial token supply to mint after creation.
+     *
+     * The tokens will be minted to an Associated Token Account (ATA)
+     * derived from the destination wallet.
+     *
+     * @param config - Initial supply configuration
+     * @returns this for chaining
+     */
+    withInitialSupply(config: MintInitialSupplyConfig): this;
+    /**
+     * Builds the mint transaction without sending.
+     *
+     * @param options - Build options
+     * @returns Build result with transaction and addresses
+     *
+     * @example
+     * ```typescript
+     * const { transaction, mintAddress } = await builder.build({
+     *   payer: authority,
+     *   mintKeypair,
+     *   validFrom: BigInt(Date.now()),
+     * });
+     *
+     * // Sign manually
+     * const signed = transaction.sign(authorityKeypair).sign(mintKeypair);
+     * await client.sendAndConfirmTransaction(signed.serialize());
+     * ```
+     */
+    build(options: MintBuildOptions): Promise<MintBuildResult>;
+    /**
+     * Builds, signs, and sends the mint transaction.
+     *
+     * @param options - Send options including signers
+     * @returns Send result with signature and addresses
+     *
+     * @example
+     * ```typescript
+     * const { signature, mintAddress } = await builder.send({
+     *   payer: authority,
+     *   mintKeypair,
+     *   validFrom: BigInt(Date.now()),
+     *   signers: [authorityKeypair, mintKeypair],
+     * });
+     * ```
+     */
+    send(options: MintSendOptions): Promise<MintSendResult>;
+    /**
+     * Returns the list of extensions that will be enabled.
+     */
+    private getExtensions;
+}
+
+/**
+ * Error handling for SPL Token operations.
+ *
+ * This module defines the error types and factory methods for all
+ * SPL Token-related operations, following the same pattern as RialoError.
+ */
+/**
+ * Error codes for SPL Token operations.
+ */
+declare enum SplTokenErrorCode {
+    /** Invalid mint account data */
+    INVALID_MINT = "INVALID_MINT",
+    /** Invalid token account data */
+    INVALID_TOKEN_ACCOUNT = "INVALID_TOKEN_ACCOUNT",
+    /** Token account not found */
+    TOKEN_ACCOUNT_NOT_FOUND = "TOKEN_ACCOUNT_NOT_FOUND",
+    /** Mint account not found */
+    MINT_NOT_FOUND = "MINT_NOT_FOUND",
+    /** Token account is frozen */
+    ACCOUNT_FROZEN = "ACCOUNT_FROZEN",
+    /** Insufficient token balance */
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE",
+    /** Invalid extension data */
+    INVALID_EXTENSION = "INVALID_EXTENSION",
+    /** PDA derivation failed */
+    PDA_DERIVATION_FAILED = "PDA_DERIVATION_FAILED",
+    /** Invalid metadata */
+    INVALID_METADATA = "INVALID_METADATA",
+    /** Account not initialized */
+    ACCOUNT_NOT_INITIALIZED = "ACCOUNT_NOT_INITIALIZED"
+}
+/**
+ * Constructor options for SplTokenError.
+ */
+interface SplTokenErrorOptions {
+    code: SplTokenErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Error class for SPL Token operations.
+ *
+ * Provides structured error handling with error codes and optional details.
+ * Use the static factory methods for consistent error creation.
  *
  * @example
  * ```typescript
@@ -956,68 +1666,378 @@ declare class SplTokenError extends Error {
 }
 
 /**
- * Mint account parsing for SPL Token-2022.
+ * Size calculation helpers for SPL Token-2022 accounts with extensions.
+ *
+ * These utilities simplify the process of calculating account sizes and
+ * rent-exempt balances when creating mints with Token-2022 extensions.
+ *
+ * @example
+ * ```typescript
+ * import { getMintSizeWithExtensions, ExtensionType } from "@rialo/spl-token";
+ *
+ * const size = getMintSizeWithExtensions({
+ *   extensions: [ExtensionType.MetadataPointer],
+ *   metadataSize: getMetadataExtensionSize({ name: "My Token", symbol: "MTK", uri: "https://..." }),
+ * });
+ * ```
  */
 
 /**
- * Options for parsing a mint account.
+ * Options for calculating mint size with extensions.
  */
-interface ParseMintAccountOptions {
-    /** The mint account's public key */
-    address: PublicKey;
-    /** Raw account data bytes (minimum 82 bytes) */
-    data: Uint8Array;
+interface GetMintSizeWithExtensionsOptions {
+    /** Array of extension types to include */
+    extensions: ExtensionType[];
+    /**
+     * Size of token metadata data in bytes.
+     * Required if extensions includes ExtensionType.TokenMetadata.
+     * Use getMetadataExtensionSize() to calculate this.
+     */
+    metadataSize?: number;
 }
 /**
- * Parses raw mint account data into a structured MintInfo object.
+ * Calculates the total size of a mint account with the specified extensions.
  *
- * @param options - Options containing address and data
- * @returns Parsed mint information
- * @throws {SplTokenError} If the data is invalid or too short
+ * The size includes:
+ * - Base mint size (82 bytes)
+ * - Account type discriminator (1 byte)
+ * - TLV headers and data for each extension
+ *
+ * Note: The base mint account is padded to TOKEN_ACCOUNT_SIZE (165 bytes) when
+ * extensions are present, to maintain alignment.
+ *
+ * @param options - Extension configuration
+ * @returns Total account size in bytes
  *
  * @example
  * ```typescript
- * const accountInfo = await client.getAccountInfo(mintPubkey);
- * if (accountInfo) {
- *   const mintInfo = parseMintAccount({ address: mintPubkey, data: accountInfo.data });
- *   console.log(`Supply: ${mintInfo.supply}`);
- *   console.log(`Decimals: ${mintInfo.decimals}`);
- * }
+ * // Mint with metadata pointer only
+ * const sizePointerOnly = getMintSizeWithExtensions({
+ *   extensions: [ExtensionType.MetadataPointer],
+ * });
+ *
+ * // Mint with metadata pointer + full metadata
+ * const metadataSize = getMetadataExtensionSize({
+ *   name: "My Token",
+ *   symbol: "MTK",
+ *   uri: "https://example.com/metadata.json",
+ * });
+ * const sizeWithMetadata = getMintSizeWithExtensions({
+ *   extensions: [ExtensionType.MetadataPointer, ExtensionType.TokenMetadata],
+ *   metadataSize,
+ * });
  * ```
  */
-declare function parseMintAccount({ address, data }: ParseMintAccountOptions): MintInfo;
+declare function getMintSizeWithExtensions({ extensions, metadataSize, }: GetMintSizeWithExtensionsOptions): number;
+/**
+ * Calculates the size of token metadata extension data.
+ *
+ * This is a convenience re-export of getTokenMetadataDataSize for use
+ * with getMintSizeWithExtensions.
+ *
+ * @param metadata - Token metadata fields
+ * @returns Size of the metadata data in bytes (excluding TLV header)
+ *
+ * @example
+ * ```typescript
+ * const metadataSize = getMetadataExtensionSize({
+ *   name: "Rialo Test Token",
+ *   symbol: "RTST",
+ *   uri: "https://picsum.photos/id/237/50/50",
+ * });
+ * // metadataSize can now be passed to getMintSizeWithExtensions
+ * ```
+ */
+declare function getMetadataExtensionSize({ name, symbol, uri, additionalMetadata, }: {
+    name: string;
+    symbol: string;
+    uri: string;
+    additionalMetadata?: Array<[string, string]>;
+}): number;
+/**
+ * Calculates the minimum lamports required for a mint account to be rent-exempt.
+ *
+ * @param client - Rialo client for RPC calls
+ * @param options - Extension configuration
+ * @returns Minimum balance for rent exemption in lamports
+ *
+ * @example
+ * ```typescript
+ * const rent = await getMinRentForMint(client, {
+ *   extensions: [ExtensionType.MetadataPointer, ExtensionType.TokenMetadata],
+ *   metadataSize: getMetadataExtensionSize({ name, symbol, uri }),
+ * });
+ * ```
+ */
+declare function getMinRentForMint(client: RialoClient, options: GetMintSizeWithExtensionsOptions): Promise<bigint>;
+/**
+ * Calculates the size of a mint account with metadata pointer and token metadata.
+ *
+ * This is a convenience function for the common case of creating a mint
+ * with embedded metadata (metadata pointer pointing to self + token metadata).
+ *
+ * @param metadata - Token metadata fields
+ * @returns Total account size in bytes
+ *
+ * @example
+ * ```typescript
+ * const size = getMintSizeWithMetadata({
+ *   name: "Rialo Test Token",
+ *   symbol: "RTST",
+ *   uri: "https://example.com/metadata.json",
+ * });
+ * const rent = await client.getMinimumBalanceForRentExemption(BigInt(size));
+ * ```
+ */
+declare function getMintSizeWithMetadata({ name, symbol, uri, additionalMetadata, }: {
+    name: string;
+    symbol: string;
+    uri: string;
+    additionalMetadata?: Array<[string, string]>;
+}): number;
+/**
+ * Calculates the minimum lamports required for a mint with metadata to be rent-exempt.
+ *
+ * Convenience function that combines size calculation and rent lookup for the
+ * common case of creating a mint with embedded metadata.
+ *
+ * @param client - Rialo client for RPC calls
+ * @param metadata - Token metadata fields
+ * @returns Minimum balance for rent exemption in lamports
+ *
+ * @example
+ * ```typescript
+ * const rent = await getMinRentForMintWithMetadata(client, {
+ *   name: "Rialo Test Token",
+ *   symbol: "RTST",
+ *   uri: "https://example.com/metadata.json",
+ * });
+ * ```
+ */
+declare function getMinRentForMintWithMetadata(client: RialoClient, metadata: {
+    name: string;
+    symbol: string;
+    uri: string;
+    additionalMetadata?: Array<[string, string]>;
+}): Promise<bigint>;
 
 /**
- * Token account parsing for SPL Token-2022.
+ * Options for finding an Associated Token Address.
+ */
+interface FindAssociatedTokenAddressOptions {
+    /** The wallet's public key (owner of the token account) */
+    wallet: PublicKey;
+    /** The token mint's public key */
+    mint: PublicKey;
+    /** The token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Finds the Associated Token Address for a wallet and mint.
+ *
+ * The ATA is derived using the following seeds:
+ * - wallet address (32 bytes)
+ * - token program ID (32 bytes)
+ * - mint address (32 bytes)
+ *
+ * @param options - Options containing wallet, mint, and optional programId
+ * @returns The derived ATA address and bump seed
+ * @throws {SplTokenError} If PDA derivation fails
+ *
+ * @example
+ * ```typescript
+ * const { address, bump } = findAssociatedTokenAddress({ wallet: walletPubkey, mint: mintPubkey });
+ * console.log(`ATA: ${address.toString()}`);
+ * console.log(`Bump: ${bump}`);
+ * ```
+ */
+declare function findAssociatedTokenAddress({ wallet, mint, programId, }: FindAssociatedTokenAddressOptions): AtaDerivationResult;
+/**
+ * Options for getting the Associated Token Address synchronously.
  */
+interface GetAssociatedTokenAddressSyncOptions {
+    /** The wallet's public key */
+    wallet: PublicKey;
+    /** The token mint's public key */
+    mint: PublicKey;
+    /** The token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Gets the Associated Token Address without the bump seed.
+ *
+ * Convenience function when you only need the address.
+ *
+ * @param options - Options containing wallet, mint, and optional programId
+ * @returns The derived ATA address
+ */
+declare function getAssociatedTokenAddressSync({ wallet, mint, programId, }: GetAssociatedTokenAddressSyncOptions): PublicKey;
 
 /**
- * Options for parsing a token account.
+ * High-level recipe for creating a Token-2022 mint with metadata.
+ *
+ * This module provides a simple, one-call function to create a new token
+ * with metadata extension, optionally minting initial supply.
+ *
+ * @example
+ * ```typescript
+ * import { createSplTokenClient, createTokenWithMetadata } from "@rialo/spl-token";
+ *
+ * const tokenClient = createSplTokenClient({ client });
+ *
+ * const { signature, mintAddress } = await createTokenWithMetadata(tokenClient, {
+ *   decimals: 9,
+ *   mintAuthority: masterPubkey,
+ *   metadata: {
+ *     name: "Rialo Test Token",
+ *     symbol: "RTST",
+ *     uri: "https://example.com/image.png",
+ *   },
+ *   initialMint: {
+ *     destination: masterPubkey,
+ *     amount: 1_000_000_000_000_000n,
+ *   },
+ * }, {
+ *   payer: masterPubkey,
+ *   mintKeypair,
+ *   validFrom: BigInt(Date.now()),
+ *   signers: [masterKeypair, mintKeypair],
+ * });
+ * ```
  */
-interface ParseTokenAccountOptions {
-    /** The token account's public key */
-    address: PublicKey;
-    /** Raw account data bytes (minimum 165 bytes) */
-    data: Uint8Array;
+
+/**
+ * Token metadata configuration.
+ */
+interface TokenMetadataParams {
+    /** Token name */
+    name: string;
+    /** Token symbol */
+    symbol: string;
+    /** Token URI (typically points to JSON metadata or an image) */
+    uri: string;
+    /** Optional additional metadata key-value pairs */
+    additionalMetadata?: Array<[string, string]>;
 }
 /**
- * Parses raw token account data into a structured TokenAccountInfo object.
+ * Parameters for creating a token with metadata.
+ */
+interface CreateTokenWithMetadataParams {
+    /** Number of decimals for the token (0-255, SPL Token-2022 stores this as a u8) */
+    decimals: number;
+    /** Public key of the mint authority */
+    mintAuthority: PublicKey;
+    /** Optional freeze authority */
+    freezeAuthority?: PublicKey;
+    /** Token metadata configuration */
+    metadata: TokenMetadataParams;
+    /**
+     * Optional initial mint configuration.
+     * If provided, tokens will be minted to the destination wallet's ATA.
+     */
+    initialMint?: {
+        /** Wallet address to receive initial tokens */
+        destination: PublicKey;
+        /** Amount to mint in smallest units */
+        amount: bigint;
+    };
+}
+/**
+ * Transaction options for creating a token.
+ */
+interface CreateTokenWithMetadataOptions {
+    /** Fee payer for the transaction */
+    payer: PublicKey;
+    /** Keypair for the new mint account */
+    mintKeypair: Keypair;
+    /** Transaction validity timestamp (milliseconds since epoch) */
+    validFrom: bigint;
+    /** Keypairs for signing the transaction (must include payer and mintKeypair) */
+    signers: Keypair[];
+}
+/**
+ * Result of creating a token with metadata.
+ */
+interface CreateTokenWithMetadataResult {
+    /** Transaction signature */
+    signature: string;
+    /** The mint address */
+    mintAddress: PublicKey;
+    /** The ATA address if initial mint was configured */
+    ataAddress?: PublicKey;
+}
+/**
+ * Creates a new SPL Token-2022 mint with metadata extension.
  *
- * @param options - Options containing address and data
- * @returns Parsed token account information
- * @throws {SplTokenError} If the data is invalid or too short
+ * This is a high-level convenience function that handles:
+ * - Account size calculation for metadata
+ * - Rent-exempt balance calculation
+ * - Creating the mint account
+ * - Initializing metadata pointer and metadata extensions
+ * - Optionally creating an ATA and minting initial supply
+ *
+ * @param tokenClient - SplTokenClient instance
+ * @param params - Token configuration parameters
+ * @param options - Transaction options
+ * @returns Result with signature and addresses
  *
  * @example
  * ```typescript
- * const accountInfo = await client.getAccountInfo(tokenAccountPubkey);
- * if (accountInfo) {
- *   const tokenAccount = parseTokenAccount({ address: tokenAccountPubkey, data: accountInfo.data });
- *   console.log(`Balance: ${tokenAccount.amount}`);
- *   console.log(`Owner: ${tokenAccount.owner.toString()}`);
- * }
+ * // Simple token creation
+ * const { mintAddress } = await createTokenWithMetadata(tokenClient, {
+ *   decimals: 9,
+ *   mintAuthority: authority,
+ *   metadata: { name: "My Token", symbol: "MTK", uri: "https://..." },
+ * }, { payer: authority, mintKeypair, validFrom: BigInt(Date.now()), signers: [authorityKeypair, mintKeypair] });
+ *
+ * // With initial supply
+ * const { mintAddress, ataAddress } = await createTokenWithMetadata(tokenClient, {
+ *   decimals: 9,
+ *   mintAuthority: authority,
+ *   metadata: { name: "My Token", symbol: "MTK", uri: "https://..." },
+ *   initialMint: { destination: authority, amount: 1_000_000_000n },
+ * }, { payer: authority, mintKeypair, validFrom: BigInt(Date.now()), signers: [authorityKeypair, mintKeypair] });
  * ```
  */
-declare function parseTokenAccount({ address, data }: ParseTokenAccountOptions): TokenAccountInfo;
+declare function createTokenWithMetadata(tokenClient: SplTokenClient, params: CreateTokenWithMetadataParams, options: CreateTokenWithMetadataOptions): Promise<CreateTokenWithMetadataResult>;
+
+declare function parseTransferFeeConfigExtension({ data, }: {
+    data: Uint8Array;
+}): TransferFeeConfigExtension;
+declare function parsePermanentDelegateExtension({ data, }: {
+    data: Uint8Array;
+}): PermanentDelegateExtension;
+declare function parseTransferHookExtension({ data }: {
+    data: Uint8Array;
+}): TransferHookExtension;
+declare function parseMetadataPointerExtensionData({ data, }: {
+    data: Uint8Array;
+}): MetadataPointerExtension;
+declare function parseTokenMetadataExtensionData({ data }: {
+    data: Uint8Array;
+}): TokenMetadata;
+declare function parseExtension({ extension }: {
+    extension: RawExtension;
+}): ParsedExtension | null;
+declare function getMintExtensionStates({ data }: {
+    data: Uint8Array;
+}): ParsedExtension[];
+declare function getTokenAccountExtensionStates({ data }: {
+    data: Uint8Array;
+}): ParsedExtension[];
+
+/**
+ * Gets all raw extensions from a mint account.
+ */
+declare function getMintExtensions({ data }: {
+    data: Uint8Array;
+}): RawExtension[];
+/**
+ * Gets all raw extensions from a token account.
+ */
+declare function getTokenAccountExtensions({ data }: {
+    data: Uint8Array;
+}): RawExtension[];
 
 /**
  * Token metadata parsing for SPL Token-2022 native metadata extension.
@@ -1073,71 +2093,261 @@ interface ParseMetadataPointerExtensionOptions {
  * @returns Parsed metadata pointer, or null if not present
  */
 declare function parseMetadataPointerExtension({ data, }: ParseMetadataPointerExtensionOptions): MetadataPointerExtension | null;
+
+/**
+ * Mint account parsing for SPL Token-2022.
+ */
+
 /**
- * Options for getting mint extensions.
+ * Options for parsing a mint account.
  */
-interface GetMintExtensionsOptions {
-    /** Raw mint account data */
+interface ParseMintAccountOptions {
+    /** The mint account's public key */
+    address: PublicKey;
+    /** Raw account data bytes (minimum 82 bytes) */
     data: Uint8Array;
 }
 /**
- * Gets all raw extensions from a mint account.
+ * Parses raw mint account data into a structured MintInfo object.
  *
- * @param options - Options containing data
- * @returns Array of raw extensions, or empty array if no extensions
+ * @param options - Options containing address and data
+ * @returns Parsed mint information
+ * @throws {SplTokenError} If the data is invalid or too short
+ *
+ * @example
+ * ```typescript
+ * const accountInfo = await client.getAccountInfo(mintPubkey);
+ * if (accountInfo) {
+ *   const mintInfo = parseMintAccount({ address: mintPubkey, data: accountInfo.data });
+ *   console.log(`Supply: ${mintInfo.supply}`);
+ *   console.log(`Decimals: ${mintInfo.decimals}`);
+ * }
+ * ```
  */
-declare function getMintExtensions({ data }: GetMintExtensionsOptions): RawExtension[];
+declare function parseMintAccount({ address, data }: ParseMintAccountOptions): MintInfo;
 
 /**
- * Options for finding an Associated Token Address.
+ * Token account parsing for SPL Token-2022.
  */
-interface FindAssociatedTokenAddressOptions {
-    /** The wallet's public key (owner of the token account) */
-    wallet: PublicKey;
-    /** The token mint's public key */
-    mint: PublicKey;
-    /** The token program ID (defaults to Token-2022) */
-    programId?: PublicKey;
+
+/**
+ * Options for parsing a token account.
+ */
+interface ParseTokenAccountOptions {
+    /** The token account's public key */
+    address: PublicKey;
+    /** Raw account data bytes (minimum 165 bytes) */
+    data: Uint8Array;
 }
 /**
- * Finds the Associated Token Address for a wallet and mint.
- *
- * The ATA is derived using the following seeds:
- * - wallet address (32 bytes)
- * - token program ID (32 bytes)
- * - mint address (32 bytes)
+ * Parses raw token account data into a structured TokenAccountInfo object.
  *
- * @param options - Options containing wallet, mint, and optional programId
- * @returns The derived ATA address and bump seed
- * @throws {SplTokenError} If PDA derivation fails
+ * @param options - Options containing address and data
+ * @returns Parsed token account information
+ * @throws {SplTokenError} If the data is invalid or too short
  *
  * @example
  * ```typescript
- * const { address, bump } = findAssociatedTokenAddress({ wallet: walletPubkey, mint: mintPubkey });
- * console.log(`ATA: ${address.toString()}`);
- * console.log(`Bump: ${bump}`);
+ * const accountInfo = await client.getAccountInfo(tokenAccountPubkey);
+ * if (accountInfo) {
+ *   const tokenAccount = parseTokenAccount({ address: tokenAccountPubkey, data: accountInfo.data });
+ *   console.log(`Balance: ${tokenAccount.amount}`);
+ *   console.log(`Owner: ${tokenAccount.owner.toString()}`);
+ * }
  * ```
  */
-declare function findAssociatedTokenAddress({ wallet, mint, programId, }: FindAssociatedTokenAddressOptions): AtaDerivationResult;
+declare function parseTokenAccount({ address, data }: ParseTokenAccountOptions): TokenAccountInfo;
+
 /**
- * Options for getting the Associated Token Address synchronously.
+ * ExtraAccountMeta type definition and parser for Token-2022 transfer hooks.
+ *
+ * Each ExtraAccountMeta is a 35-byte fixed-size struct stored in the
+ * validation account's TLV data. It describes an additional account that
+ * must be included in the transfer instruction.
+ *
+ * Layout: [discriminator: u8] [addressConfig: [u8; 32]] [isSigner: u8] [isWritable: u8]
+ *
+ * Discriminator values:
+ * - 0: Static address (addressConfig is the pubkey)
+ * - 1: PDA derived from the hook program
+ * - 2: Pubkey extracted from on-chain account data
+ * - 128+i: PDA derived from account[i]'s pubkey as the program ID
  */
-interface GetAssociatedTokenAddressSyncOptions {
-    /** The wallet's public key */
-    wallet: PublicKey;
-    /** The token mint's public key */
+/**
+ * A single extra account descriptor from the ExtraAccountMetaList.
+ */
+interface ExtraAccountMeta {
+    /** Discriminator indicating how to resolve the address. */
+    discriminator: number;
+    /** 32-byte address configuration (pubkey or packed seeds). */
+    addressConfig: Uint8Array;
+    /** Whether this account must be a signer. */
+    isSigner: boolean;
+    /** Whether this account must be writable. */
+    isWritable: boolean;
+}
+/** Size of a single ExtraAccountMeta entry in bytes (1 + 32 + 1 + 1). */
+declare const EXTRA_ACCOUNT_META_SIZE = 35;
+
+/**
+ * The Execute instruction discriminator.
+ *
+ * First 8 bytes of SHA-256("rialo-s-spl-transfer-hook-interface:execute").
+ * This matches the on-chain Rialo Transfer Hook Interface namespace.
+ */
+declare const EXECUTE_DISCRIMINATOR: Uint8Array;
+/**
+ * Parses the validation account's TLV data into ExtraAccountMeta entries.
+ *
+ * Format: [8-byte discriminator][4-byte u32 LE length][4-byte u32 LE count][N x 35-byte entries]
+ *
+ * Returns an empty array if the data is too short or the count is zero.
+ *
+ * @param data - Raw validation account data
+ * @returns Array of parsed ExtraAccountMeta entries
+ */
+declare function parseExtraAccountMetaList(data: Uint8Array): ExtraAccountMeta[];
+/**
+ * Builds the 16-byte Execute instruction data.
+ *
+ * Format: [8-byte EXECUTE_DISCRIMINATOR][8-byte amount as u64 LE]
+ *
+ * @param amount - The transfer amount
+ * @returns 16-byte instruction data buffer
+ */
+declare function buildExecuteInstructionData(amount: bigint): Uint8Array;
+/**
+ * Derives the ExtraAccountMetaList validation account PDA.
+ *
+ * Seeds: ["extra-account-metas", mint_pubkey]
+ * Program: hookProgramId
+ *
+ * @param mint - The token mint public key
+ * @param hookProgramId - The transfer hook program ID
+ * @returns The derived validation account public key
+ */
+declare function getExtraAccountMetaAddress(mint: PublicKey, hookProgramId: PublicKey): PublicKey;
+
+/**
+ * Dynamic account resolution for Token-2022 transfer hook ExtraAccountMetas.
+ *
+ * This module resolves each ExtraAccountMeta into a concrete AccountMeta
+ * (pubkey + isSigner + isWritable) by handling all discriminator types:
+ * - 0: Static address (addressConfig is the pubkey directly)
+ * - 1: PDA derived from the hook program with unpacked seeds
+ * - 2: Pubkey extracted from on-chain account data
+ * - 128+: PDA derived from a previously-resolved account's pubkey as program ID
+ *
+ * The top-level `resolveTransferHookExtraAccounts` function orchestrates the full
+ * resolution algorithm: fetch validation PDA, parse TLV, resolve each meta
+ * sequentially, de-escalate signers, and append trailing accounts.
+ */
+
+/**
+ * Callback type for fetching on-chain account data.
+ */
+type FetchAccountDataFn = (pubkey: PublicKey) => Promise<Uint8Array | null>;
+/**
+ * Parameters for resolving a single ExtraAccountMeta.
+ */
+interface ResolveExtraAccountMetaParams {
+    /** The ExtraAccountMeta to resolve */
+    meta: ExtraAccountMeta;
+    /** All accounts resolved so far (base 5 + previous extras) */
+    previousMetas: AccountMeta[];
+    /** The Execute instruction data */
+    instructionData: Uint8Array;
+    /** The transfer hook program ID */
+    hookProgramId: PublicKey;
+    /** Callback to fetch on-chain account data */
+    fetchAccountData: FetchAccountDataFn;
+}
+/**
+ * Parameters for resolving transfer hook extra accounts.
+ */
+interface ResolveTransferHookExtraAccountsParams {
+    /** The token mint public key */
     mint: PublicKey;
-    /** The token program ID (defaults to Token-2022) */
-    programId?: PublicKey;
+    /** The transfer hook program ID */
+    hookProgramId: PublicKey;
+    /** Source associated token account */
+    sourceAta: PublicKey;
+    /** Destination associated token account */
+    destinationAta: PublicKey;
+    /** Transfer authority (source account owner) */
+    authority: PublicKey;
+    /** Transfer amount in smallest units */
+    amount: bigint;
+    /** Token decimals (unused in resolution, kept for API consistency) */
+    decimals: number;
+    /** Callback to fetch on-chain account data */
+    fetchAccountData: FetchAccountDataFn;
 }
 /**
- * Gets the Associated Token Address without the bump seed.
+ * Resolves a single ExtraAccountMeta into a concrete AccountMeta.
  *
- * Convenience function when you only need the address.
+ * Handles all discriminator types:
+ * - 0: Static address
+ * - 1: Hook program PDA
+ * - 2: Pubkey from on-chain account data
+ * - 128+: External PDA (program ID from a previously-resolved account)
  *
- * @param options - Options containing wallet, mint, and optional programId
- * @returns The derived ATA address
+ * @param params - Resolution parameters for a single meta
+ * @returns The resolved AccountMeta
  */
-declare function getAssociatedTokenAddressSync({ wallet, mint, programId, }: GetAssociatedTokenAddressSyncOptions): PublicKey;
+declare function resolveExtraAccountMeta(params: ResolveExtraAccountMetaParams): Promise<AccountMeta>;
+/**
+ * Resolves all extra accounts required for a transfer hook instruction.
+ *
+ * This is the top-level entry point that:
+ * 1. Derives the validation PDA
+ * 2. Fetches the validation account data
+ * 3. Parses the ExtraAccountMetaList TLV
+ * 4. Builds Execute instruction data
+ * 5. Resolves each ExtraAccountMeta sequentially (incremental build)
+ * 6. De-escalates all resolved extras (isSigner = false)
+ * 7. Appends hook program ID and validation PDA as trailing accounts
+ *
+ * @param params - Resolution parameters
+ * @returns Array of extra AccountMetas to append to the transfer instruction
+ */
+declare function resolveTransferHookExtraAccounts(params: ResolveTransferHookExtraAccountsParams): Promise<AccountMeta[]>;
+
+/**
+ * Seed unpacking for Token-2022 transfer hook ExtraAccountMeta PDA resolution.
+ *
+ * The addressConfig field of a PDA-type ExtraAccountMeta contains packed seed
+ * descriptors. Each seed starts with a discriminator byte followed by type-specific
+ * parameters. Seeds are parsed sequentially until a terminator (0) is encountered
+ * or the 32-byte boundary is reached.
+ *
+ * Seed types:
+ * - 0: Terminator (stop parsing)
+ * - 1 (Literal): [length: u8, ...bytes]
+ * - 2 (InstructionData): [offset: u8, length: u8] -- slice of Execute instruction data
+ * - 3 (AccountKey): [accountIndex: u8] -- 32-byte pubkey of a resolved account
+ * - 4 (AccountData): [accountIndex: u8, dataOffset: u8, length: u8] -- slice of on-chain data
+ */
+
+/**
+ * Parameters for unpacking seeds from an ExtraAccountMeta addressConfig.
+ */
+interface UnpackSeedsParams {
+    /** The 32-byte packed seed configuration */
+    addressConfig: Uint8Array;
+    /** All previously resolved accounts (base 5 + resolved extras) */
+    previousMetas: AccountMeta[];
+    /** The Execute instruction data (16 bytes) */
+    instructionData: Uint8Array;
+    /** Callback to fetch on-chain account data */
+    fetchAccountData: (pubkey: PublicKey) => Promise<Uint8Array | null>;
+}
+/**
+ * Unpacks seed descriptors from a 32-byte addressConfig into concrete byte arrays.
+ *
+ * @param params - Seed unpacking parameters
+ * @returns Array of seed byte arrays for PDA derivation
+ */
+declare function unpackSeeds(params: UnpackSeedsParams): Promise<Uint8Array[]>;
 
-export { ASSOCIATED_TOKEN_PROGRAM_ID, type AccountMeta, AccountType, type AtaDerivationResult, ExtensionType, type Instruction, MINT_SIZE, type MetadataPointerExtension, type MintInfo, type RawExtension, SplTokenClient, SplTokenError, SplTokenErrorCode, TOKEN_2022_PROGRAM_ID, TOKEN_ACCOUNT_SIZE, TOKEN_PROGRAM_ID, type TokenAccountFilter, type TokenAccountInfo, TokenAccountState, TokenInstruction, type TokenMetadata, type TransferParams, createAssociatedTokenAccountIdempotentInstruction, createAssociatedTokenAccountInstruction, createSplTokenClient, findAssociatedTokenAddress, getAssociatedTokenAddressSync, getMintExtensions, initializeMintInstruction, mintToInstruction, parseMetadataPointerExtension, parseMintAccount, parseTokenAccount, parseTokenMetadata, transferCheckedInstruction, transferInstruction };
+export { ASSOCIATED_TOKEN_PROGRAM_ID, type AccountMeta, AccountType, type AtaDerivationResult, type CreateTokenWithMetadataOptions, type CreateTokenWithMetadataParams, type CreateTokenWithMetadataResult, EXECUTE_DISCRIMINATOR, EXTRA_ACCOUNT_META_SIZE, ExtensionType, type ExtraAccountMeta, type FetchAccountDataFn, type GetMintSizeWithExtensionsOptions, type InitializePermanentDelegateInstructionOptions, type InitializeTransferHookInstructionOptions, type Instruction, MINT_SIZE, type MetadataPointerExtension, type MintAccountData, type MintBuildOptions, type MintBuildResult, MintBuilder, type MintInfo, type MintInitialSupplyConfig, type MintMetadataConfig, type MintSendOptions, type MintSendResult, type MintTransferFeeConfig, type NonTransferableAccountExtension, type NonTransferableExtension, type ParsedExtension, type PermanentDelegateExtension, type RawExtension, type ResolveExtraAccountMetaParams, type ResolveTransferHookExtraAccountsParams, SplTokenClient, SplTokenError, SplTokenErrorCode, TLV_LENGTH_SIZE, TLV_TYPE_SIZE, TOKEN_2022_PROGRAM_ID, TOKEN_ACCOUNT_SIZE, TOKEN_PROGRAM_ID, type TokenAccountFilter, type TokenAccountInfo, TokenAccountState, TokenInstruction, type TokenMetadata, type TokenMetadataParams, type TransferFee, type TransferFeeAmountExtension, type TransferFeeConfigExtension, type TransferHookExtension, type TransferParams, type UnpackSeedsParams, buildExecuteInstructionData, createAssociatedTokenAccountIdempotentInstruction, createAssociatedTokenAccountInstruction, createSplTokenClient, createTokenWithMetadata, findAssociatedTokenAddress, getAssociatedTokenAddressSync, getExtraAccountMetaAddress, getMetadataExtensionSize, getMinRentForMint, getMinRentForMintWithMetadata, getMintExtensionStates, getMintExtensions, getMintSizeWithExtensions, getMintSizeWithMetadata, getTokenAccountExtensionStates, getTokenAccountExtensions, getTokenMetadataDataSize, initializeMetadataPointerInstruction, initializeMintInstruction, initializeNonTransferableMintInstruction, initializePermanentDelegateInstruction, initializeTokenMetadataInstruction, initializeTransferFeeConfigInstruction, initializeTransferHookInstruction, mintToInstruction, parseExtension, parseExtraAccountMetaList, parseMetadataPointerExtension, parseMetadataPointerExtensionData, parseMintAccount, parsePermanentDelegateExtension, parseTokenAccount, parseTokenMetadata, parseTokenMetadataExtensionData, parseTransferFeeConfigExtension, parseTransferHookExtension, resolveExtraAccountMeta, resolveTransferHookExtraAccounts, setTransferFeeInstruction, transferCheckedInstruction, transferCheckedWithFeeInstruction, transferInstruction, unpackSeeds, updateMetadataPointerInstruction };