@rialo/spl-token 0.3.0-alpha.0

package/dist/index.d.mts

@@ -0,0 +1,1143 @@
+import { PublicKey, RialoClient, TransactionBuilder, Signer } from '@rialo/ts-cdk';
+
+/**
+ * TransferChecked instruction for SPL Token-2022.
+ *
+ * TransferChecked is the preferred transfer instruction as it includes
+ * a decimals check to prevent user error.
+ */
+
+/**
+ * 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;
+}
+/**
+ * Options for creating a TransferChecked instruction.
+ */
+interface TransferCheckedInstructionOptions {
+    /** Source token account (must be owned by authority) */
+    source: PublicKey;
+    /** The token mint */
+    mint: PublicKey;
+    /** Destination token account */
+    destination: PublicKey;
+    /** Owner of the source account (signer) */
+    authority: PublicKey;
+    /** Amount to transfer in smallest units */
+    amount: bigint;
+    /** Expected decimals of the mint (for verification) */
+    decimals: number;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a TransferChecked instruction.
+ *
+ * TransferChecked transfers tokens from one token account to another,
+ * with a decimals check to prevent accidental transfers of the wrong amount.
+ *
+ * Instruction data format: [discriminator(1), amount(8 LE), decimals(1)]
+ *
+ * @param options - Options for the instruction
+ * @returns The TransferChecked instruction
+ *
+ * @example
+ * ```typescript
+ * const instruction = transferCheckedInstruction({
+ *   source: sourceTokenAccount,
+ *   mint: mintPubkey,
+ *   destination: destinationTokenAccount,
+ *   authority: walletPubkey,
+ *   amount: 1000000n, // 1 token with 6 decimals
+ *   decimals: 6,
+ * });
+ *
+ * const tx = TransactionBuilder.create()
+ *   .setPayer(walletPubkey)
+ *   .addInstruction(instruction)
+ *   .build();
+ * ```
+ */
+declare function transferCheckedInstruction({ source, mint, destination, authority, amount, decimals, programId, }: TransferCheckedInstructionOptions): Instruction;
+/**
+ * Options for creating a Transfer instruction.
+ */
+interface TransferInstructionOptions {
+    /** Source token account */
+    source: PublicKey;
+    /** Destination token account */
+    destination: PublicKey;
+    /** Owner of the source account (signer) */
+    authority: PublicKey;
+    /** Amount to transfer in smallest units */
+    amount: bigint;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a Transfer instruction (deprecated, prefer TransferChecked).
+ *
+ * This is the legacy transfer instruction without decimals verification.
+ * Use transferCheckedInstruction instead for safety.
+ *
+ * @param options - Options for the instruction
+ * @returns The Transfer instruction
+ */
+declare function transferInstruction({ source, destination, authority, amount, programId, }: TransferInstructionOptions): Instruction;
+
+/**
+ * Create Associated Token Account instruction for SPL Token-2022.
+ *
+ * Creates an Associated Token Account (ATA) for a wallet and mint combination.
+ */
+
+/**
+ * Options for creating an Associated Token Account instruction.
+ */
+interface CreateAssociatedTokenAccountInstructionOptions {
+    /** Account paying for the new account's rent */
+    payer: PublicKey;
+    /** The ATA address (derived via findAssociatedTokenAddress) */
+    associatedToken: PublicKey;
+    /** The wallet that will own the new token account */
+    owner: PublicKey;
+    /** The token mint */
+    mint: PublicKey;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates an instruction to create an Associated Token Account.
+ *
+ * The ATA is a PDA derived from the wallet, token program, and mint.
+ * This instruction will create the account if it doesn't exist.
+ *
+ * Note: This instruction has no data - all information is in the accounts.
+ *
+ * @param options - Options for the instruction
+ * @returns The CreateAssociatedTokenAccount instruction
+ *
+ * @example
+ * ```typescript
+ * const { address: ata } = findAssociatedTokenAddress({ wallet: walletPubkey, mint: mintPubkey });
+ *
+ * const instruction = createAssociatedTokenAccountInstruction({
+ *   payer: payerPubkey,
+ *   associatedToken: ata,
+ *   owner: walletPubkey,
+ *   mint: mintPubkey,
+ * });
+ *
+ * const tx = TransactionBuilder.create()
+ *   .setPayer(payerPubkey)
+ *   .addInstruction(instruction)
+ *   .build();
+ * ```
+ */
+declare function createAssociatedTokenAccountInstruction({ payer, associatedToken, owner, mint, programId, }: CreateAssociatedTokenAccountInstructionOptions): Instruction;
+/**
+ * Options for creating an idempotent Associated Token Account instruction.
+ */
+interface CreateAssociatedTokenAccountIdempotentInstructionOptions {
+    /** Account paying for the new account's rent */
+    payer: PublicKey;
+    /** The ATA address (derived via findAssociatedTokenAddress) */
+    associatedToken: PublicKey;
+    /** The wallet that will own the new token account */
+    owner: PublicKey;
+    /** The token mint */
+    mint: PublicKey;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates an instruction to create an Associated Token Account idempotently.
+ *
+ * This variant will succeed even if the ATA already exists, making it safe
+ * to call without checking if the account exists first.
+ *
+ * @param options - Options for the instruction
+ * @returns The CreateAssociatedTokenAccountIdempotent instruction
+ *
+ * @example
+ * ```typescript
+ * // Safe to call even if ATA already exists
+ * const instruction = createAssociatedTokenAccountIdempotentInstruction({
+ *   payer: payerPubkey,
+ *   associatedToken: ata,
+ *   owner: walletPubkey,
+ *   mint: mintPubkey,
+ * });
+ * ```
+ */
+declare function createAssociatedTokenAccountIdempotentInstruction({ payer, associatedToken, owner, mint, programId, }: CreateAssociatedTokenAccountIdempotentInstructionOptions): Instruction;
+
+/**
+ * Options for creating an InitializeMint2 instruction.
+ *
+ * InitializeMint2 does not require a rent sysvar account, but does require
+ * the tombstone PDA derived from ["mint_tombstone", mint_pubkey].
+ */
+interface InitializeMintInstructionOptions {
+    /** Mint account to initialize */
+    mint: PublicKey;
+    /** Number of decimals for the mint */
+    decimals: number;
+    /** Authority allowed to mint new tokens */
+    mintAuthority: PublicKey;
+    /** Optional freeze authority for the mint */
+    freezeAuthority?: PublicKey;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates an InitializeMint2 instruction for Token-2022.
+ *
+ * Instruction data format:
+ * [discriminator(1), decimals(1), mint_authority(32), freeze_option(1), freeze_authority(32)]
+ *
+ * Accounts:
+ * - mint (writable)
+ * - tombstone_pda (readonly)
+ *
+ * @param options - Options for the instruction
+ * @returns The InitializeMint2 instruction
+ *
+ * @example
+ * ```typescript
+ * const instruction = initializeMintInstruction({
+ *   mint,
+ *   decimals: 6,
+ *   mintAuthority,
+ *   freezeAuthority,
+ * });
+ * ```
+ */
+declare function initializeMintInstruction({ mint, decimals, mintAuthority, freezeAuthority, programId, }: InitializeMintInstructionOptions): Instruction;
+/**
+ * Options for creating a MintTo instruction.
+ */
+interface MintToInstructionOptions {
+    /** Mint account to mint tokens from */
+    mint: PublicKey;
+    /** Destination token account to receive minted tokens */
+    destination: PublicKey;
+    /** Mint authority (signer) */
+    authority: PublicKey;
+    /** Amount to mint in smallest units */
+    amount: bigint;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a MintTo instruction for Token-2022.
+ *
+ * Instruction data format: [discriminator(1), amount(8 LE)]
+ *
+ * Accounts:
+ * - mint (writable)
+ * - destination (writable)
+ * - authority (signer)
+ *
+ * @param options - Options for the instruction
+ * @returns The MintTo instruction
+ *
+ * @example
+ * ```typescript
+ * const instruction = mintToInstruction({
+ *   mint,
+ *   destination,
+ *   authority,
+ *   amount: 1_000_000n,
+ * });
+ * ```
+ */
+declare function mintToInstruction({ mint, destination, authority, amount, programId, }: MintToInstructionOptions): Instruction;
+
+/**
+ * Constants for SPL Token-2022 operations.
+ *
+ * This module defines program IDs, byte offsets for account parsing,
+ * and instruction discriminators for the Token-2022 program.
+ */
+/** Token-2022 program ID */
+declare const TOKEN_2022_PROGRAM_ID = "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb";
+/** Associated Token Account program ID */
+declare const ASSOCIATED_TOKEN_PROGRAM_ID = "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL";
+/** Legacy Token program ID (SPL Token) */
+declare const TOKEN_PROGRAM_ID = "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA";
+/** Size of a Mint account (without extensions) */
+declare const MINT_SIZE = 82;
+/** Size of a Token Account (without extensions) */
+declare const TOKEN_ACCOUNT_SIZE = 165;
+/**
+ * State of a token account.
+ */
+declare enum TokenAccountState {
+    /** Account is not yet initialized */
+    Uninitialized = 0,
+    /** Account is initialized and active */
+    Initialized = 1,
+    /** Account is frozen */
+    Frozen = 2
+}
+/**
+ * Extension types for Token-2022 accounts.
+ * Extensions start after the base account data with an AccountType byte.
+ */
+declare enum ExtensionType {
+    /** Uninitialized extension slot */
+    Uninitialized = 0,
+    /** Transfer fee configuration */
+    TransferFeeConfig = 1,
+    /** Transfer fee amount tracking */
+    TransferFeeAmount = 2,
+    /** Mint close authority */
+    MintCloseAuthority = 3,
+    /** Confidential transfer configuration */
+    ConfidentialTransferMint = 4,
+    /** Confidential transfer account state */
+    ConfidentialTransferAccount = 5,
+    /** Default account state */
+    DefaultAccountState = 6,
+    /** Immutable owner */
+    ImmutableOwner = 7,
+    /** Memo required on transfer */
+    MemoTransfer = 8,
+    /** Non-transferable tokens */
+    NonTransferable = 9,
+    /** Interest-bearing configuration */
+    InterestBearingConfig = 10,
+    /** CPI guard */
+    CpiGuard = 11,
+    /** Permanent delegate */
+    PermanentDelegate = 12,
+    /** Non-transferable account marker */
+    NonTransferableAccount = 13,
+    /** Transfer hook configuration */
+    TransferHook = 14,
+    /** Transfer hook account state */
+    TransferHookAccount = 15,
+    /** Confidential transfer fee configuration */
+    ConfidentialTransferFeeConfig = 16,
+    /** Confidential transfer fee amount */
+    ConfidentialTransferFeeAmount = 17,
+    /** Metadata pointer extension */
+    MetadataPointer = 18,
+    /** Token metadata extension */
+    TokenMetadata = 19,
+    /** Group pointer extension */
+    GroupPointer = 20,
+    /** Token group extension */
+    TokenGroup = 21,
+    /** Group member pointer extension */
+    GroupMemberPointer = 22,
+    /** Token group member extension */
+    TokenGroupMember = 23
+}
+/**
+ * Account type byte that precedes extensions.
+ */
+declare enum AccountType {
+    /** Account is uninitialized */
+    Uninitialized = 0,
+    /** This is a mint account */
+    Mint = 1,
+    /** This is a token account */
+    Account = 2
+}
+/**
+ * SPL Token instruction discriminators.
+ */
+declare enum TokenInstruction {
+    /** Initialize a new mint */
+    InitializeMint = 0,
+    /** Initialize a new token account */
+    InitializeAccount = 1,
+    /** Initialize a multisig */
+    InitializeMultisig = 2,
+    /** Transfer tokens (deprecated, use TransferChecked) */
+    Transfer = 3,
+    /** Approve a delegate */
+    Approve = 4,
+    /** Revoke a delegate */
+    Revoke = 5,
+    /** Set a new authority */
+    SetAuthority = 6,
+    /** Mint new tokens */
+    MintTo = 7,
+    /** Burn tokens */
+    Burn = 8,
+    /** Close a token account */
+    CloseAccount = 9,
+    /** Freeze a token account */
+    FreezeAccount = 10,
+    /** Thaw a frozen account */
+    ThawAccount = 11,
+    /** Transfer tokens with decimals check */
+    TransferChecked = 12,
+    /** Approve with amount check */
+    ApproveChecked = 13,
+    /** Mint with amount check */
+    MintToChecked = 14,
+    /** Burn with amount check */
+    BurnChecked = 15,
+    /** Initialize account with specified owner */
+    InitializeAccount2 = 16,
+    /** Sync native token balance */
+    SyncNative = 17,
+    /** Initialize account with rent sysvar */
+    InitializeAccount3 = 18,
+    /** Initialize multisig with rent sysvar */
+    InitializeMultisig2 = 19,
+    /** Initialize mint with rent sysvar */
+    InitializeMint2 = 20
+}
+
+/**
+ * TypeScript interfaces for SPL Token-2022 accounts and operations.
+ */
+
+/**
+ * Parsed mint account information.
+ *
+ * Contains the core mint data including supply, decimals, and authorities.
+ */
+interface MintInfo {
+    /** The mint's public key address */
+    address: PublicKey;
+    /** Total token supply in smallest units */
+    supply: bigint;
+    /** Number of decimal places for display (0-9) */
+    decimals: number;
+    /** Whether the mint has been initialized */
+    isInitialized: boolean;
+    /** Authority that can mint new tokens (null if disabled) */
+    mintAuthority: PublicKey | null;
+    /** Authority that can freeze token accounts (null if disabled) */
+    freezeAuthority: PublicKey | null;
+}
+/**
+ * Parsed token account information.
+ *
+ * Represents a token holding account with balance, owner, and delegation info.
+ */
+interface TokenAccountInfo {
+    /** The token account's public key address */
+    address: PublicKey;
+    /** The mint this account holds tokens for */
+    mint: PublicKey;
+    /** The wallet that owns this token account */
+    owner: PublicKey;
+    /** Current token balance in smallest units */
+    amount: bigint;
+    /** Delegate authorized to transfer tokens (null if none) */
+    delegate: PublicKey | null;
+    /** Account state (Uninitialized, Initialized, or Frozen) */
+    state: TokenAccountState;
+    /** If this is a wrapped native token account, the amount of native tokens */
+    isNative: bigint | null;
+    /** Amount delegated to the delegate */
+    delegatedAmount: bigint;
+    /** Authority that can close this account (null if none) */
+    closeAuthority: PublicKey | null;
+}
+/**
+ * Token metadata from the Token-2022 metadata extension.
+ *
+ * This is the native metadata format embedded in Token-2022 accounts,
+ * not the separate Metaplex Token Metadata program.
+ */
+interface TokenMetadata {
+    /** Authority that can update the metadata */
+    updateAuthority: PublicKey | null;
+    /** The mint this metadata belongs to */
+    mint: PublicKey;
+    /** Token name (e.g., "Wrapped SOL") */
+    name: string;
+    /** Token symbol (e.g., "SOL") */
+    symbol: string;
+    /** URI pointing to off-chain metadata (JSON) */
+    uri: string;
+    /** Additional key-value metadata pairs */
+    additionalMetadata: Array<[string, string]>;
+}
+/**
+ * Parameters for a token transfer operation.
+ */
+interface TransferParams {
+    /** Source wallet (owner of the source token account) */
+    source: PublicKey;
+    /** Destination wallet (will use/create their ATA) */
+    destination: PublicKey;
+    /** Mint of the token being transferred */
+    mint: PublicKey;
+    /** Amount to transfer in smallest units */
+    amount: bigint;
+    /** Token decimals (must match mint) */
+    decimals: number;
+    /** Whether to create destination ATA if it doesn't exist */
+    createDestinationAta?: boolean;
+}
+/**
+ * Result of deriving an Associated Token Address.
+ */
+interface AtaDerivationResult {
+    /** The derived ATA address */
+    address: PublicKey;
+    /** The bump seed used in derivation */
+    bump: number;
+}
+/**
+ * Filter options for listing token accounts.
+ */
+interface TokenAccountFilter {
+    /** Filter by specific mint */
+    mint?: PublicKey;
+    /** Filter by token program (Token or Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Raw TLV extension data.
+ */
+interface RawExtension {
+    /** Extension type identifier */
+    type: number;
+    /** Raw extension data bytes */
+    data: Uint8Array;
+}
+/**
+ * Metadata pointer extension data.
+ */
+interface MetadataPointerExtension {
+    /** Authority that can set the metadata address */
+    authority: PublicKey | null;
+    /** Address where metadata is stored (usually same as mint for embedded) */
+    metadataAddress: PublicKey | null;
+}
+
+/**
+ * High-level SPL Token-2022 client for token operations.
+ *
+ * Provides a convenient API for common token operations like getting
+ * balances, reading mint info, and building transfer transactions.
+ */
+
+/**
+ * Options for creating an SplTokenClient.
+ */
+interface SplTokenClientOptions {
+    /** The underlying RialoClient for RPC calls */
+    client: RialoClient;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * High-level client for SPL Token-2022 operations.
+ *
+ * Wraps a RialoClient to provide token-specific functionality including
+ * reading mint/token account data, getting balances, and building transfers.
+ *
+ * @example
+ * ```typescript
+ * import { createRialoClient, RIALO_DEVNET_CHAIN } from '@rialo/ts-cdk';
+ * import { createSplTokenClient } from '@rialo/spl-token';
+ *
+ * const rialoClient = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
+ * const tokenClient = createSplTokenClient({ client: rialoClient });
+ *
+ * // Get token balance
+ * const balance = await tokenClient.getBalance({ wallet: walletPubkey, mint: mintPubkey });
+ * console.log(`Balance: ${balance}`);
+ *
+ * // Get mint info
+ * const mintInfo = await tokenClient.getMintInfo({ mint: mintPubkey });
+ * console.log(`Supply: ${mintInfo.supply}, Decimals: ${mintInfo.decimals}`);
+ * ```
+ */
+declare class SplTokenClient {
+    private readonly client;
+    private readonly programId;
+    /**
+     * Creates a new SplTokenClient.
+     *
+     * @param options - Client configuration options
+     */
+    constructor({ client, programId, }: SplTokenClientOptions);
+    /**
+     * Gets the token program ID this client is configured to use.
+     */
+    getProgramId(): PublicKey;
+    /**
+     * Retrieves mint account information.
+     *
+     * @param options - Options containing the mint public key
+     * @returns Parsed mint information including supply, decimals, and authorities
+     * @throws {SplTokenError} If the mint account doesn't exist or is invalid
+     *
+     * @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'}`);
+     * ```
+     */
+    getMintInfo({ mint }: {
+        mint: PublicKey;
+    }): Promise<MintInfo>;
+    /**
+     * Retrieves Token-2022 native metadata from a mint.
+     *
+     * @param options - Options containing the mint public key
+     * @returns Parsed token metadata, or null if no metadata extension exists
+     * @throws {SplTokenError} If the mint account doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const metadata = await tokenClient.getTokenMetadata({ mint: mintPubkey });
+     * if (metadata) {
+     *   console.log(`Name: ${metadata.name}`);
+     *   console.log(`Symbol: ${metadata.symbol}`);
+     *   console.log(`URI: ${metadata.uri}`);
+     * }
+     * ```
+     */
+    getTokenMetadata({ mint }: {
+        mint: PublicKey;
+    }): Promise<TokenMetadata | null>;
+    /**
+     * Retrieves token account information.
+     *
+     * @param options - Options containing the token account public key
+     * @returns Parsed token account information
+     * @throws {SplTokenError} If the account doesn't exist or is invalid
+     */
+    getTokenAccountInfo({ tokenAccount, }: {
+        tokenAccount: PublicKey;
+    }): Promise<TokenAccountInfo>;
+    /**
+     * Gets the token balance for a wallet.
+     *
+     * Automatically derives the Associated Token Address for the wallet/mint
+     * combination and retrieves the balance.
+     *
+     * @param options - Options containing wallet and mint public keys
+     * @returns The token balance in smallest units, or 0n if the ATA doesn't exist
+     *
+     * @example
+     * ```typescript
+     * const balance = await tokenClient.getBalance({ wallet: walletPubkey, mint: mintPubkey });
+     * console.log(`Token balance: ${balance}`);
+     * ```
+     */
+    getBalance({ wallet, mint }: {
+        wallet: PublicKey;
+        mint: PublicKey;
+    }): Promise<bigint>;
+    /**
+     * Derives the Associated Token Address for a wallet and mint.
+     *
+     * @param options - Options containing wallet and mint public keys
+     * @returns The derived ATA address and bump seed
+     *
+     * @example
+     * ```typescript
+     * const { address, bump } = tokenClient.getAssociatedTokenAddress({ wallet: walletPubkey, mint: mintPubkey });
+     * console.log(`ATA: ${address.toString()}`);
+     * ```
+     */
+    getAssociatedTokenAddress({ wallet, mint, }: {
+        wallet: PublicKey;
+        mint: PublicKey;
+    }): AtaDerivationResult;
+    /**
+     * Checks if an Associated Token Account exists.
+     *
+     * @param options - Options containing wallet and mint public keys
+     * @returns True if the ATA exists, false otherwise
+     */
+    ataExists({ wallet, mint }: {
+        wallet: PublicKey;
+        mint: PublicKey;
+    }): Promise<boolean>;
+    /**
+     * Creates instructions for a token transfer.
+     *
+     * This 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
+     * const instructions = await tokenClient.createTransferInstructions({
+     *   source: senderWallet,
+     *   destination: recipientWallet,
+     *   mint: mintPubkey,
+     *   amount: 1000000n,
+     *   decimals: 6,
+     *   createDestinationAta: true,
+     * });
+     * ```
+     */
+    createTransferInstructions(params: TransferParams): Promise<Instruction[]>;
+    /**
+     * Options for creating a transfer transaction.
+     */
+    /**
+     * Creates a transaction for a token transfer.
+     *
+     * Builds a complete transaction with all necessary instructions for
+     * transferring tokens, including ATA creation if needed.
+     *
+     * @param options - Options containing params and validFrom
+     * @returns Built transaction ready for signing
+     *
+     * @example
+     * ```typescript
+     * const blockHeight = await rialoClient.getBlockHeight();
+     * const configHashPrefix = await rialoClient.getConfigHashPrefix();
+     * const tx = await tokenClient.createTransferTransaction({
+     *   params: {
+     *     source: senderWallet,
+     *     destination: recipientWallet,
+     *     mint: mintPubkey,
+     *     amount: 1000000n,
+     *     decimals: 6,
+     *   },
+     *   validFrom: blockHeight,
+     *   configHashPrefix,
+     * });
+     *
+     * // Sign and send
+     * const signedTx = tx.sign([signer]);
+     * const signature = await rialoClient.sendTransaction(signedTx.serialize());
+     * ```
+     */
+    createTransferTransaction({ params, validFrom, configHashPrefix, }: {
+        params: TransferParams;
+        validFrom: bigint;
+        configHashPrefix: bigint;
+    }): Promise<ReturnType<typeof TransactionBuilder.prototype.build>>;
+    /**
+     * Transfers tokens from one wallet to another.
+     *
+     * This is a high-level convenience method that:
+     * 1. Creates the destination ATA if needed
+     * 2. Builds the transfer transaction
+     * 3. Signs and sends the transaction
+     * 4. Waits for confirmation
+     *
+     * @param options - Options containing params, validFrom, and signer
+     * @returns Transaction signature
+     *
+     * @example
+     * ```typescript
+     * const blockHeight = await rialoClient.getBlockHeight();
+     * const configHashPrefix = await rialoClient.getConfigHashPrefix();
+     * const signature = await tokenClient.transfer({
+     *   params: {
+     *     source: senderWallet,
+     *     destination: recipientWallet,
+     *     mint: mintPubkey,
+     *     amount: 1000000n,
+     *     decimals: 6,
+     *   },
+     *   validFrom: blockHeight,
+     *   configHashPrefix,
+     *   signer: senderSigner,
+     * });
+     * console.log(`Transfer complete: ${signature}`);
+     * ```
+     */
+    transfer({ params, validFrom, configHashPrefix, signer, }: {
+        params: TransferParams;
+        validFrom: bigint;
+        configHashPrefix: bigint;
+        signer: Signer;
+    }): Promise<string>;
+}
+/**
+ * Options for creating an SplTokenClient via the factory function.
+ */
+interface CreateSplTokenClientOptions {
+    /** The underlying RialoClient for RPC calls */
+    client: RialoClient;
+    /** Token program ID (defaults to Token-2022) */
+    programId?: PublicKey;
+}
+/**
+ * Creates a new SplTokenClient.
+ *
+ * Factory function for creating an SplTokenClient instance.
+ *
+ * @param options - Options for creating the client
+ * @returns Configured SplTokenClient instance
+ *
+ * @example
+ * ```typescript
+ * import { createRialoClient, RIALO_DEVNET_CHAIN } from '@rialo/ts-cdk';
+ * import { createSplTokenClient } from '@rialo/spl-token';
+ *
+ * const rialoClient = createRialoClient({ chain: RIALO_DEVNET_CHAIN });
+ * const tokenClient = createSplTokenClient({ client: rialoClient });
+ * ```
+ */
+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.
+ */
+/**
+ * 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
+ * // Create errors using factory methods
+ * throw SplTokenError.invalidMint({ reason: "Account data too short" });
+ * throw SplTokenError.tokenAccountNotFound({ address: "5ZqB9U..." });
+ * throw SplTokenError.insufficientBalance({ required: 1000n, available: 500n });
+ *
+ * // Handle errors with type information
+ * try {
+ *   await client.getBalance({ wallet, mint });
+ * } catch (error) {
+ *   if (error instanceof SplTokenError && error.code === SplTokenErrorCode.TOKEN_ACCOUNT_NOT_FOUND) {
+ *     console.log("Token account does not exist");
+ *   }
+ * }
+ * ```
+ */
+declare class SplTokenError extends Error {
+    readonly code: SplTokenErrorCode;
+    readonly details?: Record<string, unknown>;
+    constructor({ code, message, details }: SplTokenErrorOptions);
+    /**
+     * Creates an invalid mint error.
+     *
+     * @param options - Error options containing the reason
+     */
+    static invalidMint({ reason }: {
+        reason: string;
+    }): SplTokenError;
+    /**
+     * Creates an invalid token account error.
+     *
+     * @param options - Error options containing the reason
+     */
+    static invalidTokenAccount({ reason }: {
+        reason: string;
+    }): SplTokenError;
+    /**
+     * Creates a token account not found error.
+     *
+     * @param options - Error options containing the address
+     */
+    static tokenAccountNotFound({ address }: {
+        address: string;
+    }): SplTokenError;
+    /**
+     * Creates a mint not found error.
+     *
+     * @param options - Error options containing the address
+     */
+    static mintNotFound({ address }: {
+        address: string;
+    }): SplTokenError;
+    /**
+     * Creates an account frozen error.
+     *
+     * @param options - Error options containing the address
+     */
+    static accountFrozen({ address }: {
+        address: string;
+    }): SplTokenError;
+    /**
+     * Creates an insufficient balance error.
+     *
+     * @param options - Error options containing required and available amounts
+     */
+    static insufficientBalance({ required, available, }: {
+        required: bigint;
+        available: bigint;
+    }): SplTokenError;
+    /**
+     * Creates an invalid extension error.
+     *
+     * @param options - Error options containing the reason
+     */
+    static invalidExtension({ reason }: {
+        reason: string;
+    }): SplTokenError;
+    /**
+     * Creates a PDA derivation failed error.
+     *
+     * @param options - Error options containing the reason
+     */
+    static pdaDerivationFailed({ reason }: {
+        reason: string;
+    }): SplTokenError;
+    /**
+     * Creates an invalid metadata error.
+     *
+     * @param options - Error options containing the reason
+     */
+    static invalidMetadata({ reason }: {
+        reason: string;
+    }): SplTokenError;
+    /**
+     * Creates an account not initialized error.
+     *
+     * @param options - Error options containing the address
+     */
+    static accountNotInitialized({ address }: {
+        address: string;
+    }): SplTokenError;
+}
+
+/**
+ * Mint account parsing for SPL Token-2022.
+ */
+
+/**
+ * Options for parsing a mint account.
+ */
+interface ParseMintAccountOptions {
+    /** The mint account's public key */
+    address: PublicKey;
+    /** Raw account data bytes (minimum 82 bytes) */
+    data: Uint8Array;
+}
+/**
+ * Parses raw mint account data into a structured MintInfo object.
+ *
+ * @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 parseMintAccount({ address, data }: ParseMintAccountOptions): MintInfo;
+
+/**
+ * Token account parsing for SPL Token-2022.
+ */
+
+/**
+ * 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;
+}
+/**
+ * Parses raw token account data into a structured TokenAccountInfo object.
+ *
+ * @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 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 parseTokenAccount({ address, data }: ParseTokenAccountOptions): TokenAccountInfo;
+
+/**
+ * Token metadata parsing for SPL Token-2022 native metadata extension.
+ *
+ * This parses the TokenMetadata extension (ExtensionType=19) embedded in
+ * Token-2022 mint accounts, not the separate Metaplex Token Metadata program.
+ */
+
+/**
+ * Options for parsing token metadata.
+ */
+interface ParseTokenMetadataOptions {
+    /** The mint's public key */
+    mint: PublicKey;
+    /** Raw mint account data (including extensions) */
+    data: Uint8Array;
+}
+/**
+ * Parses Token-2022 native metadata from a mint account.
+ *
+ * This function looks for the TokenMetadata extension (type 19) in the
+ * account's extension data and parses it if found.
+ *
+ * @param options - Options containing mint and data
+ * @returns Parsed token metadata, or null if no metadata extension exists
+ * @throws {SplTokenError} If the metadata extension is malformed
+ *
+ * @example
+ * ```typescript
+ * const accountInfo = await client.getAccountInfo(mintPubkey);
+ * if (accountInfo) {
+ *   const metadata = parseTokenMetadata({ mint: mintPubkey, data: accountInfo.data });
+ *   if (metadata) {
+ *     console.log(`Name: ${metadata.name}`);
+ *     console.log(`Symbol: ${metadata.symbol}`);
+ *     console.log(`URI: ${metadata.uri}`);
+ *   }
+ * }
+ * ```
+ */
+declare function parseTokenMetadata({ mint, data, }: ParseTokenMetadataOptions): TokenMetadata | null;
+/**
+ * Options for parsing metadata pointer extension.
+ */
+interface ParseMetadataPointerExtensionOptions {
+    /** Raw mint account data (including extensions) */
+    data: Uint8Array;
+}
+/**
+ * Parses the MetadataPointer extension from a mint account.
+ *
+ * @param options - Options containing data
+ * @returns Parsed metadata pointer, or null if not present
+ */
+declare function parseMetadataPointerExtension({ data, }: ParseMetadataPointerExtensionOptions): MetadataPointerExtension | null;
+/**
+ * Options for getting mint extensions.
+ */
+interface GetMintExtensionsOptions {
+    /** Raw mint account data */
+    data: Uint8Array;
+}
+/**
+ * Gets all raw extensions from a mint account.
+ *
+ * @param options - Options containing data
+ * @returns Array of raw extensions, or empty array if no extensions
+ */
+declare function getMintExtensions({ data }: GetMintExtensionsOptions): RawExtension[];
+
+/**
+ * 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;
+
+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 };