@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/instructions.js

@@ -0,0 +1,1760 @@
+/**
+ * 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, } from "@solana/kit";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { address, getConfig, TOKEN_2022_PROGRAM_ID } from "./config";
+import { resolveAuditorCiphertext } from "./auditor-ciphertext";
+import { MAGICBLOCK_EPHEMERAL_VAULT_ID, MAGICBLOCK_DELEGATION_PROGRAM_ID, MAGICBLOCK_MAGIC_CONTEXT_ID, MAGICBLOCK_MAGIC_PROGRAM_ID, MAGICBLOCK_MAX_PER_MEMBERS, MAGICBLOCK_PERMISSION_PROGRAM_ID, MAGICBLOCK_PER_MEMBER_FLAGS, } from "./magicblock";
+/** System program address */
+const SYSTEM_PROGRAM_ADDRESS = address("11111111111111111111111111111111");
+// =============================================================================
+// Constants
+// =============================================================================
+/** Instruction discriminators — sequential 0-19 (must match contracts/programs/utxopia/src/lib.rs) */
+const INSTRUCTION = {
+    // Core (0-2)
+    INITIALIZE: 0,
+    SET_PAUSED: 1,
+    SET_POOL_CONFIG: 2,
+    // Pool updates (3-5)
+    PROPOSE_POOL_UPDATE: 3,
+    EXECUTE_POOL_UPDATE: 4,
+    CANCEL_POOL_UPDATE: 5,
+    // VK admin (6-7)
+    INIT_VK_REGISTRY: 6,
+    UPDATE_VK_REGISTRY: 7,
+    // Multi-token (8-10)
+    REGISTER_TOKEN: 8,
+    UPDATE_TOKEN_CONFIG: 9,
+    CLAIM_FEES: 10,
+    // Deposit (11-12)
+    COMPLETE_DEPOSIT: 11,
+    SHIELD: 12,
+    // JoinSplit (13-15) — all share n_in + n_out + n_pub + proof_source header
+    TRANSACT: 13,
+    UNSHIELD: 14,
+    REDEEM: 15,
+    // Redemption lifecycle (16-19)
+    RESERVED_REQUEST_REDEMPTION: 16,
+    COMPLETE_REDEMPTION: 17,
+    MARK_PROCESSING: 18,
+    CANCEL_REDEMPTION: 19,
+    // Tree management (20)
+    ROTATE_TREE: 20,
+    // 21-23 are permissioned-pool ops — see PERMISSIONED_DISC
+    APPROVE_REDEMPTION_SIGNING: 27,
+    // Auditor-only setters (28-29) — utxopia program, permissioned pools
+    SET_AUDITOR_FROZEN: 28,
+    SET_AUDITOR_VIEWING_PUBKEY: 29,
+    // MagicBlock ER/PER lifecycle helpers (32-33)
+    MAGICBLOCK_DELEGATE: 32,
+    MAGICBLOCK_COMMIT: 33,
+    MAGICBLOCK_PER_PERMISSION: 34,
+    ROTATE_AUDITOR: 35,
+    INITIALIZE_POLICY_APPROVAL: 36,
+    POLICY_APPROVAL_DECISION: 37,
+    POLICY_APPROVAL_COMMIT: 38,
+};
+/**
+ * Discriminants for permissioned-pool instructions (utxopia program only).
+ * Values must match programs/utxopia/src/lib.rs exactly.
+ */
+const PERMISSIONED_DISC = {
+    INITIALIZE_PERMISSIONED: 21,
+    COMPLETE_DEPOSIT_PERMISSIONED: 22,
+    SHIELD_PERMISSIONED: 23,
+    REGISTER_EXIT_DESTINATION: 39,
+};
+/** Export instruction discriminators for consumers */
+export const INSTRUCTION_DISCRIMINATORS = INSTRUCTION;
+// =============================================================================
+// Utilities
+// =============================================================================
+/**
+ * Simple base58 decoding for addresses
+ */
+function bs58Decode(str) {
+    const ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+    const ALPHABET_MAP = new Map();
+    for (let i = 0; i < ALPHABET.length; i++) {
+        ALPHABET_MAP.set(ALPHABET[i], i);
+    }
+    let num = BigInt(0);
+    for (const char of str) {
+        const val = ALPHABET_MAP.get(char);
+        if (val === undefined) {
+            throw new Error(`Invalid base58 character: ${char}`);
+        }
+        num = num * BigInt(58) + BigInt(val);
+    }
+    // Count leading zeros
+    let leadingZeros = 0;
+    for (const char of str) {
+        if (char === "1") {
+            leadingZeros++;
+        }
+        else {
+            break;
+        }
+    }
+    // Convert to bytes
+    const bytes = [];
+    while (num > BigInt(0)) {
+        bytes.unshift(Number(num % BigInt(256)));
+        num = num / BigInt(256);
+    }
+    // Add leading zeros
+    for (let i = 0; i < leadingZeros; i++) {
+        bytes.unshift(0);
+    }
+    // Ensure 32 bytes for Solana addresses
+    while (bytes.length < 32) {
+        bytes.unshift(0);
+    }
+    return new Uint8Array(bytes);
+}
+/**
+ * Convert Address to bytes
+ */
+function addressToBytes(addr) {
+    return bs58Decode(addr.toString());
+}
+const STEALTH_DATA_PER_OUTPUT = 72; // ephemeral_pub(32) + encrypted_amount(8) + encrypted_token_id(32)
+function assertStealthDataRecordLengths(stealthData) {
+    for (let i = 0; i < stealthData.length; i++) {
+        if (stealthData[i].length !== STEALTH_DATA_PER_OUTPUT) {
+            throw new Error(`Stealth data ${i} must be ${STEALTH_DATA_PER_OUTPUT} bytes, got ${stealthData[i].length}`);
+        }
+    }
+}
+/**
+ * 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 function buildShieldInstructionData(options) {
+    const data = new Uint8Array(73);
+    data[0] = INSTRUCTION.SHIELD;
+    const view = new DataView(data.buffer);
+    view.setBigUint64(1, options.amount, true);
+    data.set(options.npk.slice(0, 32), 9);
+    data.set(options.ephemeralPub.slice(0, 32), 41);
+    return data;
+}
+/**
+ * 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 function buildShieldInstruction(options) {
+    const config = getConfig();
+    const data = buildShieldInstructionData({
+        amount: options.amount,
+        npk: options.npk,
+        ephemeralPub: options.ephemeralPub,
+    });
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.userTokenAccount, role: AccountRole.WRITABLE },
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.tokenConfig, role: AccountRole.WRITABLE },
+            { address: options.accounts.vault, role: AccountRole.WRITABLE },
+            { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+            { address: options.accounts.tokenProgram, role: AccountRole.READONLY },
+        ],
+        data,
+    };
+}
+export function buildApproveRedemptionSigningInstructionData(options) {
+    if (options.btcSighash.length !== 32) {
+        throw new Error("btcSighash must be exactly 32 bytes");
+    }
+    if (options.ikaMessageDigest && options.ikaMessageDigest.length !== 32) {
+        throw new Error("ikaMessageDigest must be exactly 32 bytes");
+    }
+    const data = new Uint8Array(1 + 32 + (options.ikaMessageDigest ? 32 : 0) + 8);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = INSTRUCTION.APPROVE_REDEMPTION_SIGNING;
+    data.set(options.btcSighash, offset);
+    offset += 32;
+    if (options.ikaMessageDigest) {
+        data.set(options.ikaMessageDigest, offset);
+        offset += 32;
+    }
+    view.setBigUint64(offset, BigInt(options.minerFeeSats), true);
+    return data;
+}
+export function buildApproveRedemptionSigningInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.READONLY },
+            { address: options.accounts.redemptionRequest, role: AccountRole.READONLY },
+            { address: options.accounts.authority, role: AccountRole.READONLY_SIGNER },
+            { address: options.accounts.poolConfig, role: AccountRole.READONLY },
+            { address: options.accounts.ikaProgram, role: AccountRole.READONLY },
+            { address: options.accounts.ikaCoordinator, role: AccountRole.READONLY },
+            { address: options.accounts.ikaMessageApproval, role: AccountRole.WRITABLE },
+            { address: options.accounts.ikaDwallet, role: AccountRole.READONLY },
+            { address: options.accounts.callerProgram, role: AccountRole.READONLY },
+            { address: options.accounts.cpiAuthority, role: AccountRole.READONLY },
+            { address: options.accounts.ikaPayer, role: AccountRole.WRITABLE_SIGNER },
+            { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+        ],
+        data: buildApproveRedemptionSigningInstructionData({
+            btcSighash: options.btcSighash,
+            ikaMessageDigest: options.ikaMessageDigest,
+            minerFeeSats: options.minerFeeSats,
+        }),
+    };
+}
+/**
+ * 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 function buildCompleteRedemptionInstructionData(options) {
+    const { btcTxid, txSize, poolScript, consumedUtxoCount } = options;
+    const totalLen = 1 + 32 + 4 + 1 + poolScript.length + 1;
+    const data = new Uint8Array(totalLen);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = INSTRUCTION.COMPLETE_REDEMPTION;
+    data.set(btcTxid, offset);
+    offset += 32;
+    view.setUint32(offset, txSize, true);
+    offset += 4;
+    data[offset++] = poolScript.length;
+    if (poolScript.length > 0) {
+        data.set(poolScript, offset);
+        offset += poolScript.length;
+    }
+    data[offset++] = consumedUtxoCount;
+    return data;
+}
+/**
+ * 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 function buildCompleteRedemptionInstruction(options) {
+    const config = getConfig();
+    const data = buildCompleteRedemptionInstructionData({
+        btcTxid: options.btcTxid,
+        txSize: options.txSize,
+        poolScript: options.poolScript,
+        consumedUtxoCount: options.consumedUtxoCount,
+    });
+    const accounts = [
+        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+        { address: options.accounts.redemptionRequest, role: AccountRole.WRITABLE },
+        { address: options.accounts.authority, role: AccountRole.WRITABLE_SIGNER },
+        { address: options.accounts.rentRecipient, role: AccountRole.READONLY },
+        { address: options.accounts.verifiedTransaction, role: AccountRole.READONLY },
+        { address: options.accounts.lightClient, role: AccountRole.READONLY },
+        { address: options.accounts.txBuffer, role: AccountRole.READONLY },
+        { address: options.accounts.zkbtcMint, role: AccountRole.WRITABLE },
+        { address: options.accounts.poolVault, role: AccountRole.WRITABLE },
+        { address: options.accounts.tokenProgram ?? TOKEN_2022_PROGRAM_ID, role: AccountRole.READONLY },
+        { address: options.accounts.completionReceipt, role: AccountRole.WRITABLE },
+        { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+        { address: options.accounts.poolConfig, role: AccountRole.READONLY },
+    ];
+    if (options.poolScript.length > 0) {
+        if (!options.accounts.changeUtxo) {
+            throw new Error("changeUtxo is required when poolScript is non-empty");
+        }
+        accounts.push({ address: options.accounts.changeUtxo, role: AccountRole.WRITABLE });
+    }
+    // Append consumed UTXO PDAs
+    if (options.accounts.consumedUtxos) {
+        for (const utxo of options.accounts.consumedUtxos) {
+            accounts.push({ address: utxo, role: AccountRole.WRITABLE });
+        }
+    }
+    accounts.push({ address: options.accounts.tokenConfig, role: AccountRole.WRITABLE });
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts,
+        data,
+    };
+}
+/**
+ * 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 function buildCancelRedemptionInstructionData(options) {
+    const { npk, reservedUtxoCount } = options;
+    if (npk.length !== 32) {
+        throw new Error("npk must be 32 bytes");
+    }
+    // disc(1) + npk(32) + utxo_count(1)
+    const data = new Uint8Array(1 + 32 + 1);
+    let offset = 0;
+    data[offset++] = INSTRUCTION.CANCEL_REDEMPTION;
+    data.set(npk, offset);
+    offset += 32;
+    data[offset++] = reservedUtxoCount;
+    return data;
+}
+/**
+ * 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 function buildCancelRedemptionInstruction(options) {
+    const config = getConfig();
+    const reservedUtxos = options.accounts.reservedUtxos ?? [];
+    const data = buildCancelRedemptionInstructionData({
+        npk: options.npk,
+        reservedUtxoCount: reservedUtxos.length,
+    });
+    const accounts = [
+        { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
+        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+        { address: options.accounts.redemptionRequest, role: AccountRole.WRITABLE },
+        { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+        { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+        { address: options.accounts.tokenConfig, role: AccountRole.WRITABLE },
+    ];
+    for (const utxo of reservedUtxos) {
+        accounts.push({ address: utxo, role: AccountRole.WRITABLE });
+    }
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts,
+        data,
+    };
+}
+/**
+ * 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 function buildTransactInstructionData(options) {
+    const { nInputs, nOutputs, proofBytes, merkleRoot, boundParamsHash, nullifiers, commitmentsOut, stealthData, senderMemos } = options;
+    const proofSource = options.proofSource ?? 0;
+    if (proofSource === 0 && (!proofBytes || proofBytes.length !== 256)) {
+        throw new Error(`Inline mode requires 256-byte proof, got ${proofBytes?.length ?? 0}`);
+    }
+    if (nullifiers.length !== nInputs) {
+        throw new Error(`Expected ${nInputs} nullifiers, got ${nullifiers.length}`);
+    }
+    if (commitmentsOut.length !== nOutputs) {
+        throw new Error(`Expected ${nOutputs} commitments, got ${commitmentsOut.length}`);
+    }
+    if (stealthData.length !== nOutputs) {
+        throw new Error(`Expected ${nOutputs} stealth data entries, got ${stealthData.length}`);
+    }
+    assertStealthDataRecordLengths(stealthData);
+    if (senderMemos != null) {
+        throw new Error("senderMemos are disabled until a proof-bound protocol version is available");
+    }
+    const proofSize = proofSource === 0 ? 256 : 0;
+    const totalSize = 1 + 4 + proofSize + 32 + 32 + nInputs * 32 + nOutputs * 32 + nOutputs * STEALTH_DATA_PER_OUTPUT;
+    const data = new Uint8Array(totalSize);
+    let offset = 0;
+    // Discriminator
+    data[offset++] = INSTRUCTION.TRANSACT;
+    // Header (4 bytes)
+    data[offset++] = nInputs;
+    data[offset++] = nOutputs;
+    data[offset++] = 0; // n_public_outputs = 0 for transact
+    data[offset++] = proofSource;
+    // Proof (256 bytes, only in inline mode)
+    if (proofSource === 0 && proofBytes) {
+        data.set(proofBytes, offset);
+        offset += 256;
+    }
+    // Merkle root (32 bytes)
+    data.set(merkleRoot, offset);
+    offset += 32;
+    // Bound params hash (32 bytes)
+    data.set(boundParamsHash, offset);
+    offset += 32;
+    // Nullifiers
+    for (const nullifier of nullifiers) {
+        data.set(nullifier, offset);
+        offset += 32;
+    }
+    // Output commitments
+    for (const commitment of commitmentsOut) {
+        data.set(commitment, offset);
+        offset += 32;
+    }
+    // Stealth data (ephemeral_pub + encrypted_amount per output)
+    for (const sd of stealthData) {
+        data.set(sd, offset);
+        offset += STEALTH_DATA_PER_OUTPUT;
+    }
+    return data;
+}
+/**
+ * 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 function buildTransactInstruction(options) {
+    const config = getConfig();
+    const data = buildTransactInstructionData({
+        nInputs: options.nInputs,
+        nOutputs: options.nOutputs,
+        proofBytes: options.proofBytes,
+        merkleRoot: options.merkleRoot,
+        boundParamsHash: options.boundParamsHash,
+        nullifiers: options.nullifiers,
+        commitmentsOut: options.commitmentsOut,
+        stealthData: options.stealthData,
+        senderMemos: options.senderMemos,
+    });
+    const accounts = [
+        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+        { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+        { address: options.accounts.vkRegistry, role: AccountRole.READONLY },
+        { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
+        { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+    ];
+    // Nullifier records (writable PDAs)
+    for (const nr of options.accounts.nullifierRecords) {
+        accounts.push({ address: nr, role: AccountRole.WRITABLE });
+    }
+    if (options.accounts.policyApproval) {
+        accounts.push({ address: options.accounts.policyApproval, role: AccountRole.WRITABLE });
+        accounts.push({
+            address: config.policyProgramId ?? config.utxopiaProgramId,
+            role: AccountRole.READONLY,
+        });
+    }
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts,
+        data,
+    };
+}
+// =============================================================================
+// JoinSplit + BTC Redeem Instruction Builder (disc=16)
+// =============================================================================
+/**
+ * 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 function buildRedeemInstructionData(options) {
+    const { nInputs, nOutputs, proofBytes, merkleRoot, boundParamsHash, nullifiers, commitmentsOut, stealthData, redeemAmounts, btcScripts, requestNonces, } = options;
+    const nPublicOutputs = options.nPublicOutputs ?? redeemAmounts.length;
+    const proofSource = options.proofSource ?? 0;
+    if (proofSource === 0 && (!proofBytes || proofBytes.length !== 256)) {
+        throw new Error(`Inline mode requires 256-byte proof, got ${proofBytes?.length ?? 0}`);
+    }
+    if (nPublicOutputs < 1 || nPublicOutputs > 3) {
+        throw new Error(`nPublicOutputs must be 1-3, got ${nPublicOutputs}`);
+    }
+    const nTreeOutputs = nOutputs - nPublicOutputs;
+    if (nTreeOutputs < 0) {
+        throw new Error(`nOutputs (${nOutputs}) must be >= nPublicOutputs (${nPublicOutputs})`);
+    }
+    if (nullifiers.length !== nInputs) {
+        throw new Error(`Expected ${nInputs} nullifiers, got ${nullifiers.length}`);
+    }
+    if (commitmentsOut.length !== nOutputs) {
+        throw new Error(`Expected ${nOutputs} commitments, got ${commitmentsOut.length}`);
+    }
+    if (stealthData.length !== nTreeOutputs) {
+        throw new Error(`Expected ${nTreeOutputs} stealth data entries, got ${stealthData.length}`);
+    }
+    assertStealthDataRecordLengths(stealthData);
+    if (redeemAmounts.length !== nPublicOutputs) {
+        throw new Error(`Expected ${nPublicOutputs} redeem amounts, got ${redeemAmounts.length}`);
+    }
+    if (btcScripts.length !== nPublicOutputs) {
+        throw new Error(`Expected ${nPublicOutputs} BTC scripts, got ${btcScripts.length}`);
+    }
+    if (requestNonces.length !== nPublicOutputs) {
+        throw new Error(`Expected ${nPublicOutputs} request nonces, got ${requestNonces.length}`);
+    }
+    for (let k = 0; k < nPublicOutputs; k++) {
+        if (btcScripts[k].length === 0 || btcScripts[k].length > 62) {
+            throw new Error(`BTC script[${k}] must be 1-62 bytes, got ${btcScripts[k].length}`);
+        }
+    }
+    const proofSize = proofSource === 0 ? 256 : 0;
+    let totalScriptLen = 0;
+    for (const s of btcScripts)
+        totalScriptLen += s.length;
+    const totalSize = 1 + 4 + proofSize + 32 + 32
+        + (nInputs * 32) + (nOutputs * 32) + (nTreeOutputs * STEALTH_DATA_PER_OUTPUT)
+        + nPublicOutputs * (8 + 1 + 8) + totalScriptLen;
+    const data = new Uint8Array(totalSize);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    // Discriminator
+    data[offset++] = INSTRUCTION.REDEEM;
+    // Header (4 bytes)
+    data[offset++] = nInputs;
+    data[offset++] = nOutputs;
+    data[offset++] = nPublicOutputs;
+    data[offset++] = proofSource;
+    // Proof (256 bytes, only in inline mode)
+    if (proofSource === 0 && proofBytes) {
+        data.set(proofBytes, offset);
+        offset += 256;
+    }
+    // Merkle root (32 bytes)
+    data.set(merkleRoot, offset);
+    offset += 32;
+    // Bound params hash (32 bytes)
+    data.set(boundParamsHash, offset);
+    offset += 32;
+    // Nullifiers
+    for (const nullifier of nullifiers) {
+        data.set(nullifier, offset);
+        offset += 32;
+    }
+    // Output commitments (all n_outputs, last n_public_outputs = redeem)
+    for (const commitment of commitmentsOut) {
+        data.set(commitment, offset);
+        offset += 32;
+    }
+    // Stealth data for tree outputs only (72 bytes each)
+    for (const sd of stealthData) {
+        data.set(sd, offset);
+        offset += STEALTH_DATA_PER_OUTPUT;
+    }
+    // Per-output redeem data: amount(8) + script_len(1) + script(var) + nonce(8)
+    for (let k = 0; k < nPublicOutputs; k++) {
+        view.setBigUint64(offset, redeemAmounts[k], true);
+        offset += 8;
+        data[offset++] = btcScripts[k].length;
+        data.set(btcScripts[k], offset);
+        offset += btcScripts[k].length;
+        view.setBigUint64(offset, requestNonces[k], true);
+        offset += 8;
+    }
+    return data;
+}
+/**
+ * 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 function buildUnshieldInstructionData(options) {
+    const { nInputs, nOutputs, proofBytes, merkleRoot, boundParamsHash, nullifiers, commitmentsOut, stealthData, unshieldAmounts } = options;
+    const nPublicOutputs = options.nPublicOutputs ?? unshieldAmounts.length;
+    const proofSource = options.proofSource ?? 0;
+    if (proofSource === 0 && (!proofBytes || proofBytes.length !== 256)) {
+        throw new Error(`Inline mode requires 256-byte proof, got ${proofBytes?.length ?? 0}`);
+    }
+    if (nPublicOutputs < 1 || nPublicOutputs > 3) {
+        throw new Error(`nPublicOutputs must be 1-3, got ${nPublicOutputs}`);
+    }
+    if (nullifiers.length !== nInputs) {
+        throw new Error(`Expected ${nInputs} nullifiers, got ${nullifiers.length}`);
+    }
+    if (commitmentsOut.length !== nOutputs) {
+        throw new Error(`Expected ${nOutputs} commitments, got ${commitmentsOut.length}`);
+    }
+    const nTreeOutputs = nOutputs - nPublicOutputs;
+    if (nTreeOutputs < 0) {
+        throw new Error(`nOutputs (${nOutputs}) must be >= nPublicOutputs (${nPublicOutputs})`);
+    }
+    if (stealthData.length !== nTreeOutputs) {
+        throw new Error(`Expected ${nTreeOutputs} stealth data entries (tree outputs), got ${stealthData.length}`);
+    }
+    assertStealthDataRecordLengths(stealthData);
+    if (unshieldAmounts.length !== nPublicOutputs) {
+        throw new Error(`Expected ${nPublicOutputs} unshield amounts, got ${unshieldAmounts.length}`);
+    }
+    const proofSize = proofSource === 0 ? 256 : 0;
+    const totalSize = 1 + 4 + proofSize + 32 + 32 + (nInputs * 32) + (nOutputs * 32) + (nTreeOutputs * STEALTH_DATA_PER_OUTPUT) + (nPublicOutputs * 8);
+    const data = new Uint8Array(totalSize);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    // Discriminator
+    data[offset++] = INSTRUCTION.UNSHIELD;
+    // Header (4 bytes)
+    data[offset++] = nInputs;
+    data[offset++] = nOutputs;
+    data[offset++] = nPublicOutputs;
+    data[offset++] = proofSource;
+    // Proof (256 bytes, only in inline mode)
+    if (proofSource === 0 && proofBytes) {
+        data.set(proofBytes, offset);
+        offset += 256;
+    }
+    // Merkle root (32 bytes)
+    data.set(merkleRoot, offset);
+    offset += 32;
+    // Bound params hash (32 bytes)
+    data.set(boundParamsHash, offset);
+    offset += 32;
+    // Nullifiers
+    for (const nullifier of nullifiers) {
+        data.set(nullifier, offset);
+        offset += 32;
+    }
+    // Output commitments (all n_outputs, last nPublicOutputs = burn)
+    for (const commitment of commitmentsOut) {
+        data.set(commitment, offset);
+        offset += 32;
+    }
+    // Stealth data for tree outputs only
+    for (const sd of stealthData) {
+        data.set(sd, offset);
+        offset += STEALTH_DATA_PER_OUTPUT;
+    }
+    // Per-output unshield amounts (u64 LE each)
+    for (const amount of unshieldAmounts) {
+        view.setBigUint64(offset, amount, true);
+        offset += 8;
+    }
+    return data;
+}
+/**
+ * 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 function buildUnshieldInstruction(options) {
+    const config = getConfig();
+    const nPublicOutputs = options.nPublicOutputs ?? options.unshieldAmounts.length;
+    const data = buildUnshieldInstructionData({
+        nInputs: options.nInputs,
+        nOutputs: options.nOutputs,
+        nPublicOutputs,
+        proofBytes: options.proofBytes,
+        merkleRoot: options.merkleRoot,
+        boundParamsHash: options.boundParamsHash,
+        nullifiers: options.nullifiers,
+        commitmentsOut: options.commitmentsOut,
+        stealthData: options.stealthData,
+        unshieldAmounts: options.unshieldAmounts,
+    });
+    const accounts = [
+        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+        { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+        { address: options.accounts.vkRegistry, role: AccountRole.READONLY },
+        { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
+        { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+        { address: options.accounts.tokenConfig, role: AccountRole.WRITABLE },
+        { address: options.accounts.vault, role: AccountRole.WRITABLE },
+        { address: options.accounts.tokenProgram ?? TOKEN_2022_PROGRAM_ID, role: AccountRole.READONLY },
+    ];
+    // Public destinations (one per public output)
+    for (const rta of options.accounts.recipientTokenAccounts) {
+        accounts.push({ address: rta, role: AccountRole.WRITABLE });
+    }
+    // Nullifier records (writable PDAs)
+    for (const nr of options.accounts.nullifierRecords) {
+        accounts.push({ address: nr, role: AccountRole.WRITABLE });
+    }
+    if (options.accounts.policyApproval) {
+        accounts.push({ address: options.accounts.policyApproval, role: AccountRole.WRITABLE });
+        accounts.push({
+            address: config.policyProgramId ?? config.utxopiaProgramId,
+            role: AccountRole.READONLY,
+        });
+    }
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts,
+        data,
+    };
+}
+/**
+ * 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 function buildProposePoolUpdateInstructionData(minDeposit, maxDeposit, serviceFee, serviceFeeBps) {
+    const hasBps = serviceFeeBps !== undefined;
+    const data = new Uint8Array(hasBps ? 27 : 25);
+    const view = new DataView(data.buffer);
+    data[0] = INSTRUCTION.PROPOSE_POOL_UPDATE;
+    view.setBigUint64(1, minDeposit, true);
+    view.setBigUint64(9, maxDeposit, true);
+    view.setBigUint64(17, serviceFee, true);
+    if (hasBps) {
+        view.setUint16(25, serviceFeeBps, true);
+    }
+    return data;
+}
+/**
+ * Build a complete propose_pool_update instruction
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. authority (signer)
+ */
+export function buildProposePoolUpdateInstruction(options) {
+    const config = getConfig();
+    const data = buildProposePoolUpdateInstructionData(options.minDeposit, options.maxDeposit, options.serviceFee, options.serviceFeeBps);
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.authority, role: AccountRole.WRITABLE_SIGNER },
+        ],
+        data,
+    };
+}
+/**
+ * Build execute_pool_update instruction data
+ *
+ * Layout: discriminator(1) = 1 byte
+ */
+export function buildExecutePoolUpdateInstructionData() {
+    return new Uint8Array([INSTRUCTION.EXECUTE_POOL_UPDATE]);
+}
+/**
+ * Build a complete execute_pool_update instruction (authority-only)
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. authority (signer)
+ */
+export function buildExecutePoolUpdateInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.authority, role: AccountRole.READONLY_SIGNER },
+        ],
+        data: buildExecutePoolUpdateInstructionData(),
+    };
+}
+/**
+ * Build cancel_pool_update instruction data
+ *
+ * Layout: discriminator(1) = 1 byte
+ */
+export function buildCancelPoolUpdateInstructionData() {
+    return new Uint8Array([INSTRUCTION.CANCEL_POOL_UPDATE]);
+}
+/**
+ * Build a complete cancel_pool_update instruction
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. authority (signer)
+ */
+export function buildCancelPoolUpdateInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.authority, role: AccountRole.WRITABLE_SIGNER },
+        ],
+        data: buildCancelPoolUpdateInstructionData(),
+    };
+}
+/**
+ * Build rotate_tree instruction data (disc=20, no payload)
+ */
+export function buildRotateTreeInstructionData() {
+    return new Uint8Array([INSTRUCTION.ROTATE_TREE]);
+}
+/**
+ * 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 function buildRotateTreeInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.currentTree, role: AccountRole.WRITABLE },
+            { address: options.accounts.newTree, role: AccountRole.WRITABLE },
+            { address: options.accounts.authority, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.systemProgram, role: AccountRole.READONLY },
+        ],
+        data: buildRotateTreeInstructionData(),
+    };
+}
+function magicBlockDelegateTargetByte(target) {
+    if (target === "policyApproval")
+        return 2;
+    throw new Error(`Unsupported MagicBlock delegate target: ${target}`);
+}
+/**
+ * Build magicblock_delegate instruction data (disc=32).
+ */
+export function buildMagicBlockDelegateInstructionData(options) {
+    if (!Number.isInteger(options.commitFrequencyMs) || options.commitFrequencyMs < 0) {
+        throw new Error("commitFrequencyMs must be a non-negative u32");
+    }
+    if (options.commitFrequencyMs > 0xffffffff) {
+        throw new Error("commitFrequencyMs must fit in u32");
+    }
+    const data = new Uint8Array(options.validator ? 38 : 6);
+    const view = new DataView(data.buffer);
+    data[0] = INSTRUCTION.MAGICBLOCK_DELEGATE;
+    data[1] = magicBlockDelegateTargetByte(options.target);
+    view.setUint32(2, options.commitFrequencyMs, true);
+    if (options.validator) {
+        data.set(addressToBytes(options.validator), 6);
+    }
+    return data;
+}
+/**
+ * Build a complete magicblock_delegate instruction.
+ */
+export function buildMagicBlockDelegateInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.policyProgramId ?? config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.payer, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.authority, role: AccountRole.READONLY_SIGNER },
+            { address: options.accounts.poolState, role: AccountRole.READONLY },
+            { address: options.accounts.delegatedAccount, role: AccountRole.WRITABLE },
+            {
+                address: options.accounts.ownerProgram ?? config.policyProgramId ?? config.utxopiaProgramId,
+                role: AccountRole.READONLY,
+            },
+            { address: options.accounts.buffer, role: AccountRole.WRITABLE },
+            { address: options.accounts.delegationRecord, role: AccountRole.WRITABLE },
+            { address: options.accounts.delegationMetadata, role: AccountRole.WRITABLE },
+            { address: options.accounts.systemProgram ?? SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+            { address: MAGICBLOCK_DELEGATION_PROGRAM_ID, role: AccountRole.READONLY },
+        ],
+        data: buildMagicBlockDelegateInstructionData({
+            target: options.target,
+            commitFrequencyMs: options.commitFrequencyMs,
+            validator: options.validator,
+        }),
+    };
+}
+/**
+ * Build magicblock_commit instruction data (disc=33).
+ */
+export function buildMagicBlockCommitInstructionData(options) {
+    if (options.nullifierHashes.length === 0 ||
+        options.nullifierHashes.length > 10) {
+        throw new Error("MagicBlock commits require 1-10 nullifier hashes");
+    }
+    for (const hash of options.nullifierHashes) {
+        if (hash.length !== 32) {
+            throw new Error("Each MagicBlock commit nullifier hash must be 32 bytes");
+        }
+    }
+    const data = new Uint8Array(4 + options.nullifierHashes.length * 32);
+    data[0] = INSTRUCTION.MAGICBLOCK_COMMIT;
+    data[1] = 1;
+    data[2] = options.allowUndelegation ? 1 : 0;
+    data[3] = options.nullifierHashes.length;
+    options.nullifierHashes.forEach((hash, index) => data.set(hash, 4 + index * 32));
+    return data;
+}
+/**
+ * Build a complete magicblock_commit instruction.
+ */
+export function buildMagicBlockCommitInstruction(options) {
+    const config = getConfig();
+    if (options.accounts.nullifierAccounts.length !== options.nullifierHashes.length) {
+        throw new Error("Nullifier account and hash counts must match");
+    }
+    const accounts = [
+        { address: options.accounts.payer, role: AccountRole.READONLY_SIGNER },
+        {
+            address: options.accounts.authority ?? options.accounts.payer,
+            role: AccountRole.READONLY_SIGNER,
+        },
+        {
+            address: options.accounts.magicContext ?? MAGICBLOCK_MAGIC_CONTEXT_ID,
+            role: AccountRole.WRITABLE,
+        },
+        { address: options.accounts.magicProgram ?? MAGICBLOCK_MAGIC_PROGRAM_ID, role: AccountRole.READONLY },
+        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+        { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+    ];
+    for (const nullifier of options.accounts.nullifierAccounts) {
+        accounts.push({ address: nullifier, role: AccountRole.WRITABLE });
+    }
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts,
+        data: buildMagicBlockCommitInstructionData({
+            nullifierHashes: options.nullifierHashes,
+            allowUndelegation: options.allowUndelegation,
+        }),
+    };
+}
+function magicBlockPerOperationByte(operation) {
+    if (operation === "create")
+        return 0;
+    if (operation === "update")
+        return 1;
+    if (operation === "close")
+        return 2;
+    throw new Error(`Unsupported MagicBlock PER operation: ${operation}`);
+}
+export function buildMagicBlockPerPermissionInstructionData(options) {
+    const members = options.members ?? [];
+    if (options.operation === "close") {
+        if (members.length !== 0) {
+            throw new Error("Closing a MagicBlock PER permission does not accept members");
+        }
+    }
+    else {
+        if (members.length === 0 || members.length > MAGICBLOCK_MAX_PER_MEMBERS) {
+            throw new Error(`MagicBlock PER permissions require 1-${MAGICBLOCK_MAX_PER_MEMBERS} members`);
+        }
+        if (!members.some((member) => (member.flags & MAGICBLOCK_PER_MEMBER_FLAGS.authority) !== 0)) {
+            throw new Error("MagicBlock PER permissions must retain an authority member");
+        }
+    }
+    const allowedFlags = Object.values(MAGICBLOCK_PER_MEMBER_FLAGS).reduce((combined, flag) => combined | flag, 0);
+    const data = new Uint8Array(4 + members.length * 33);
+    data[0] = INSTRUCTION.MAGICBLOCK_PER_PERMISSION;
+    data[1] = magicBlockPerOperationByte(options.operation);
+    data[2] = magicBlockDelegateTargetByte(options.target);
+    data[3] = members.length;
+    members.forEach((member, index) => {
+        if (!Number.isInteger(member.flags) || member.flags < 0 || member.flags > 0xff) {
+            throw new Error("MagicBlock PER member flags must fit in u8");
+        }
+        if ((member.flags & ~allowedFlags) !== 0) {
+            throw new Error("MagicBlock PER member flags contain unsupported bits");
+        }
+        const offset = 4 + index * 33;
+        data[offset] = member.flags;
+        data.set(addressToBytes(member.address), offset + 1);
+    });
+    return data;
+}
+export function buildMagicBlockPerPermissionInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.policyProgramId ?? config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.authority, role: AccountRole.READONLY_SIGNER },
+            { address: options.accounts.poolState, role: AccountRole.READONLY },
+            { address: options.accounts.permissionedAccount, role: AccountRole.WRITABLE },
+            { address: options.accounts.permission, role: AccountRole.WRITABLE },
+            {
+                address: options.accounts.ephemeralVault ?? MAGICBLOCK_EPHEMERAL_VAULT_ID,
+                role: AccountRole.WRITABLE,
+            },
+            {
+                address: options.accounts.magicProgram ?? MAGICBLOCK_MAGIC_PROGRAM_ID,
+                role: AccountRole.READONLY,
+            },
+            {
+                address: options.accounts.permissionProgram ?? MAGICBLOCK_PERMISSION_PROGRAM_ID,
+                role: AccountRole.READONLY,
+            },
+        ],
+        data: buildMagicBlockPerPermissionInstructionData(options),
+    };
+}
+/** Must match `MAX_INTENT_PARTS` in the asset program. */
+export 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 function buildPolicyIntentParts(options) {
+    const nullifiers = concatBytes(options.nullifiers);
+    if (options.action === INSTRUCTION.TRANSACT) {
+        // An internal transfer reveals no amount and no external destination, so the
+        // only thing being decided is whether these notes may be spent at all.
+        return [nullifiers];
+    }
+    if (options.action === INSTRUCTION.UNSHIELD) {
+        const amounts = new Uint8Array(options.unshieldAmounts.length * 8);
+        const view = new DataView(amounts.buffer);
+        options.unshieldAmounts.forEach((amount, i) => view.setBigUint64(i * 8, amount, true));
+        for (const owner of options.recipientOwners) {
+            if (owner.length !== 32)
+                throw new Error("recipient owner must be 32 bytes");
+        }
+        return [nullifiers, amounts, concatBytes(options.recipientOwners)];
+    }
+    // redeem: amount(8) + script_len(1) + script(var) + nonce(8), per output
+    const { redeemAmounts, btcScripts, requestNonces } = options;
+    if (redeemAmounts.length !== btcScripts.length || btcScripts.length !== requestNonces.length) {
+        throw new Error("redeem amounts, scripts and nonces must be the same length");
+    }
+    const size = redeemAmounts.length * 17 + btcScripts.reduce((n, s) => n + s.length, 0);
+    const outputs = new Uint8Array(size);
+    const view = new DataView(outputs.buffer);
+    let offset = 0;
+    for (let k = 0; k < redeemAmounts.length; k++) {
+        view.setBigUint64(offset, redeemAmounts[k], true);
+        offset += 8;
+        outputs[offset++] = btcScripts[k].length;
+        outputs.set(btcScripts[k], offset);
+        offset += btcScripts[k].length;
+        view.setBigUint64(offset, requestNonces[k], true);
+        offset += 8;
+    }
+    return [nullifiers, outputs];
+}
+function concatBytes(chunks) {
+    const out = new Uint8Array(chunks.reduce((n, c) => n + c.length, 0));
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/**
+ * 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 function buildPolicyRequestHash(options) {
+    if (options.intentParts.length < 1 ||
+        options.intentParts.length > MAX_POLICY_INTENT_PARTS) {
+        throw new Error(`Policy intent must have 1-${MAX_POLICY_INTENT_PARTS} parts`);
+    }
+    const domain = new TextEncoder().encode("UTXOPIA_POLICY_APPROVAL_V1");
+    const chunks = [
+        domain,
+        addressToBytes(options.programId),
+        addressToBytes(options.poolState),
+        addressToBytes(options.actor),
+        Uint8Array.of(options.action),
+        Uint8Array.of(options.intentParts.length),
+        ...options.intentParts.map((part) => sha256(part)),
+    ];
+    const length = chunks.reduce((total, chunk) => total + chunk.length, 0);
+    const preimage = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        preimage.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return sha256(preimage);
+}
+export function buildInitializePolicyApprovalInstructionData(options) {
+    if (!Number.isInteger(options.action) || options.action < 0 || options.action > 0xff) {
+        throw new Error("Policy approval action must fit in u8");
+    }
+    if (options.requestHash.length !== 32 || options.nonce.length !== 32) {
+        throw new Error("Policy approval requestHash and nonce must be 32 bytes");
+    }
+    const data = new Uint8Array(106);
+    const view = new DataView(data.buffer);
+    data[0] = INSTRUCTION.INITIALIZE_POLICY_APPROVAL;
+    data[1] = options.action;
+    view.setBigUint64(2, options.expiresAtSlot, true);
+    data.set(addressToBytes(options.actor), 10);
+    data.set(options.requestHash, 42);
+    data.set(options.nonce, 74);
+    return data;
+}
+export function buildInitializePolicyApprovalInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.policyProgramId ?? config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.payer, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.poolState, role: AccountRole.READONLY },
+            { address: options.accounts.policyApproval, role: AccountRole.WRITABLE },
+            {
+                address: options.accounts.systemProgram ?? SYSTEM_PROGRAM_ADDRESS,
+                role: AccountRole.READONLY,
+            },
+        ],
+        data: buildInitializePolicyApprovalInstructionData(options),
+    };
+}
+export function buildPolicyApprovalDecisionInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.policyProgramId ?? config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.policyAuthority, role: AccountRole.READONLY_SIGNER },
+            { address: options.accounts.policyApproval, role: AccountRole.WRITABLE },
+        ],
+        data: new Uint8Array([
+            INSTRUCTION.POLICY_APPROVAL_DECISION,
+            options.decision === "approve" ? 1 : 2,
+        ]),
+    };
+}
+export function buildPolicyApprovalCommitInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.policyProgramId ?? config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.payer, role: AccountRole.READONLY_SIGNER },
+            {
+                address: options.accounts.magicContext ?? MAGICBLOCK_MAGIC_CONTEXT_ID,
+                role: AccountRole.WRITABLE,
+            },
+            {
+                address: options.accounts.magicProgram ?? MAGICBLOCK_MAGIC_PROGRAM_ID,
+                role: AccountRole.READONLY,
+            },
+            { address: options.accounts.policyApproval, role: AccountRole.WRITABLE },
+        ],
+        data: new Uint8Array([INSTRUCTION.POLICY_APPROVAL_COMMIT]),
+    };
+}
+// =============================================================================
+// Redemption Request PDA Derivation
+// =============================================================================
+// deriveRedemptionRequestPDA lived here too, over inlined copies of the same seeds pda.ts
+// already builds — and it returned `address: userBytes`, the caller's own pubkey rather than the
+// derived address, leaving a comment telling you to derive it yourself. Nothing used it. Use
+// `deriveRedemptionRequestPDA` from pda.ts, which returns the real PDA.
+// =============================================================================
+// BTC Light Client Verify Transaction (disc=2)
+// =============================================================================
+/**
+ * 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 function buildVerifyTransactionInstructionData(params) {
+    const { txid, blockHash, txSize, txIndex, merkleSiblings, pathBits } = params;
+    const pathLen = merkleSiblings.length;
+    // disc(1) + txid(32) + blockHash(32) + txSize(4) + proofTxid(32) + pathBits(4) + pathLen(1) + txIndex(4) + siblings(32*N)
+    const totalSize = 1 + 32 + 32 + 4 + 32 + 4 + 1 + 4 + 32 * pathLen;
+    const data = new Uint8Array(totalSize);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = 2; // discriminator for verify_transaction
+    data.set(txid, offset);
+    offset += 32;
+    data.set(blockHash, offset);
+    offset += 32;
+    view.setUint32(offset, txSize, true);
+    offset += 4;
+    // Merkle proof sub-layout
+    data.set(txid, offset);
+    offset += 32; // proof_txid = txid
+    view.setUint32(offset, pathBits, true);
+    offset += 4;
+    data[offset++] = pathLen;
+    view.setUint32(offset, txIndex, true);
+    offset += 4;
+    for (const sibling of merkleSiblings) {
+        data.set(sibling, offset);
+        offset += 32;
+    }
+    return data;
+}
+// =============================================================================
+// UTXOpia Complete Deposit (disc=11)
+// =============================================================================
+/**
+ * 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 function buildCompleteDepositInstructionData(params) {
+    const data = new Uint8Array(81);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = INSTRUCTION.COMPLETE_DEPOSIT;
+    data.set(params.sweepTxid, offset);
+    offset += 32;
+    view.setBigUint64(offset, BigInt(params.blockHeight), true);
+    offset += 8;
+    view.setUint32(offset, params.sweepTxSize, true);
+    offset += 4;
+    view.setUint32(offset, params.depositTxSize, true);
+    offset += 4;
+    data.set(params.depositTxid, offset);
+    offset += 32;
+    return data;
+}
+// =============================================================================
+// UTXOpia Set Pool Config (disc=2)
+// =============================================================================
+/** PoolConfig account discriminator (0x0a) */
+export const POOL_CONFIG_DISCRIMINATOR = 0x0a;
+/** Serialized PoolConfig account length (bytes) */
+export const POOL_CONFIG_LEN = 129;
+/** Max pool_script (P2TR scriptPubKey) length */
+export 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 function buildSetPoolConfigInstructionData(params) {
+    const { poolScript, ikaDwallet, ikaDwalletXonlyPubkey, cpiAuthorityBump } = params;
+    if (poolScript.length < 1 || poolScript.length > POOL_SCRIPT_MAX_LEN) {
+        throw new Error(`poolScript length must be 1..=${POOL_SCRIPT_MAX_LEN}, got ${poolScript.length}`);
+    }
+    if (ikaDwallet.length !== 32) {
+        throw new Error(`ikaDwallet must be 32 bytes, got ${ikaDwallet.length}`);
+    }
+    if (ikaDwalletXonlyPubkey.length !== 32) {
+        throw new Error(`ikaDwalletXonlyPubkey must be 32 bytes, got ${ikaDwalletXonlyPubkey.length}`);
+    }
+    const data = new Uint8Array(1 + 1 + poolScript.length + 32 + 32 + 1);
+    let offset = 0;
+    data[offset++] = INSTRUCTION.SET_POOL_CONFIG;
+    data[offset++] = poolScript.length;
+    data.set(poolScript, offset);
+    offset += poolScript.length;
+    data.set(ikaDwallet, offset);
+    offset += 32;
+    data.set(ikaDwalletXonlyPubkey, offset);
+    offset += 32;
+    data[offset++] = cpiAuthorityBump;
+    return data;
+}
+/**
+ * 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 function parsePoolConfig(data) {
+    if (data.length < POOL_CONFIG_LEN) {
+        throw new Error(`PoolConfig account too small: ${data.length} < ${POOL_CONFIG_LEN}`);
+    }
+    if (data[0] !== POOL_CONFIG_DISCRIMINATOR) {
+        throw new Error(`Invalid PoolConfig discriminator: 0x${data[0].toString(16)}`);
+    }
+    const poolScriptLen = data[1];
+    if (poolScriptLen > POOL_SCRIPT_MAX_LEN) {
+        throw new Error(`Invalid pool script length: ${poolScriptLen}`);
+    }
+    return {
+        discriminator: data[0],
+        poolScriptLen,
+        poolScript: data.subarray(2, 2 + poolScriptLen),
+        ikaDwallet: data.subarray(36, 68),
+        ikaDwalletXonlyPubkey: data.subarray(68, 100),
+        cpiAuthorityBump: data[100],
+    };
+}
+// =============================================================================
+// Utility Exports
+// =============================================================================
+/**
+ * Bigint to 32-byte Uint8Array (big-endian)
+ */
+export function bigintTo32Bytes(value) {
+    const hex = value.toString(16).padStart(64, "0");
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 32; i++) {
+        bytes[i] = parseInt(hex.slice(i * 2, i * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * 32-byte Uint8Array to bigint (big-endian)
+ */
+export function bytes32ToBigint(bytes) {
+    if (bytes.length !== 32) {
+        throw new Error("Expected 32 bytes");
+    }
+    let hex = "0x";
+    for (let i = 0; i < 32; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return BigInt(hex);
+}
+// hexToBytes / bytesToHex live in ./crypto (single source); re-exported here
+// to preserve this module's public surface.
+export { hexToBytes, bytesToHex } from "./crypto";
+/**
+ * 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 function buildInitializePermissionedInstructionData(options) {
+    if (options.auditor.length !== 32) {
+        throw new Error(`auditor must be 32 bytes, got ${options.auditor.length}`);
+    }
+    if (options.auditorViewingPubkey.length !== 32) {
+        throw new Error(`auditorViewingPubkey must be 32 bytes, got ${options.auditorViewingPubkey.length}`);
+    }
+    // disc(1) + pool_bump(1) + tree_bump(1) + deposit_fee_bps(2) + withdrawal_fee_bps(2) + auditor(32) + auditor_viewing_pubkey(32) = 71
+    const data = new Uint8Array(71);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = PERMISSIONED_DISC.INITIALIZE_PERMISSIONED; // disc = 21
+    data[offset++] = options.poolBump;
+    data[offset++] = options.treeBump;
+    view.setUint16(offset, options.depositFeeBps, true);
+    offset += 2;
+    view.setUint16(offset, options.withdrawalFeeBps, true);
+    offset += 2;
+    data.set(options.auditor, offset);
+    offset += 32;
+    data.set(options.auditorViewingPubkey, offset);
+    return data;
+}
+/**
+ * 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 function buildInitializePermissionedInstruction(options) {
+    const config = getConfig();
+    const data = buildInitializePermissionedInstructionData({
+        poolBump: options.poolBump,
+        treeBump: options.treeBump,
+        depositFeeBps: options.depositFeeBps,
+        withdrawalFeeBps: options.withdrawalFeeBps,
+        auditor: options.auditor,
+        auditorViewingPubkey: options.auditorViewingPubkey,
+    });
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+            { address: options.accounts.zkbtcMint, role: AccountRole.WRITABLE },
+            { address: options.accounts.poolVault, role: AccountRole.WRITABLE },
+            { address: options.accounts.depositVault, role: AccountRole.WRITABLE },
+            { address: options.accounts.authority, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.systemProgram, role: AccountRole.READONLY },
+        ],
+        data,
+    };
+}
+/**
+ * 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 function buildCompleteDepositPermissionedInstructionData(options) {
+    // disc(1) + sweep_txid(32) + block_height(8) + sweep_tx_size(4) + deposit_tx_size(4) + deposit_txid(32) + auditorCiphertext(variable)
+    const auditorCiphertext = resolveAuditorCiphertext(options.auditorCiphertext);
+    const headerSize = 1 + 32 + 8 + 4 + 4 + 32; // 81 bytes
+    const data = new Uint8Array(headerSize + auditorCiphertext.length);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = PERMISSIONED_DISC.COMPLETE_DEPOSIT_PERMISSIONED; // disc = 22
+    data.set(options.sweepTxid, offset);
+    offset += 32;
+    view.setBigUint64(offset, BigInt(options.blockHeight), true);
+    offset += 8;
+    view.setUint32(offset, options.sweepTxSize, true);
+    offset += 4;
+    view.setUint32(offset, options.depositTxSize, true);
+    offset += 4;
+    data.set(options.depositTxid, offset);
+    offset += 32;
+    if (auditorCiphertext.length > 0) {
+        data.set(auditorCiphertext, offset);
+    }
+    return data;
+}
+/**
+ * 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 function buildCompleteDepositPermissionedInstruction(options) {
+    const config = getConfig();
+    const data = buildCompleteDepositPermissionedInstructionData({
+        sweepTxid: options.sweepTxid,
+        blockHeight: options.blockHeight,
+        sweepTxSize: options.sweepTxSize,
+        depositTxSize: options.depositTxSize,
+        depositTxid: options.depositTxid,
+        auditorCiphertext: options.auditorCiphertext,
+    });
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.verifiedTransaction, role: AccountRole.READONLY },
+            { address: options.accounts.lightClient, role: AccountRole.READONLY },
+            { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+            { address: options.accounts.txBuffer, role: AccountRole.READONLY },
+            { address: options.accounts.authority, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.systemProgram, role: AccountRole.READONLY },
+            { address: options.accounts.zkbtcMint, role: AccountRole.WRITABLE },
+            { address: options.accounts.poolVault, role: AccountRole.WRITABLE },
+            { address: options.accounts.tokenProgram, role: AccountRole.READONLY },
+            { address: options.accounts.depositTxBuffer, role: AccountRole.READONLY },
+            { address: options.accounts.depositReceipt, role: AccountRole.WRITABLE },
+            { address: options.accounts.utxoRecord, role: AccountRole.WRITABLE },
+            { address: options.accounts.tokenConfig, role: AccountRole.WRITABLE },
+            { address: options.accounts.poolConfig, role: AccountRole.READONLY },
+            { address: options.accounts.policyApproval, role: AccountRole.WRITABLE },
+            { address: config.policyProgramId ?? config.utxopiaProgramId, role: AccountRole.READONLY },
+        ],
+        data,
+    };
+}
+/**
+ * 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 function buildShieldPermissionedInstructionData(options) {
+    // disc(1) + amount(8) + npk(32) + ephemeral_pub(32) + auditorCiphertext(variable)
+    const auditorCiphertext = resolveAuditorCiphertext(options.auditorCiphertext);
+    const headerSize = 1 + 8 + 32 + 32; // 73 bytes
+    const data = new Uint8Array(headerSize + auditorCiphertext.length);
+    const view = new DataView(data.buffer);
+    let offset = 0;
+    data[offset++] = PERMISSIONED_DISC.SHIELD_PERMISSIONED; // disc = 23
+    view.setBigUint64(offset, options.amount, true);
+    offset += 8;
+    data.set(options.npk.slice(0, 32), offset);
+    offset += 32;
+    data.set(options.ephemeralPub.slice(0, 32), offset);
+    offset += 32;
+    if (auditorCiphertext.length > 0) {
+        data.set(auditorCiphertext, offset);
+    }
+    return data;
+}
+/**
+ * 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 function buildShieldPermissionedInstruction(options) {
+    const config = getConfig();
+    const data = buildShieldPermissionedInstructionData({
+        amount: options.amount,
+        npk: options.npk,
+        ephemeralPub: options.ephemeralPub,
+        auditorCiphertext: options.auditorCiphertext,
+    });
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.userTokenAccount, role: AccountRole.WRITABLE },
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.tokenConfig, role: AccountRole.WRITABLE },
+            { address: options.accounts.vault, role: AccountRole.WRITABLE },
+            { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+            { address: options.accounts.tokenProgram, role: AccountRole.READONLY },
+            { address: options.accounts.policyApproval, role: AccountRole.WRITABLE },
+            { address: config.policyProgramId ?? config.utxopiaProgramId, role: AccountRole.READONLY },
+            { address: options.accounts.exitDestination, role: AccountRole.READONLY },
+        ],
+        data,
+    };
+}
+// ---------------------------------------------------------------------------
+// registerExitDestination (disc=39)
+// ---------------------------------------------------------------------------
+/**
+ * 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 function buildRegisterExitDestinationInstructionData(options) {
+    if (options.key.length !== 32) {
+        throw new Error("exit destination key must be 32 bytes");
+    }
+    const data = new Uint8Array(34);
+    data[0] = PERMISSIONED_DISC.REGISTER_EXIT_DESTINATION;
+    data[1] = options.kind;
+    data.set(options.key, 2);
+    return data;
+}
+export function buildRegisterExitDestinationInstruction(options) {
+    const config = getConfig();
+    const data = buildRegisterExitDestinationInstructionData(options);
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.auditor, role: AccountRole.WRITABLE_SIGNER },
+            { address: options.accounts.poolState, role: AccountRole.READONLY },
+            { address: options.accounts.exitDestination, role: AccountRole.WRITABLE },
+            { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
+        ],
+        data,
+    };
+}
+/**
+ * Build setAuditorFrozen instruction data (disc=28).
+ *
+ * Layout: disc(1) + frozen(1)  — frozen byte: 0 = not frozen, 1 = frozen.
+ */
+export function buildSetAuditorFrozenInstructionData(frozen) {
+    return new Uint8Array([INSTRUCTION.SET_AUDITOR_FROZEN, frozen ? 1 : 0]);
+}
+/**
+ * Build a complete setAuditorFrozen instruction (disc=28).
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. auditor    (signer)
+ */
+export function buildSetAuditorFrozenInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.auditor, role: AccountRole.READONLY_SIGNER },
+        ],
+        data: buildSetAuditorFrozenInstructionData(options.frozen),
+    };
+}
+/**
+ * Build setAuditorViewingPubkey instruction data (disc=29).
+ *
+ * Layout: disc(1) + viewing_pubkey(32) = 33 bytes.
+ */
+export function buildSetAuditorViewingPubkeyInstructionData(viewingPubkey) {
+    if (viewingPubkey.length !== 32) {
+        throw new Error(`viewingPubkey must be 32 bytes, got ${viewingPubkey.length}`);
+    }
+    const data = new Uint8Array(33);
+    data[0] = INSTRUCTION.SET_AUDITOR_VIEWING_PUBKEY;
+    data.set(viewingPubkey, 1);
+    return data;
+}
+/**
+ * Build a complete setAuditorViewingPubkey instruction (disc=29).
+ *
+ * Accounts:
+ * 0. pool_state (writable)
+ * 1. auditor    (signer)
+ */
+export function buildSetAuditorViewingPubkeyInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.auditor, role: AccountRole.READONLY_SIGNER },
+        ],
+        data: buildSetAuditorViewingPubkeyInstructionData(options.viewingPubkey),
+    };
+}
+export function buildRotateAuditorInstructionData(auditor, viewingPubkey) {
+    if (auditor.length !== 32 || auditor.every((byte) => byte === 0)) {
+        throw new Error("auditor must be a nonzero 32-byte public key");
+    }
+    if (viewingPubkey.length !== 32 || viewingPubkey.every((byte) => byte === 0)) {
+        throw new Error("viewingPubkey must be a nonzero 32-byte public key");
+    }
+    const data = new Uint8Array(65);
+    data[0] = INSTRUCTION.ROTATE_AUDITOR;
+    data.set(auditor, 1);
+    data.set(viewingPubkey, 33);
+    return data;
+}
+export function buildRotateAuditorInstruction(options) {
+    const config = getConfig();
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts: [
+            { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+            { address: options.accounts.authority, role: AccountRole.READONLY_SIGNER },
+        ],
+        data: buildRotateAuditorInstructionData(options.auditor, options.viewingPubkey),
+    };
+}