@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/instructions.d.ts

@@ -0,0 +1,1125 @@
+/**
+ * UTXOPIA Instruction Builders (JoinSplit Architecture)
+ *
+ * Low-level instruction building for UTXOPIA operations.
+ * All Groth16 proofs are verified inline using BN254 pairing syscalls.
+ *
+ * @module instructions
+ */
+import { AccountRole, type Address } from "@solana/kit";
+import { type AuditorCiphertextInput } from "./auditor-ciphertext";
+/** Instruction type for v2 */
+export interface Instruction {
+    programAddress: Address;
+    accounts: Array<{
+        address: Address;
+        role: (typeof AccountRole)[keyof typeof AccountRole];
+    }>;
+    data: Uint8Array;
+}
+/** Export instruction discriminators for consumers */
+export declare const INSTRUCTION_DISCRIMINATORS: {
+    readonly INITIALIZE: 0;
+    readonly SET_PAUSED: 1;
+    readonly SET_POOL_CONFIG: 2;
+    readonly PROPOSE_POOL_UPDATE: 3;
+    readonly EXECUTE_POOL_UPDATE: 4;
+    readonly CANCEL_POOL_UPDATE: 5;
+    readonly INIT_VK_REGISTRY: 6;
+    readonly UPDATE_VK_REGISTRY: 7;
+    readonly REGISTER_TOKEN: 8;
+    readonly UPDATE_TOKEN_CONFIG: 9;
+    readonly CLAIM_FEES: 10;
+    readonly COMPLETE_DEPOSIT: 11;
+    readonly SHIELD: 12;
+    readonly TRANSACT: 13;
+    readonly UNSHIELD: 14;
+    readonly REDEEM: 15;
+    readonly RESERVED_REQUEST_REDEMPTION: 16;
+    readonly COMPLETE_REDEMPTION: 17;
+    readonly MARK_PROCESSING: 18;
+    readonly CANCEL_REDEMPTION: 19;
+    readonly ROTATE_TREE: 20;
+    readonly APPROVE_REDEMPTION_SIGNING: 27;
+    readonly SET_AUDITOR_FROZEN: 28;
+    readonly SET_AUDITOR_VIEWING_PUBKEY: 29;
+    readonly MAGICBLOCK_DELEGATE: 32;
+    readonly MAGICBLOCK_COMMIT: 33;
+    readonly MAGICBLOCK_PER_PERMISSION: 34;
+    readonly ROTATE_AUDITOR: 35;
+    readonly INITIALIZE_POLICY_APPROVAL: 36;
+    readonly POLICY_APPROVAL_DECISION: 37;
+    readonly POLICY_APPROVAL_COMMIT: 38;
+};
+/** Shield instruction options */
+export interface ShieldInstructionOptions {
+    /** Amount to shield (in token's smallest unit — lamports, micro-USDC, sats) */
+    amount: bigint;
+    /** NPK bytes (32) — recipient's note public key */
+    npk: Uint8Array;
+    /** Ephemeral public key (32) — for stealth address derivation */
+    ephemeralPub: Uint8Array;
+    /** Accounts required for the shield instruction */
+    accounts: {
+        user: Address;
+        userTokenAccount: Address;
+        poolState: Address;
+        tokenConfig: Address;
+        vault: Address;
+        commitmentTree: Address;
+        tokenProgram: Address;
+    };
+}
+/**
+ * Build shield instruction data (disc=12).
+ *
+ * Layout (after disc stripped by entrypoint):
+ * - amount: u64 LE (8 bytes)
+ * - npk: [u8; 32]
+ * - ephemeral_pub: [u8; 32]
+ */
+export declare function buildShieldInstructionData(options: {
+    amount: bigint;
+    npk: Uint8Array;
+    ephemeralPub: Uint8Array;
+}): Uint8Array;
+/**
+ * Build a complete shield instruction (disc=12).
+ *
+ * Shields SPL tokens into the privacy pool. Works with both
+ * legacy Token program (wSOL) and Token-2022 (USDC, USDT, etc.).
+ */
+export declare function buildShieldInstruction(options: ShieldInstructionOptions): Instruction;
+/** Complete redemption instruction options */
+export interface CompleteRedemptionInstructionOptions {
+    /** BTC transaction ID (internal byte order, 32 bytes) */
+    btcTxid: Uint8Array;
+    /** Raw tx size in ChadBuffer */
+    txSize: number;
+    /** Pool scriptPubKey for change UTXO tracking (empty = no tracking) */
+    poolScript: Uint8Array;
+    /** Number of consumed UTXO PDAs in remaining accounts */
+    consumedUtxoCount: number;
+    /** Account addresses */
+    accounts: {
+        poolState: Address;
+        redemptionRequest: Address;
+        authority: Address;
+        rentRecipient: Address;
+        verifiedTransaction: Address;
+        lightClient: Address;
+        txBuffer: Address;
+        zkbtcMint: Address;
+        poolVault: Address;
+        completionReceipt: Address;
+        poolConfig: Address;
+        /** Change UTXO PDA. Required when poolScript is non-empty. */
+        changeUtxo?: Address;
+        /** zkBTC TokenConfig PDA (credits protocol revenue) */
+        tokenConfig: Address;
+        /** Token program for zkBTC mint (TOKEN_2022_PROGRAM_ID or TOKEN_PROGRAM_ID). Defaults to Token-2022. */
+        tokenProgram?: Address;
+        /** Consumed UTXO PDAs to close */
+        consumedUtxos?: Address[];
+    };
+}
+export interface ApproveRedemptionSigningInstructionOptions {
+    /** BIP-341 taproot key-spend sighash for the unsigned BTC transaction. */
+    btcSighash: Uint8Array;
+    /** Optional keccak256(Sign.message), where Sign.message is the TapSighash preimage. */
+    ikaMessageDigest?: Uint8Array;
+    /** Miner fee in satoshis, checked by the on-chain signing policy. */
+    minerFeeSats: bigint | number;
+    accounts: {
+        poolState: Address;
+        redemptionRequest: Address;
+        authority: Address;
+        poolConfig: Address;
+        ikaProgram: Address;
+        ikaCoordinator: Address;
+        ikaMessageApproval: Address;
+        ikaDwallet: Address;
+        callerProgram: Address;
+        cpiAuthority: Address;
+        ikaPayer: Address;
+    };
+}
+export declare function buildApproveRedemptionSigningInstructionData(options: {
+    btcSighash: Uint8Array;
+    ikaMessageDigest?: Uint8Array;
+    minerFeeSats: bigint | number;
+}): Uint8Array;
+export declare function buildApproveRedemptionSigningInstruction(options: ApproveRedemptionSigningInstructionOptions): Instruction;
+/**
+ * Build instruction data for COMPLETE_REDEMPTION (disc 17)
+ *
+ * Layout (after disc stripped):
+ * - btc_txid: [u8; 32]
+ * - tx_size: u32 LE
+ * - pool_script_len: u8
+ * - pool_script: [u8; 0-34]
+ * - consumed_utxo_count: u8
+ */
+export declare function buildCompleteRedemptionInstructionData(options: {
+    btcTxid: Uint8Array;
+    txSize: number;
+    poolScript: Uint8Array;
+    consumedUtxoCount: number;
+}): Uint8Array;
+/**
+ * Build a complete redemption instruction
+ *
+ * Accounts (14 base + optional change + variable consumed UTXOs):
+ * 0.  pool_state (writable)
+ * 1.  redemption_request (writable)
+ * 2.  authority (signer)
+ * 3.  rent_recipient (readonly)
+ * 4.  verified_transaction (readonly)
+ * 5.  light_client (readonly)
+ * 6.  tx_buffer (readonly)
+ * 7.  zkbtc_mint (writable)
+ * 8.  pool_vault (writable)
+ * 9.  token_program (readonly)
+ * 10. completion_receipt (writable)
+ * 11. system_program (readonly)
+ * 12. pool_config (readonly)
+ * 13. change_utxo (writable, only when pool_script is non-empty)
+ * 13/14..+N consumed_utxos (writable)
+ * final. token_config (writable)
+ */
+export declare function buildCompleteRedemptionInstruction(options: CompleteRedemptionInstructionOptions): Instruction;
+/** Cancel redemption instruction options */
+export interface CancelRedemptionInstructionOptions {
+    /** Note public key for the re-minted commitment (32 bytes) */
+    npk: Uint8Array;
+    accounts: {
+        /** Original requester (signer; receives the closed request's rent) */
+        user: Address;
+        poolState: Address;
+        redemptionRequest: Address;
+        commitmentTree: Address;
+        tokenConfig: Address;
+        /**
+         * Reserved UtxoRecord PDAs to release. Required when the request was in
+         * Processing (mark_processing reserved these UTXOs); pass [] / omit for a
+         * Pending cancel, which never reserved any. The program rejects a mismatch.
+         */
+        reservedUtxos?: Address[];
+    };
+}
+/**
+ * Build cancel redemption instruction data.
+ *
+ * Layout (after disc stripped by entrypoint):
+ * - npk:        [u8; 32]
+ * - utxo_count: u8  (number of reserved UtxoRecord accounts that follow; 0 for Pending)
+ */
+export declare function buildCancelRedemptionInstructionData(options: {
+    npk: Uint8Array;
+    reservedUtxoCount: number;
+}): Uint8Array;
+/**
+ * Build a cancel redemption instruction.
+ *
+ * Accounts (6 base + variable):
+ * 0. user (writable signer)
+ * 1. pool_state (writable)
+ * 2. redemption_request (writable)
+ * 3. commitment_tree (writable)
+ * 4. system_program (readonly)
+ * 5. token_config (writable)
+ * 6..6+N reserved UtxoRecord PDAs (writable) — Processing cancels only
+ */
+export declare function buildCancelRedemptionInstruction(options: CancelRedemptionInstructionOptions): Instruction;
+/** JoinSplit transact instruction options */
+export interface TransactInstructionOptions {
+    /** Number of input notes being spent */
+    nInputs: number;
+    /** Number of output notes being created */
+    nOutputs: number;
+    /** Groth16 proof bytes (256 bytes) */
+    proofBytes: Uint8Array;
+    /** Merkle root */
+    merkleRoot: Uint8Array;
+    /** Bound parameters hash */
+    boundParamsHash: Uint8Array;
+    /** Nullifiers (32 bytes each) */
+    nullifiers: Uint8Array[];
+    /** Output commitments (32 bytes each) */
+    commitmentsOut: Uint8Array[];
+    /** Per-output stealth data: ephemeral_pub (32) + encrypted_amount (8) */
+    stealthData: Uint8Array[];
+    /** Reserved. Sender memos are rejected until they are proof-bound. */
+    senderMemos?: Uint8Array[];
+    /** Account addresses */
+    accounts: {
+        poolState: Address;
+        commitmentTree: Address;
+        vkRegistry: Address;
+        user: Address;
+        /** Nullifier record PDAs (one per input) */
+        nullifierRecords: Address[];
+        /** Required when poolState is permissioned. Appended before any proof buffer. */
+        policyApproval?: Address;
+    };
+}
+/**
+ * Build transact instruction data (JoinSplit)
+ *
+ * Layout (after disc stripped by entrypoint):
+ * - n_inputs: u8
+ * - n_outputs: u8
+ * - n_public_outputs: u8 (always 0 for transact)
+ * - proof_source: u8 (0=inline, 1=buffer account)
+ * - proof: [u8; 256] (only if proof_source=0)
+ * - merkle_root: [u8; 32]
+ * - bound_params_hash: [u8; 32]
+ * - nullifiers: [[u8; 32]; n_inputs]
+ * - commitments_out: [[u8; 32]; n_outputs]
+ * - stealth_data: [ephemeral_pub(32) + encrypted_amount(8) + encrypted_token_id(32)] x n_outputs
+ */
+export declare function buildTransactInstructionData(options: {
+    nInputs: number;
+    nOutputs: number;
+    /** Groth16 proof (256 bytes). Omit when using buffer mode. */
+    proofBytes?: Uint8Array;
+    merkleRoot: Uint8Array;
+    boundParamsHash: Uint8Array;
+    nullifiers: Uint8Array[];
+    commitmentsOut: Uint8Array[];
+    stealthData: Uint8Array[];
+    /** 0=inline proof (default), 1=proof in separate ChadBuffer account */
+    proofSource?: 0 | 1;
+    /** Reserved. Sender memos are rejected until they are proof-bound. */
+    senderMemos?: Uint8Array[];
+}): Uint8Array;
+/**
+ * Build a complete JoinSplit transact instruction
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. commitment_tree (writable)
+ * 2. vk_registry (read)
+ * 3. user (signer)
+ * 4. system_program (read)
+ * 5..5+N nullifier_records (writable)
+ */
+export declare function buildTransactInstruction(options: TransactInstructionOptions): Instruction;
+/**
+ * Build instruction data for REDEEM (disc=15) — atomic JoinSplit + BTC withdrawal (multi-output)
+ *
+ * Combines Groth16 proof verification with RedemptionRequest PDA creation.
+ * Supports 1..3 public outputs, each creating a separate RedemptionRequest.
+ *
+ * Layout (4-byte common header):
+ * - n_inputs: u8
+ * - n_outputs: u8
+ * - n_public_outputs: u8 (1..3)
+ * - proof_source: u8 (0=inline, 1=buffer account)
+ * - proof: [u8; 256] (only if proof_source=0)
+ * - merkle_root: [u8; 32]
+ * - bound_params_hash: [u8; 32]
+ * - nullifiers: [[u8; 32]; n_inputs]
+ * - commitments_out: [[u8; 32]; n_outputs]
+ * - stealth_data: [ephemeral_pub(32) + encrypted_amount(8) + encrypted_token_id(32)] x n_tree_outputs
+ * - For each public output: amount(8) + script_len(1) + script(var) + nonce(8)
+ */
+export declare function buildRedeemInstructionData(options: {
+    nInputs: number;
+    nOutputs: number;
+    /** Number of public (redeem) outputs. Defaults to redeemAmounts.length. */
+    nPublicOutputs?: number;
+    /** Groth16 proof (256 bytes). Omit when using buffer mode. */
+    proofBytes?: Uint8Array;
+    merkleRoot: Uint8Array;
+    boundParamsHash: Uint8Array;
+    nullifiers: Uint8Array[];
+    commitmentsOut: Uint8Array[];
+    /** Stealth data for tree outputs only (n_tree_outputs entries, 72 bytes each) */
+    stealthData: Uint8Array[];
+    /** Amount(s) to redeem in satoshis — single or array */
+    redeemAmounts: bigint[];
+    /** Bitcoin scriptPubKey(s) (raw bytes, max 62 each) — single or array */
+    btcScripts: Uint8Array[];
+    /** Unique request nonce(s) — single or array */
+    requestNonces: bigint[];
+    /** 0=inline proof (default), 1=proof in separate ChadBuffer account */
+    proofSource?: 0 | 1;
+}): Uint8Array;
+/** Unshield instruction options (multi-output) */
+export interface UnshieldInstructionOptions {
+    /** Number of input notes being spent */
+    nInputs: number;
+    /** Number of output notes (includes burn outputs at end) */
+    nOutputs: number;
+    /** Number of public (unshield) outputs. Defaults to 1. */
+    nPublicOutputs?: number;
+    /** Groth16 proof bytes (256 bytes) */
+    proofBytes: Uint8Array;
+    /** Merkle root */
+    merkleRoot: Uint8Array;
+    /** Bound parameters hash */
+    boundParamsHash: Uint8Array;
+    /** Nullifiers (32 bytes each) */
+    nullifiers: Uint8Array[];
+    /** Output commitments (32 bytes each, last nPublicOutputs = burn commitments) */
+    commitmentsOut: Uint8Array[];
+    /** Per-output stealth data for tree outputs only */
+    stealthData: Uint8Array[];
+    /** Amount(s) being unshielded */
+    unshieldAmounts: bigint[];
+    /** Account addresses */
+    accounts: {
+        poolState: Address;
+        commitmentTree: Address;
+        vkRegistry: Address;
+        user: Address;
+        tokenConfig: Address;
+        vault: Address;
+        /** Token program for the mint (TOKEN_2022_PROGRAM_ID or TOKEN_PROGRAM_ID). Defaults to Token-2022. */
+        tokenProgram?: Address;
+        /** Public destination accounts (SPL token accounts, or direct recipients for native SOL) */
+        recipientTokenAccounts: Address[];
+        /** Nullifier record PDAs (one per input) */
+        nullifierRecords: Address[];
+        /** Required when poolState is permissioned. Appended before any proof buffer. */
+        policyApproval?: Address;
+    };
+}
+/**
+ * Build unshield instruction data (multi-output, disc=14).
+ *
+ * Layout (4-byte common header):
+ * - disc(1) + n_inputs(1) + n_outputs(1) + n_public_outputs(1) + proof_source(1)
+ * - proof(256) if inline
+ * - merkle_root(32) + bound_params_hash(32)
+ * - nullifiers(N*32) + commitments_out(M*32)
+ * - stealth_data(n_tree_outputs * 72)
+ * - amounts[P] (each u64 LE)
+ *
+ * Recipients come from the accounts array. Ordinary SPL outputs use token
+ * accounts; native-SOL outputs use the recipient accounts directly.
+ */
+export declare function buildUnshieldInstructionData(options: {
+    nInputs: number;
+    nOutputs: number;
+    /** Number of public (unshield) outputs. Defaults to 1. */
+    nPublicOutputs?: number;
+    /** Groth16 proof (256 bytes). Omit when using buffer mode. */
+    proofBytes?: Uint8Array;
+    merkleRoot: Uint8Array;
+    boundParamsHash: Uint8Array;
+    nullifiers: Uint8Array[];
+    commitmentsOut: Uint8Array[];
+    stealthData: Uint8Array[];
+    /** Amount(s) being unshielded — single or array */
+    unshieldAmounts: bigint[];
+    /** 0=inline proof (default), 1=proof in separate ChadBuffer account */
+    proofSource?: 0 | 1;
+}): Uint8Array;
+/**
+ * Build a complete unshield instruction (multi-output, disc=14)
+ *
+ * Accounts:
+ * 0. pool_state (read)
+ * 1. commitment_tree (writable)
+ * 2. vk_registry (read)
+ * 3. user (signer)
+ * 4. system_program (read)
+ * 5. token_config (writable)
+ * 6. vault (writable)
+ * 7. token_program (read)
+ * 8..8+P public destinations (SPL token accounts or native-SOL recipients)
+ * 8+P..8+P+N nullifier_records (writable)
+ */
+export declare function buildUnshieldInstruction(options: UnshieldInstructionOptions): Instruction;
+/** Propose pool update instruction options */
+export interface ProposePoolUpdateOptions {
+    /** New minimum deposit in satoshis */
+    minDeposit: bigint;
+    /** New maximum deposit in satoshis */
+    maxDeposit: bigint;
+    /** New service fee base in satoshis */
+    serviceFee: bigint;
+    /** Service fee in basis points (e.g. 30 = 0.3%). Applied immediately, no timelock. */
+    serviceFeeBps?: number;
+    /** Account addresses */
+    accounts: {
+        poolState: Address;
+        authority: Address;
+    };
+}
+/**
+ * Build propose_pool_update instruction data
+ *
+ * Layout: discriminator(1) + min_deposit(8) + max_deposit(8) + service_fee(8) + [service_fee_bps(2)] = 25 or 27 bytes
+ */
+export declare function buildProposePoolUpdateInstructionData(minDeposit: bigint, maxDeposit: bigint, serviceFee: bigint, serviceFeeBps?: number): Uint8Array;
+/**
+ * Build a complete propose_pool_update instruction
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. authority (signer)
+ */
+export declare function buildProposePoolUpdateInstruction(options: ProposePoolUpdateOptions): Instruction;
+/** Execute pool update instruction options */
+export interface ExecutePoolUpdateOptions {
+    accounts: {
+        poolState: Address;
+        /** Pool authority — must sign (execute is authority-only; audit f11). */
+        authority: Address;
+    };
+}
+/**
+ * Build execute_pool_update instruction data
+ *
+ * Layout: discriminator(1) = 1 byte
+ */
+export declare function buildExecutePoolUpdateInstructionData(): Uint8Array;
+/**
+ * Build a complete execute_pool_update instruction (authority-only)
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. authority (signer)
+ */
+export declare function buildExecutePoolUpdateInstruction(options: ExecutePoolUpdateOptions): Instruction;
+/** Cancel pool update instruction options */
+export interface CancelPoolUpdateOptions {
+    accounts: {
+        poolState: Address;
+        authority: Address;
+    };
+}
+/**
+ * Build cancel_pool_update instruction data
+ *
+ * Layout: discriminator(1) = 1 byte
+ */
+export declare function buildCancelPoolUpdateInstructionData(): Uint8Array;
+/**
+ * Build a complete cancel_pool_update instruction
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. authority (signer)
+ */
+export declare function buildCancelPoolUpdateInstruction(options: CancelPoolUpdateOptions): Instruction;
+/** Rotate tree instruction options */
+export interface RotateTreeOptions {
+    accounts: {
+        poolState: Address;
+        currentTree: Address;
+        newTree: Address;
+        authority: Address;
+        systemProgram: Address;
+    };
+}
+/**
+ * Build rotate_tree instruction data (disc=20, no payload)
+ */
+export declare function buildRotateTreeInstructionData(): Uint8Array;
+/**
+ * Build a complete rotate_tree instruction
+ *
+ * Accounts:
+ * 0. pool_state    (writable)
+ * 1. current_tree  (writable) — must be full
+ * 2. new_tree      (writable) — to be created
+ * 3. authority     (signer)
+ * 4. system_program
+ */
+export declare function buildRotateTreeInstruction(options: RotateTreeOptions): Instruction;
+/** Only policy decisions are delegated; asset-bearing pool/tree state stays on Solana. */
+export type MagicBlockDelegateTarget = "policyApproval";
+export interface MagicBlockDelegateInstructionOptions {
+    accounts: {
+        payer: Address;
+        authority: Address;
+        poolState: Address;
+        delegatedAccount: Address;
+        ownerProgram?: Address;
+        buffer: Address;
+        delegationRecord: Address;
+        delegationMetadata: Address;
+        systemProgram?: Address;
+    };
+    target: MagicBlockDelegateTarget;
+    commitFrequencyMs: number;
+    validator?: Address;
+}
+export interface MagicBlockCommitInstructionOptions {
+    accounts: {
+        payer: Address;
+        /** Required for undelegation. Commit-only callers may omit it. */
+        authority?: Address;
+        magicContext?: Address;
+        magicProgram?: Address;
+        poolState: Address;
+        commitmentTree: Address;
+        nullifierAccounts: Address[];
+    };
+    nullifierHashes: Uint8Array[];
+    allowUndelegation?: boolean;
+}
+export type MagicBlockPerPermissionOperation = "create" | "update" | "close";
+export interface MagicBlockPerPermissionMember {
+    address: Address;
+    flags: number;
+}
+export interface MagicBlockPerPermissionInstructionOptions {
+    operation: MagicBlockPerPermissionOperation;
+    target: MagicBlockDelegateTarget;
+    members?: MagicBlockPerPermissionMember[];
+    accounts: {
+        authority: Address;
+        poolState: Address;
+        permissionedAccount: Address;
+        permission: Address;
+        ephemeralVault?: Address;
+        magicProgram?: Address;
+        permissionProgram?: Address;
+    };
+}
+/**
+ * Build magicblock_delegate instruction data (disc=32).
+ */
+export declare function buildMagicBlockDelegateInstructionData(options: {
+    target: MagicBlockDelegateTarget;
+    commitFrequencyMs: number;
+    validator?: Address;
+}): Uint8Array;
+/**
+ * Build a complete magicblock_delegate instruction.
+ */
+export declare function buildMagicBlockDelegateInstruction(options: MagicBlockDelegateInstructionOptions): Instruction;
+/**
+ * Build magicblock_commit instruction data (disc=33).
+ */
+export declare function buildMagicBlockCommitInstructionData(options: {
+    nullifierHashes: Uint8Array[];
+    allowUndelegation?: boolean;
+}): Uint8Array;
+/**
+ * Build a complete magicblock_commit instruction.
+ */
+export declare function buildMagicBlockCommitInstruction(options: MagicBlockCommitInstructionOptions): Instruction;
+export declare function buildMagicBlockPerPermissionInstructionData(options: {
+    operation: MagicBlockPerPermissionOperation;
+    target: MagicBlockDelegateTarget;
+    members?: MagicBlockPerPermissionMember[];
+}): Uint8Array;
+export declare function buildMagicBlockPerPermissionInstruction(options: MagicBlockPerPermissionInstructionOptions): Instruction;
+export type PolicyApprovalDecision = "approve" | "reject";
+/** Must match `MAX_INTENT_PARTS` in the asset program. */
+export declare const MAX_POLICY_INTENT_PARTS = 3;
+/**
+ * Build the intent parts a spend's policy approval commits to.
+ *
+ * The layout mirrors what the asset program hashes, and deliberately carries no
+ * proof machinery: the merkle root, output commitments and stealth data all move
+ * when a spend is re-proved, and a spend has to be re-proved whenever the root
+ * advances — which is exactly while the authority is deciding. Binding them
+ * would make every approval expire the moment someone else deposits.
+ *
+ * Amounts and BTC scripts are encoded exactly as the instruction encodes them,
+ * because the program hashes the same trailing bytes it parses.
+ */
+export declare function buildPolicyIntentParts(options: {
+    action: 13;
+    nullifiers: Uint8Array[];
+} | {
+    action: 14;
+    nullifiers: Uint8Array[];
+    unshieldAmounts: bigint[];
+    /** OWNER of each recipient token account — what the payout credits. */
+    recipientOwners: Uint8Array[];
+} | {
+    action: 15;
+    nullifiers: Uint8Array[];
+    redeemAmounts: bigint[];
+    btcScripts: Uint8Array[];
+    requestNonces: bigint[];
+}): Uint8Array[];
+/**
+ * Mirror of `compute_policy_request_hash` in the asset program.
+ *
+ * The approval commits to what the authority decides — which notes are spent,
+ * how much leaves, and where it goes — never to the whole instruction. Binding
+ * the payload would tie an approval to one exact proof, and a spend has to be
+ * re-proved whenever the merkle root moves on, which is precisely while the
+ * authority is deciding.
+ *
+ * Parts, in the order the program hashes them:
+ * - `transact`: [nullifiers]
+ * - `unshield`: [nullifiers, amounts, recipientOwners]
+ * - `redeem`:   [nullifiers, amountsScriptsAndNonces]
+ * - value entry (`shield` / `completeDeposit`): [instructionDataWithoutDiscriminator]
+ *
+ * Each part is folded to a fixed 32 bytes before the parts are joined, so their
+ * boundaries cannot be slid. Any drift from the on-chain version makes every
+ * Verified spend fail with PolicyApprovalMismatch.
+ */
+export declare function buildPolicyRequestHash(options: {
+    programId: Address;
+    poolState: Address;
+    actor: Address;
+    /** Discriminator of the asset instruction this approval covers. */
+    action: number;
+    intentParts: Uint8Array[];
+}): Uint8Array;
+export interface InitializePolicyApprovalOptions {
+    action: number;
+    expiresAtSlot: bigint;
+    actor: Address;
+    requestHash: Uint8Array;
+    nonce: Uint8Array;
+    accounts: {
+        payer: Address;
+        poolState: Address;
+        policyApproval: Address;
+        systemProgram?: Address;
+    };
+}
+export declare function buildInitializePolicyApprovalInstructionData(options: Omit<InitializePolicyApprovalOptions, "accounts">): Uint8Array;
+export declare function buildInitializePolicyApprovalInstruction(options: InitializePolicyApprovalOptions): Instruction;
+export declare function buildPolicyApprovalDecisionInstruction(options: {
+    decision: PolicyApprovalDecision;
+    accounts: {
+        policyAuthority: Address;
+        policyApproval: Address;
+    };
+}): Instruction;
+export declare function buildPolicyApprovalCommitInstruction(options: {
+    accounts: {
+        payer: Address;
+        policyApproval: Address;
+        magicContext?: Address;
+        magicProgram?: Address;
+    };
+}): Instruction;
+/**
+ * Build btc-light-client verify_transaction instruction data (disc=2)
+ *
+ * Layout (after disc byte):
+ * txid(32) + block_hash(32) + tx_size(u32 LE) + merkle_proof(variable)
+ *
+ * Merkle proof sub-layout:
+ * proof_txid(32) + path_bits(u32 LE) + path_len(u8) + tx_index(u32 LE) + siblings(32 * path_len)
+ */
+export declare function buildVerifyTransactionInstructionData(params: {
+    txid: Uint8Array;
+    blockHash: Uint8Array;
+    txSize: number;
+    txIndex: number;
+    merkleSiblings: Uint8Array[];
+    pathBits: number;
+}): Uint8Array;
+/**
+ * Build utxopia complete_deposit instruction data (disc=11)
+ *
+ * npk + ephemeral_pub are extracted ON-CHAIN from the deposit TX OP_RETURN.
+ * Amount is extracted from the SPV-verified sweep TX.
+ *
+ * Layout: disc(1) + sweep_txid(32) + block_height(u64 LE)
+ *         + sweep_tx_size(u32 LE) + deposit_tx_size(u32 LE) + deposit_txid(32) = 81 bytes
+ */
+export declare function buildCompleteDepositInstructionData(params: {
+    sweepTxid: Uint8Array;
+    blockHeight: number;
+    sweepTxSize: number;
+    depositTxSize: number;
+    depositTxid: Uint8Array;
+}): Uint8Array;
+/** PoolConfig account discriminator (0x0a) */
+export declare const POOL_CONFIG_DISCRIMINATOR = 10;
+/** Serialized PoolConfig account length (bytes) */
+export declare const POOL_CONFIG_LEN = 129;
+/** Max pool_script (P2TR scriptPubKey) length */
+export declare const POOL_SCRIPT_MAX_LEN = 34;
+/**
+ * Build set_pool_config instruction data (disc=2).
+ *
+ * Strict payload — the program rejects any other shape:
+ *   disc(1)
+ *   + pool_script_len(1)
+ *   + pool_script(N, 1..=34)
+ *   + ika_dwallet(32)
+ *   + ika_dwallet_xonly_pubkey(32)
+ *   + cpi_authority_bump(1)
+ *
+ * `group_pub_key` is no longer part of PoolConfig and must not be sent.
+ */
+export declare function buildSetPoolConfigInstructionData(params: {
+    poolScript: Uint8Array;
+    ikaDwallet: Uint8Array;
+    ikaDwalletXonlyPubkey: Uint8Array;
+    cpiAuthorityBump: number;
+}): Uint8Array;
+/** Parsed PoolConfig account (Ika-only, 129 bytes) */
+export interface ParsedPoolConfig {
+    discriminator: number;
+    poolScriptLen: number;
+    poolScript: Uint8Array;
+    ikaDwallet: Uint8Array;
+    ikaDwalletXonlyPubkey: Uint8Array;
+    cpiAuthorityBump: number;
+}
+/**
+ * Parse a PoolConfig account.
+ *
+ * Layout (fixed offsets — pool_script is a 34-byte field regardless of len):
+ *   disc(1) @0, pool_script_len(1) @1, pool_script(34) @2,
+ *   ika_dwallet(32) @36, ika_dwallet_xonly_pubkey(32) @68,
+ *   cpi_authority_bump(1) @100, reserved(28) @101
+ */
+export declare function parsePoolConfig(data: Uint8Array): ParsedPoolConfig;
+/**
+ * Bigint to 32-byte Uint8Array (big-endian)
+ */
+export declare function bigintTo32Bytes(value: bigint): Uint8Array;
+/**
+ * 32-byte Uint8Array to bigint (big-endian)
+ */
+export declare function bytes32ToBigint(bytes: Uint8Array): bigint;
+export { hexToBytes, bytesToHex } from "./crypto";
+/** initializePermissioned instruction options */
+export interface InitializePermissionedOptions {
+    /** PDA bump for pool state */
+    poolBump: number;
+    /** PDA bump for commitment tree */
+    treeBump: number;
+    /** Deposit fee in basis points (u16 LE) */
+    depositFeeBps: number;
+    /** Withdrawal fee in basis points (u16 LE) */
+    withdrawalFeeBps: number;
+    /** Auditor's Solana pubkey (32 bytes) */
+    auditor: Uint8Array;
+    /** Auditor's viewing public key (32 bytes) */
+    auditorViewingPubkey: Uint8Array;
+    /** Account addresses — same layout as initialize (disc=0) */
+    accounts: {
+        /** 0. pool_state (writable) */
+        poolState: Address;
+        /** 1. commitment_tree (writable) */
+        commitmentTree: Address;
+        /** 2. zkbtc_mint (writable) */
+        zkbtcMint: Address;
+        /** 3. pool_vault (writable) */
+        poolVault: Address;
+        /** 4. deposit_vault (writable) */
+        depositVault: Address;
+        /** 5. authority (signer, writable — pays for storage) */
+        authority: Address;
+        /** 6. system_program (readonly) */
+        systemProgram: Address;
+    };
+}
+/**
+ * Build initializePermissioned instruction data (disc=21).
+ *
+ * Layout (after disc byte — same as initialize plus two 32-byte fields):
+ *   pool_bump(1) + tree_bump(1) + deposit_fee_bps(2 LE) + withdrawal_fee_bps(2 LE)
+ *   + auditor(32) + auditor_viewing_pubkey(32)
+ *   = 70 bytes of payload; 71 bytes total with disc.
+ */
+export declare function buildInitializePermissionedInstructionData(options: {
+    poolBump: number;
+    treeBump: number;
+    depositFeeBps: number;
+    withdrawalFeeBps: number;
+    auditor: Uint8Array;
+    auditorViewingPubkey: Uint8Array;
+}): Uint8Array;
+/**
+ * Build a complete initializePermissioned instruction (disc=21).
+ *
+ * Initializes a pool in permissioned mode; deposits/shields require auditor co-signing.
+ *
+ * Accounts (identical to initialize, disc=0):
+ * 0. pool_state          (writable)
+ * 1. commitment_tree     (writable)
+ * 2. zkbtc_mint          (writable)
+ * 3. pool_vault          (writable)
+ * 4. deposit_vault       (writable)
+ * 5. authority           (writable signer)
+ * 6. system_program      (readonly)
+ */
+export declare function buildInitializePermissionedInstruction(options: InitializePermissionedOptions): Instruction;
+/** completeDepositPermissioned instruction options */
+export interface CompleteDepositPermissionedOptions {
+    /** SPV-proven sweep txid (32 bytes, internal byte order) */
+    sweepTxid: Uint8Array;
+    /** Block height containing the verified tx */
+    blockHeight: number;
+    /** Raw sweep tx size in ChadBuffer */
+    sweepTxSize: number;
+    /** Raw deposit tx size in ChadBuffer (0 = direct-to-pool) */
+    depositTxSize: number;
+    /** Deposit txid (32 bytes, internal byte order) */
+    depositTxid: Uint8Array;
+    /**
+     * Auditor ciphertext: either a pre-computed 112-byte `Uint8Array` blob (advanced
+     * / off-chain computed), OR the raw note fields from which the blob is derived
+     * on the fly via {@link buildAuditorCiphertextForNote}.
+     *
+     * If a `Uint8Array` is supplied it is used verbatim (preferred for auditors who
+     * hold the key off-chain).  Pass `{ auditorViewingPubKey, tokenId, amount, commitment }`
+     * to have the builder encrypt and embed the ciphertext automatically.
+     */
+    auditorCiphertext: AuditorCiphertextInput;
+    /** Account addresses — same 15 as complete_deposit PLUS auditor at index 15 */
+    accounts: {
+        /** 0. pool_state (writable) */
+        poolState: Address;
+        /** 1. verified_transaction PDA (readonly) */
+        verifiedTransaction: Address;
+        /** 2. light_client (readonly) */
+        lightClient: Address;
+        /** 3. commitment_tree (writable) */
+        commitmentTree: Address;
+        /** 4. tx_buffer / sweep ChadBuffer (readonly) */
+        txBuffer: Address;
+        /** 5. authority (writable signer) */
+        authority: Address;
+        /** 6. system_program (readonly) */
+        systemProgram: Address;
+        /** 7. zkbtc_mint (writable) */
+        zkbtcMint: Address;
+        /** 8. pool_vault (writable) */
+        poolVault: Address;
+        /** 9. token_program (readonly) */
+        tokenProgram: Address;
+        /** 10. deposit_tx_buffer (readonly) */
+        depositTxBuffer: Address;
+        /** 11. deposit_receipt PDA (writable) */
+        depositReceipt: Address;
+        /** 12. utxo_record PDA (writable) */
+        utxoRecord: Address;
+        /** 13. token_config PDA (writable) */
+        tokenConfig: Address;
+        /** 14. pool_config PDA (readonly) */
+        poolConfig: Address;
+        /** 15. one-time PolicyApproval (writable) */
+        policyApproval: Address;
+    };
+}
+/**
+ * Build completeDepositPermissioned instruction data (disc=22).
+ *
+ * Layout:
+ *   disc(1) + CompleteDepositData fixed header (80 bytes) + auditorCiphertext (variable)
+ *
+ * The 80-byte header is identical to complete_deposit (disc=11).
+ */
+export declare function buildCompleteDepositPermissionedInstructionData(options: {
+    sweepTxid: Uint8Array;
+    blockHeight: number;
+    sweepTxSize: number;
+    depositTxSize: number;
+    depositTxid: Uint8Array;
+    auditorCiphertext: AuditorCiphertextInput;
+}): Uint8Array;
+/**
+ * Build a complete completeDepositPermissioned instruction (disc=22).
+ *
+ * Same accounts as complete_deposit (disc=11), plus a one-time PolicyApproval
+ * appended at account index 15.
+ *
+ * Accounts:
+ * 0.  pool_state          (writable)
+ * 1.  verified_transaction(readonly)
+ * 2.  light_client        (readonly)
+ * 3.  commitment_tree     (writable)
+ * 4.  tx_buffer           (readonly)
+ * 5.  authority           (writable signer)
+ * 6.  system_program      (readonly)
+ * 7.  zkbtc_mint          (writable)
+ * 8.  pool_vault          (writable)
+ * 9.  token_program       (readonly)
+ * 10. deposit_tx_buffer   (readonly)
+ * 11. deposit_receipt     (writable)
+ * 12. utxo_record         (writable)
+ * 13. token_config        (writable)
+ * 14. pool_config         (readonly)
+ * 15. policy_approval     (writable)
+ */
+export declare function buildCompleteDepositPermissionedInstruction(options: CompleteDepositPermissionedOptions): Instruction;
+/** shieldPermissioned instruction options */
+export interface ShieldPermissionedInstructionOptions {
+    /** Amount to shield (in token's smallest unit) */
+    amount: bigint;
+    /** NPK bytes (32) — recipient's note public key */
+    npk: Uint8Array;
+    /** Ephemeral public key (32) — for stealth address derivation */
+    ephemeralPub: Uint8Array;
+    /**
+     * Auditor ciphertext: either a pre-computed 112-byte `Uint8Array` blob (advanced
+     * / off-chain computed), OR the raw note fields from which the blob is derived
+     * on the fly via {@link buildAuditorCiphertextForNote}.
+     *
+     * If a `Uint8Array` is supplied it is used verbatim (preferred for auditors who
+     * hold the key off-chain).  Pass `{ auditorViewingPubKey, tokenId, amount, commitment }`
+     * to have the builder encrypt and embed the ciphertext automatically.
+     */
+    auditorCiphertext: AuditorCiphertextInput;
+    /** Account addresses — same 7 as shield (disc=12) plus PolicyApproval at index 7 */
+    accounts: {
+        /** 0. user (writable signer) */
+        user: Address;
+        /** 1. user_token_account (writable) */
+        userTokenAccount: Address;
+        /** 2. pool_state (readonly) */
+        poolState: Address;
+        /** 3. token_config (writable) */
+        tokenConfig: Address;
+        /** 4. vault (writable) */
+        vault: Address;
+        /** 5. commitment_tree (writable) */
+        commitmentTree: Address;
+        /** 6. token_program (readonly) */
+        tokenProgram: Address;
+        /** 7. one-time PolicyApproval (writable) */
+        policyApproval: Address;
+        /**
+         * 9. ExitDestination PDA registered for `user`.
+         *
+         * Value cannot enter without a way back out: the program refuses a
+         * depositor who has no registered exit, so they can always ragequit to
+         * their own wallet without the auditor. Derive with
+         * {@link deriveExitDestinationPDA} using `EXIT_KIND_SOLANA_OWNER` and the
+         * depositor's address.
+         */
+        exitDestination: Address;
+    };
+}
+/**
+ * Build shieldPermissioned instruction data (disc=23).
+ *
+ * Layout:
+ *   disc(1) + shield header (72 bytes) + auditorCiphertext (variable)
+ *
+ * The 72-byte header is identical to shield (disc=12):
+ *   amount(8 LE) + npk(32) + ephemeral_pub(32)
+ */
+export declare function buildShieldPermissionedInstructionData(options: {
+    amount: bigint;
+    npk: Uint8Array;
+    ephemeralPub: Uint8Array;
+    auditorCiphertext: AuditorCiphertextInput;
+}): Uint8Array;
+/**
+ * Build a complete shieldPermissioned instruction (disc=23).
+ *
+ * Same accounts as shield (disc=12), plus three appended.
+ *
+ * Accounts:
+ * 0. user              (writable signer)
+ * 1. user_token_account(writable)
+ * 2. pool_state        (writable)
+ * 3. token_config      (writable)
+ * 4. vault             (writable)
+ * 5. commitment_tree   (writable)
+ * 6. token_program     (readonly)
+ * 7. policy_approval   (writable)
+ * 8. policy_program    (readonly)
+ * 9. exit_destination  (readonly) — the depositor's registered exit
+ */
+export declare function buildShieldPermissionedInstruction(options: ShieldPermissionedInstructionOptions): Instruction;
+/**
+ * Build a registerExitDestination instruction (disc=39) — auditor-only.
+ *
+ * Adds one entry to a permissioned pool's append-only exit registry. Entries can
+ * be added but never removed: a removable entry would hand the auditor back the
+ * ability to prevent a withdrawal, which is the one power the design withholds.
+ *
+ * Register a depositor's address BEFORE their first `shieldPermissioned` — the
+ * program refuses a depositor who has no exit.
+ *
+ * Data:     kind(1) + key(32)
+ * Accounts: 0. auditor (writable signer, pays rent)
+ *           1. pool_state (readonly)
+ *           2. exit_destination PDA (writable, uninitialized)
+ *           3. system_program (readonly)
+ */
+/**
+ * Build registerExitDestination instruction data (disc=39).
+ *
+ * Layout: disc(1) + kind(1) + key(32)
+ */
+export declare function buildRegisterExitDestinationInstructionData(options: {
+    kind: number;
+    key: Uint8Array;
+}): Uint8Array;
+export declare function buildRegisterExitDestinationInstruction(options: {
+    /** `EXIT_KIND_SOLANA_OWNER` or `EXIT_KIND_BTC_SCRIPT`. */
+    kind: number;
+    /** Recipient token account owner, or sha256(btcScript). */
+    key: Uint8Array;
+    accounts: {
+        auditor: Address;
+        poolState: Address;
+        exitDestination: Address;
+    };
+}): Instruction;
+/** setAuditorFrozen instruction options */
+export interface SetAuditorFrozenOptions {
+    /** true = freeze the auditor role; false = un-freeze */
+    frozen: boolean;
+    accounts: {
+        /** 0. pool_state (writable) */
+        poolState: Address;
+        /** 1. auditor (signer) */
+        auditor: Address;
+    };
+}
+/**
+ * Build setAuditorFrozen instruction data (disc=28).
+ *
+ * Layout: disc(1) + frozen(1)  — frozen byte: 0 = not frozen, 1 = frozen.
+ */
+export declare function buildSetAuditorFrozenInstructionData(frozen: boolean): Uint8Array;
+/**
+ * Build a complete setAuditorFrozen instruction (disc=28).
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. auditor    (signer)
+ */
+export declare function buildSetAuditorFrozenInstruction(options: SetAuditorFrozenOptions): Instruction;
+/** setAuditorViewingPubkey instruction options */
+export interface SetAuditorViewingPubkeyOptions {
+    /** New 32-byte viewing pubkey for the auditor */
+    viewingPubkey: Uint8Array;
+    accounts: {
+        /** 0. pool_state (writable) */
+        poolState: Address;
+        /** 1. auditor (signer) */
+        auditor: Address;
+    };
+}
+/**
+ * Build setAuditorViewingPubkey instruction data (disc=29).
+ *
+ * Layout: disc(1) + viewing_pubkey(32) = 33 bytes.
+ */
+export declare function buildSetAuditorViewingPubkeyInstructionData(viewingPubkey: Uint8Array): Uint8Array;
+/**
+ * Build a complete setAuditorViewingPubkey instruction (disc=29).
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. auditor    (signer)
+ */
+export declare function buildSetAuditorViewingPubkeyInstruction(options: SetAuditorViewingPubkeyOptions): Instruction;
+export interface RotateAuditorOptions {
+    auditor: Uint8Array;
+    viewingPubkey: Uint8Array;
+    accounts: {
+        poolState: Address;
+        authority: Address;
+    };
+}
+export declare function buildRotateAuditorInstructionData(auditor: Uint8Array, viewingPubkey: Uint8Array): Uint8Array;
+export declare function buildRotateAuditorInstruction(options: RotateAuditorOptions): Instruction;