@utxopia/sdk 0.1.0-alpha.7 → 0.1.0-alpha.8

package/dist/commitment-tree.js

@@ -189,7 +189,16 @@ export class CommitmentTreeIndex {
         if (leafIndex >= MAX_LEAVES) {
             throw new Error("Tree is full");
         }
-        // Store in map for lookup
+        // Store in map for lookup.
+        //
+        // Test-only helper, and this map is why: a commitment is NOT unique in the
+        // tree. Paying the same BTC deposit address twice for the same amount yields
+        // byte-identical commitments (complete_deposit hashes note_public_key,
+        // token_id and shielded_amount), so a second add overwrites the first and
+        // getMerkleProof then returns only the later leaf. Production never takes
+        // this path — announcements dedupe on leafIndex and proofs come from
+        // /api/tree/proof/:leaf_index — but do not promote this class to a wallet
+        // path without keying on leafIndex instead.
         const commitmentHex = commitment.toString(16).padStart(64, "0");
         this.commitments.set(commitmentHex, { index: leafIndex, amount });
         // Add to leaves array

package/dist/index.d.ts

@@ -43,7 +43,7 @@ export { formatSpendDoc, renderSpendDoc, SpendDocMismatch, type SpendDoc, type S
 export { getConfig, setConfig, createConfig, initConfig, DEVNET_CONFIG, DEVNET_REGTEST_CONFIG, MAINNET_CONFIG, LOCALNET_CONFIG, TOKEN_PROGRAM_ID, TOKEN_2022_PROGRAM_ID, ATA_PROGRAM_ID, UTXOPIA_POLICY_PROGRAM_ID, SDK_VERSION, DEPLOYMENT_INFO, JOINSPLIT_TREE_DEPTH, type NetworkConfig, type NetworkType, } from "./config";
 export { POOL_STATE_DISCRIMINATOR, POOL_STATE_LEN, POOL_STATE_OFFSETS, POOL_FLAG, parsePoolState, parsePoolFees, BPS_DENOMINATOR, computeBpsFee, feeShareBps, } from "./pool-state";
 export type { PoolState, PoolFees } from "./pool-state";
-export { PDA_SEEDS, poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifierRecordSeeds, redemptionRequestSeeds, vkRegistrySeeds, depositReceiptSeeds, policyApprovalSeeds, exitDestinationSeeds, lightClientSeeds, blockHeaderSeeds, heightIndexSeeds, verifiedTransactionSeeds, derivePoolStatePDA, deriveCommitmentTreePDA, deriveNullifierRecordPDA, derivePolicyApprovalPDA, deriveExitDestinationPDA, EXIT_KIND_SOLANA_OWNER, EXIT_KIND_BTC_SCRIPT, deriveLightClientPDA, deriveBlockHeaderPDA, deriveHeightIndexPDA, deriveVkRegistryPDA, deriveRedemptionRequestPDA, deriveTokenConfigPDA, derivePoolConfigPDA, deriveDepositReceiptPDA, commitmentToBytes, } from "./pda";
+export { PDA_SEEDS, poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifierRecordSeeds, redemptionRequestSeeds, vkRegistrySeeds, depositReceiptSeeds, policyApprovalSeeds, exitDestinationSeeds, lightClientSeeds, blockHeaderSeeds, heightIndexSeeds, verifiedTransactionSeeds, derivePoolStatePDA, deriveCommitmentTreePDA, deriveNullifierRecordPDA, deriveQueuedLeafPDA, queuedLeafSeeds, derivePolicyApprovalPDA, deriveExitDestinationPDA, EXIT_KIND_SOLANA_OWNER, EXIT_KIND_BTC_SCRIPT, deriveLightClientPDA, deriveBlockHeaderPDA, deriveHeightIndexPDA, deriveVkRegistryPDA, deriveRedemptionRequestPDA, deriveTokenConfigPDA, derivePoolConfigPDA, deriveDepositReceiptPDA, commitmentToBytes, } from "./pda";
 export { createStealthDeposit, createStealthDepositWithKeys, createStealthOutput, createStealthOutputWithKeys, createStealthOutputForCommitment, packStealthOutputForCircuit, scanAnnouncements, scanAnnouncementsViewOnly, scanAnnouncementsViewOnlyMulti, exportViewOnlyKeys, encodeViewOnlyKeys, decodeViewOnlyKeys, prepareClaimInputs, scanUnifiedNotes, scanUnifiedNotesMulti, encryptAmount, decryptAmount, computeNullifierHashForNote, computeNullifierBytes, parseAnnouncementsFromHex, createDepositFromConfig, createDirectVaultDeposit, createTweakDeposit, depositEphemeralKeyPair, depositViewingNode, outgoingViewingNode, outgoingEphemeralKeyPair, findNextSendIndex, isDepositForViewer, isDepositForViewerHex, ANNOUNCEMENT_TYPE_DEPOSIT, ANNOUNCEMENT_TYPE_TRANSFER, type StealthDeposit, type StealthOutputData, type StealthOutputWithKeys, type CircuitStealthOutput, type ScannedNote, type ClaimInputs as StealthClaimInputs, type OnChainStealthAnnouncement, type ConnectionAdapter, type ViewOnlyKeys, type ViewOnlyScannedNote, createNonInteractiveDeposit, pickIkaCustodyKey, type NonInteractiveDepositResult, type TweakDepositResult, type DepositRecoveryMaterial, type OutgoingRecoveryMaterial, type NonInteractiveDepositWithRefundResult, } from "./stealth";
 export { buildDepositPsbt, estimateDepositFee, fetchUtxos, selectUtxos, type BuildDepositPsbtParams, type BuildDepositPsbtResult, type UtxoDescriptor, } from "./psbt";
 export { EsploraClient, esploraTestnet, esploraMainnet, type EsploraTransaction, type EsploraVin, type EsploraVout, type EsploraStatus, type EsploraAddressInfo, type EsploraUtxo, type EsploraMerkleProof, type EsploraNetwork, } from "./core/esplora";
@@ -53,7 +53,7 @@ export { setDebug } from "./logger";
 export { createFetchConnectionAdapter, createConnectionAdapterFromWeb3, createConnectionAdapterFromKit, getConnectionAdapter, clearConnectionAdapterCache, type RpcConfig, type Web3Connection, type KitRpc, } from "./solana/connection";
 export { resolveSnsName, resolveStealthName, parseSnsStealthData, isSnsStealthAddress, isAuditorDisclosable, SnsComplianceFlags, SNS_COMPLIANCE_AUDITOR_OFFSET, SNS_COMPLIANCE_AUDITOR_BYTES, deriveParentDomainKey, SNS_STEALTH_DATA_SIZE, type SnsStealthAddress, } from "./sns-resolver";
 export { COMMITMENT_TREE_DISCRIMINATOR, parseCommitmentTreeData, isValidRoot, fetchCommitmentTree, getCommitmentIndex, saveCommitmentIndex, CommitmentTreeIndex, buildCommitmentTreeFromChain, fetchLeafIndexForCommitment, fetchMerkleProofForCommitment, getMerkleProofFromTree, type CommitmentTreeState, type RpcClient, type OnChainMerkleProof, } from "./commitment-tree";
-export { INSTRUCTION_DISCRIMINATORS, buildShieldInstructionData, buildShieldInstruction, type ShieldInstructionOptions, buildApproveRedemptionSigningInstructionData, buildApproveRedemptionSigningInstruction, buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, type CancelRedemptionInstructionOptions, bigintTo32Bytes, bytes32ToBigint, buildTransactInstructionData, buildTransactInstruction, buildRedeemInstructionData, buildUnshieldInstructionData, buildUnshieldInstruction, buildProposePoolUpdateInstructionData, buildProposePoolUpdateInstruction, buildExecutePoolUpdateInstructionData, buildExecutePoolUpdateInstruction, buildCancelPoolUpdateInstructionData, buildCancelPoolUpdateInstruction, buildRotateTreeInstructionData, buildRotateTreeInstruction, type RotateTreeOptions, buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, type MagicBlockDelegateTarget, type MagicBlockDelegateInstructionOptions, type MagicBlockCommitInstructionOptions, type MagicBlockPerPermissionOperation, type MagicBlockPerPermissionMember, type MagicBlockPerPermissionInstructionOptions, type PolicyApprovalDecision, type InitializePolicyApprovalOptions, type CompleteDepositPermissionedOptions, type ShieldPermissionedInstructionOptions, type RotateAuditorOptions, buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, buildVerifyDepositPermissionedInstructionData, buildSetPoolConfigInstructionData, parsePoolConfig, type ParsedPoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, type Instruction, type ApproveRedemptionSigningInstructionOptions, type TransactInstructionOptions, type UnshieldInstructionOptions, type ProposePoolUpdateOptions, type ExecutePoolUpdateOptions, type CancelPoolUpdateOptions, } from "./instructions";
+export { INSTRUCTION_DISCRIMINATORS, buildShieldInstructionData, buildShieldInstruction, type ShieldInstructionOptions, buildApproveRedemptionSigningInstructionData, buildApproveRedemptionSigningInstruction, buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, type CancelRedemptionInstructionOptions, bigintTo32Bytes, bytes32ToBigint, JSFLAGS, joinSplitFlags, buildMergeQueuedLeavesInstruction, MAX_MERGE_LEAVES, buildTransactInstructionData, buildTransactInstruction, buildRedeemInstructionData, buildUnshieldInstructionData, buildUnshieldInstruction, buildProposePoolUpdateInstructionData, buildProposePoolUpdateInstruction, buildExecutePoolUpdateInstructionData, buildExecutePoolUpdateInstruction, buildCancelPoolUpdateInstructionData, buildCancelPoolUpdateInstruction, buildRotateTreeInstructionData, buildRotateTreeInstruction, type RotateTreeOptions, buildMagicBlockDelegateInstructionData, buildMagicBlockDelegateInstruction, buildMagicBlockCommitInstructionData, buildMagicBlockCommitInstruction, buildMagicBlockPerPermissionInstructionData, buildMagicBlockPerPermissionInstruction, buildPolicyRequestHash, buildPolicyIntentParts, buildRegisterExitDestinationInstruction, buildRegisterExitDestinationInstructionData, MAX_POLICY_INTENT_PARTS, buildInitializePolicyApprovalInstructionData, buildInitializePolicyApprovalInstruction, buildPolicyApprovalDecisionInstruction, buildPolicyApprovalCommitInstruction, buildCompleteDepositPermissionedInstructionData, buildCompleteDepositPermissionedInstruction, buildShieldPermissionedInstructionData, buildShieldPermissionedInstruction, buildRotateAuditorInstructionData, buildRotateAuditorInstruction, type MagicBlockDelegateTarget, type JoinSplitTailOptions, type PolicyTailKind, type MagicBlockDelegateInstructionOptions, type MagicBlockCommitInstructionOptions, type MagicBlockPerPermissionOperation, type MagicBlockPerPermissionMember, type MagicBlockPerPermissionInstructionOptions, type PolicyApprovalDecision, type InitializePolicyApprovalOptions, type CompleteDepositPermissionedOptions, type ShieldPermissionedInstructionOptions, type RotateAuditorOptions, buildVerifyTransactionInstructionData, buildCompleteDepositInstructionData, buildVerifyDepositInstructionData, buildVerifyDepositPermissionedInstructionData, buildSetPoolConfigInstructionData, parsePoolConfig, type ParsedPoolConfig, POOL_CONFIG_DISCRIMINATOR, POOL_CONFIG_LEN, POOL_SCRIPT_MAX_LEN, type Instruction, type ApproveRedemptionSigningInstructionOptions, type TransactInstructionOptions, type UnshieldInstructionOptions, type ProposePoolUpdateOptions, type ExecutePoolUpdateOptions, type CancelPoolUpdateOptions, } from "./instructions";
 export { VK_REGISTRY_DISCRIMINATOR, VK_REGISTRY_LEN, MAX_IC_POINTS, MAX_SAFE_JOINSPLIT_SIZE, INIT_VK_REGISTRY_DISCRIMINATOR, UPDATE_VK_REGISTRY_DISCRIMINATOR, joinSplitNumPublicInputs, computeVkHash, vkeyJsonToVkMaterial, buildVkRegistryData, parseVkRegistry, assertVkRegistryForShape, assertVkeyMatchesRegistry, isVkRegistryReady, type JoinSplitVkMaterial, type SnarkjsVkeyJson, type ParsedVkRegistry, } from "./vk-registry";
 export { fetchExplorerDeposits, fetchExplorerTransfers, fetchExplorerRedemptions, parseNullifierRecord, parseRedemptionRequest, NULLIFIER_RECORD_SIZE, REDEMPTION_REQUEST_SIZE, NULLIFIER_RECORD_DISCRIMINATOR, REDEMPTION_REQUEST_DISCRIMINATOR, OPERATION_TYPE_LABELS, type ExplorerDeposit, type ExplorerTransferEvent, type ExplorerRedemption, type IndexerLeaf, } from "./explorer";
 export { parseProgramEvents, parseNullifierSpentEvent, parseStealthAnnouncementEvent, parseSenderMemoEvent, parseBtcOriginAttestationEvent, parseAuditorCiphertextEvent, EVENT_NULLIFIER_SPENT, EVENT_STEALTH_ANNOUNCEMENT, EVENT_NULLIFIERS_BATCH, EVENT_ANNOUNCEMENTS_BATCH, EVENT_SENDER_MEMO, EVENT_BTC_ORIGIN_ATTESTATION, EVENT_AUDITOR_CIPHERTEXT, type NullifierSpentEvent, type StealthAnnouncementEvent, type SenderMemoEvent, type BtcOriginAttestationEvent, type AuditorCiphertextEvent, type ProgramEvent, } from "./events";

package/dist/index.js

@@ -123,7 +123,7 @@ export { PDA_SEEDS,
 // Seed builders — the single definition of every PDA. Consumers on
 // @solana/web3.js should derive from these with findProgramAddressSync rather
 // than restating the seeds, which is how copies drift from the program.
-poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifierRecordSeeds, redemptionRequestSeeds, vkRegistrySeeds, depositReceiptSeeds, policyApprovalSeeds, exitDestinationSeeds, lightClientSeeds, blockHeaderSeeds, heightIndexSeeds, verifiedTransactionSeeds, derivePoolStatePDA, deriveCommitmentTreePDA, deriveNullifierRecordPDA, derivePolicyApprovalPDA, deriveExitDestinationPDA, EXIT_KIND_SOLANA_OWNER, EXIT_KIND_BTC_SCRIPT, deriveLightClientPDA, deriveBlockHeaderPDA, deriveHeightIndexPDA, deriveVkRegistryPDA, deriveRedemptionRequestPDA, deriveTokenConfigPDA, derivePoolConfigPDA, deriveDepositReceiptPDA, commitmentToBytes, } from "./pda";
+poolStateSeeds, commitmentTreeSeeds, tokenConfigSeeds, poolConfigSeeds, nullifierRecordSeeds, redemptionRequestSeeds, vkRegistrySeeds, depositReceiptSeeds, policyApprovalSeeds, exitDestinationSeeds, lightClientSeeds, blockHeaderSeeds, heightIndexSeeds, verifiedTransactionSeeds, derivePoolStatePDA, deriveCommitmentTreePDA, deriveNullifierRecordPDA, deriveQueuedLeafPDA, queuedLeafSeeds, derivePolicyApprovalPDA, deriveExitDestinationPDA, EXIT_KIND_SOLANA_OWNER, EXIT_KIND_BTC_SCRIPT, deriveLightClientPDA, deriveBlockHeaderPDA, deriveHeightIndexPDA, deriveVkRegistryPDA, deriveRedemptionRequestPDA, deriveTokenConfigPDA, derivePoolConfigPDA, deriveDepositReceiptPDA, commitmentToBytes, } from "./pda";
 // ==========================================================================
 // Stealth address utilities
 // ==========================================================================
@@ -169,7 +169,7 @@ buildShieldInstructionData, buildShieldInstruction, buildApproveRedemptionSignin
 // Cancel redemption instruction
 buildCancelRedemptionInstructionData, buildCancelRedemptionInstruction, bigintTo32Bytes, bytes32ToBigint, 
 // JoinSplit transact instruction
-buildTransactInstructionData, buildTransactInstruction, 
+JSFLAGS, joinSplitFlags, buildMergeQueuedLeavesInstruction, MAX_MERGE_LEAVES, buildTransactInstructionData, buildTransactInstruction, 
 // JoinSplit + BTC redeem instruction
 buildRedeemInstructionData, 
 // Public unshield instruction

package/dist/instructions.d.ts

@@ -46,6 +46,7 @@ export declare const INSTRUCTION_DISCRIMINATORS: {
     readonly APPROVE_REDEMPTION_SIGNING: 27;
     readonly SET_AUDITOR_FROZEN: 28;
     readonly SET_AUDITOR_VIEWING_PUBKEY: 29;
+    readonly MERGE_QUEUED_LEAVES: 40;
     readonly MAGICBLOCK_DELEGATE: 32;
     readonly MAGICBLOCK_COMMIT: 33;
     readonly MAGICBLOCK_PER_PERMISSION: 34;
@@ -280,6 +281,12 @@ export interface TransactInstructionOptions {
     accounts: {
         poolState: Address;
         commitmentTree: Address;
+        /**
+         * Supply one `QueuedLeaf` PDA per output to defer placement. Doing so also
+         * flips poolState and commitmentTree to read-only, which is what lets two
+         * spends run in the same slot.
+         */
+        queuedLeaves?: Address[];
         vkRegistry: Address;
         user: Address;
         /** Nullifier record PDAs (one per input) */
@@ -288,6 +295,50 @@ export interface TransactInstructionOptions {
         policyApproval?: Address;
     };
 }
+/**
+ * What a JoinSplit declares it is passing, mirroring `jsflags` on-chain.
+ *
+ * This byte used to be `proof_source`, valued 0 or 1. Bit 0 keeps that exact
+ * meaning so no instruction-data offset moved; the rest replaced the program's
+ * positional heuristics, which recovered the optional account tail by counting
+ * backwards from the end and by asking whether an account "looked like" a
+ * commitment tree or carried the policy program's id.
+ *
+ * A flag only says which slot to read. The program still validates owner,
+ * signer and seeds on every slot, so declaring the wrong thing breaks your own
+ * transaction rather than buying anything.
+ */
+export declare const JSFLAGS: {
+    readonly PROOF_IN_BUFFER: number;
+    readonly RELAYER: number;
+    readonly FROZEN_SOURCE_TREE: number;
+    readonly POLICY: number;
+    readonly QUEUED_LEAVES: number;
+    readonly RAGEQUIT: number;
+};
+/** Which permissioned tail a spend carries. */
+export type PolicyTailKind = "none" | "verified" | "ragequit";
+export interface JoinSplitTailOptions {
+    /** 0=inline proof (default), 1=proof in a separate ChadBuffer account */
+    proofSource?: 0 | 1;
+    /** A relayer signs and pays instead of the note owner. transact only. */
+    hasRelayer?: boolean;
+    /** A rotated-out CommitmentTree proves membership of pre-rotation notes. */
+    hasFrozenSourceTree?: boolean;
+    /**
+     * Permissioned tail. "verified" appends (approval, policyProgram);
+     * "ragequit" appends one registered ExitDestination per public output.
+     * Must match the pool: the program cross-checks against pool.permissioned().
+     */
+    policyTail?: PolicyTailKind;
+    /** Outputs are queued as QueuedLeaf PDAs instead of inserted inline. */
+    hasQueuedLeaves?: boolean;
+}
+/**
+ * Assemble the flags byte. Kept in one place so the data builders and the
+ * account builders cannot disagree about what was declared.
+ */
+export declare function joinSplitFlags(options: JoinSplitTailOptions): number;
 /**
  * Build transact instruction data (JoinSplit)
  *
@@ -313,11 +364,9 @@ export declare function buildTransactInstructionData(options: {
     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;
+} & JoinSplitTailOptions): Uint8Array;
 /**
  * Build a complete JoinSplit transact instruction
  *
@@ -368,9 +417,7 @@ export declare function buildRedeemInstructionData(options: {
     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;
+} & JoinSplitTailOptions): Uint8Array;
 /** Unshield instruction options (multi-output) */
 export interface UnshieldInstructionOptions {
     /** Number of input notes being spent */
@@ -439,9 +486,7 @@ export declare function buildUnshieldInstructionData(options: {
     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;
+} & JoinSplitTailOptions): Uint8Array;
 /**
  * Build a complete unshield instruction (multi-output, disc=14)
  *
@@ -572,7 +617,8 @@ export interface MagicBlockDelegateInstructionOptions {
     };
     target: MagicBlockDelegateTarget;
     commitFrequencyMs: number;
-    validator?: Address;
+    /** Required: the PER's TEE validator. An unpinned delegation is rejected on-chain. */
+    validator: Address;
 }
 export interface MagicBlockCommitInstructionOptions {
     accounts: {
@@ -613,7 +659,7 @@ export interface MagicBlockPerPermissionInstructionOptions {
 export declare function buildMagicBlockDelegateInstructionData(options: {
     target: MagicBlockDelegateTarget;
     commitFrequencyMs: number;
-    validator?: Address;
+    validator: Address;
 }): Uint8Array;
 /**
  * Build a complete magicblock_delegate instruction.
@@ -1097,3 +1143,35 @@ export interface RotateAuditorOptions {
 }
 export declare function buildRotateAuditorInstructionData(auditor: Uint8Array, viewingPubkey: Uint8Array): Uint8Array;
 export declare function buildRotateAuditorInstruction(options: RotateAuditorOptions): Instruction;
+export interface MergeQueuedLeavesOptions {
+    accounts: {
+        /** Pays the fee. A relayer, or the holder taking the escape hatch. */
+        caller: Address;
+        poolState: Address;
+        commitmentTree: Address;
+    };
+    /**
+     * The leaves to place, in the order they should land: leaf `i` gets
+     * `first_leaf_index + i`. Each needs the payer recorded in the account —
+     * rent goes there, never to the caller, so racing to merge earns nothing.
+     */
+    leaves: {
+        queuedLeaf: Address;
+        rentRecipient: Address;
+    }[];
+}
+/** Matches MAX_MERGE_LEAVES on-chain: two accounts per leaf under the 64-account cap. */
+export declare const MAX_MERGE_LEAVES = 24;
+/**
+ * Place queued commitments into the tree and close their accounts.
+ *
+ * Permissionless: anyone may call this, which is what makes a QueuedLeaf
+ * recoverable without a timeout — no operator can strand a note, because the
+ * holder can merge it themselves.
+ *
+ * Prefer having a relayer call it. Self-merging links a Solana identity to one
+ * specific leaf and the timing says the holder is in a hurry to spend it, so it
+ * is the escape hatch rather than the path. Merge cadence is a privacy
+ * parameter, not only a UX one.
+ */
+export declare function buildMergeQueuedLeavesInstruction(options: MergeQueuedLeavesOptions): Instruction;

package/dist/instructions.js

@@ -58,6 +58,7 @@ const INSTRUCTION = {
     SET_AUDITOR_FROZEN: 28,
     SET_AUDITOR_VIEWING_PUBKEY: 29,
     // MagicBlock ER/PER lifecycle helpers (32-33)
+    MERGE_QUEUED_LEAVES: 40,
     MAGICBLOCK_DELEGATE: 32,
     MAGICBLOCK_COMMIT: 33,
     MAGICBLOCK_PER_PERMISSION: 34,
@@ -381,6 +382,47 @@ export function buildCancelRedemptionInstruction(options) {
         data,
     };
 }
+/**
+ * What a JoinSplit declares it is passing, mirroring `jsflags` on-chain.
+ *
+ * This byte used to be `proof_source`, valued 0 or 1. Bit 0 keeps that exact
+ * meaning so no instruction-data offset moved; the rest replaced the program's
+ * positional heuristics, which recovered the optional account tail by counting
+ * backwards from the end and by asking whether an account "looked like" a
+ * commitment tree or carried the policy program's id.
+ *
+ * A flag only says which slot to read. The program still validates owner,
+ * signer and seeds on every slot, so declaring the wrong thing breaks your own
+ * transaction rather than buying anything.
+ */
+export const JSFLAGS = {
+    PROOF_IN_BUFFER: 1 << 0,
+    RELAYER: 1 << 1,
+    FROZEN_SOURCE_TREE: 1 << 2,
+    POLICY: 1 << 3,
+    QUEUED_LEAVES: 1 << 4,
+    RAGEQUIT: 1 << 5,
+};
+/**
+ * Assemble the flags byte. Kept in one place so the data builders and the
+ * account builders cannot disagree about what was declared.
+ */
+export function joinSplitFlags(options) {
+    let flags = 0;
+    if ((options.proofSource ?? 0) === 1)
+        flags |= JSFLAGS.PROOF_IN_BUFFER;
+    if (options.hasRelayer)
+        flags |= JSFLAGS.RELAYER;
+    if (options.hasFrozenSourceTree)
+        flags |= JSFLAGS.FROZEN_SOURCE_TREE;
+    if (options.policyTail === "verified")
+        flags |= JSFLAGS.POLICY;
+    if (options.policyTail === "ragequit")
+        flags |= JSFLAGS.RAGEQUIT;
+    if (options.hasQueuedLeaves)
+        flags |= JSFLAGS.QUEUED_LEAVES;
+    return flags;
+}
 /**
  * Build transact instruction data (JoinSplit)
  *
@@ -425,7 +467,7 @@ export function buildTransactInstructionData(options) {
     data[offset++] = nInputs;
     data[offset++] = nOutputs;
     data[offset++] = 0; // n_public_outputs = 0 for transact
-    data[offset++] = proofSource;
+    data[offset++] = joinSplitFlags(options);
     // Proof (256 bytes, only in inline mode)
     if (proofSource === 0 && proofBytes) {
         data.set(proofBytes, offset);
@@ -467,6 +509,11 @@ export function buildTransactInstructionData(options) {
  */
 export function buildTransactInstruction(options) {
     const config = getConfig();
+    const queuedLeaves = options.accounts.queuedLeaves ?? [];
+    const queued = queuedLeaves.length > 0;
+    if (queued && queuedLeaves.length !== options.nOutputs) {
+        throw new Error(`Queued placement needs one QueuedLeaf PDA per output: expected ${options.nOutputs}, got ${queuedLeaves.length}`);
+    }
     const data = buildTransactInstructionData({
         nInputs: options.nInputs,
         nOutputs: options.nOutputs,
@@ -477,10 +524,21 @@ export function buildTransactInstruction(options) {
         commitmentsOut: options.commitmentsOut,
         stealthData: options.stealthData,
         senderMemos: options.senderMemos,
+        // The account list below appends the policy pair exactly when the caller
+        // supplies an approval, so the declared tail is derived from the same fact
+        // rather than asked for twice.
+        policyTail: options.accounts.policyApproval ? "verified" : "none",
+        hasQueuedLeaves: queued,
     });
+    // A queued spend writes neither shared account — the tree is read for
+    // is_valid_root, pool_state for its policy flags — and the program REJECTS
+    // them as writable. Sealevel serialises on the declared metas, not on what
+    // the program does, so leaving them writable would take both locks and
+    // silently cost the parallelism the queue exists for.
+    const sharedRole = queued ? AccountRole.READONLY : AccountRole.WRITABLE;
     const accounts = [
-        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
-        { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+        { address: options.accounts.poolState, role: sharedRole },
+        { address: options.accounts.commitmentTree, role: sharedRole },
         { address: options.accounts.vkRegistry, role: AccountRole.READONLY },
         { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
         { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
@@ -496,6 +554,11 @@ export function buildTransactInstruction(options) {
             role: AccountRole.READONLY,
         });
     }
+    // Order matches resolve_joinsplit_tail: relayer, source tree, policy, queued
+    // leaves, proof buffer. One PDA per output, in output order.
+    for (const leaf of queuedLeaves) {
+        accounts.push({ address: leaf, role: AccountRole.WRITABLE });
+    }
     return {
         programAddress: config.utxopiaProgramId,
         accounts,
@@ -578,7 +641,7 @@ export function buildRedeemInstructionData(options) {
     data[offset++] = nInputs;
     data[offset++] = nOutputs;
     data[offset++] = nPublicOutputs;
-    data[offset++] = proofSource;
+    data[offset++] = joinSplitFlags(options);
     // Proof (256 bytes, only in inline mode)
     if (proofSource === 0 && proofBytes) {
         data.set(proofBytes, offset);
@@ -669,7 +732,7 @@ export function buildUnshieldInstructionData(options) {
     data[offset++] = nInputs;
     data[offset++] = nOutputs;
     data[offset++] = nPublicOutputs;
-    data[offset++] = proofSource;
+    data[offset++] = joinSplitFlags(options);
     // Proof (256 bytes, only in inline mode)
     if (proofSource === 0 && proofBytes) {
         data.set(proofBytes, offset);
@@ -898,14 +961,12 @@ export function buildMagicBlockDelegateInstructionData(options) {
     if (options.commitFrequencyMs > 0xffffffff) {
         throw new Error("commitFrequencyMs must fit in u32");
     }
-    const data = new Uint8Array(options.validator ? 38 : 6);
+    const data = new Uint8Array(38);
     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);
-    }
+    data.set(addressToBytes(options.validator), 6);
     return data;
 }
 /**
@@ -1732,3 +1793,50 @@ export function buildRotateAuditorInstruction(options) {
         data: buildRotateAuditorInstructionData(options.auditor, options.viewingPubkey),
     };
 }
+/** Matches MAX_MERGE_LEAVES on-chain: two accounts per leaf under the 64-account cap. */
+export const MAX_MERGE_LEAVES = 24;
+/**
+ * Place queued commitments into the tree and close their accounts.
+ *
+ * Permissionless: anyone may call this, which is what makes a QueuedLeaf
+ * recoverable without a timeout — no operator can strand a note, because the
+ * holder can merge it themselves.
+ *
+ * Prefer having a relayer call it. Self-merging links a Solana identity to one
+ * specific leaf and the timing says the holder is in a hurry to spend it, so it
+ * is the escape hatch rather than the path. Merge cadence is a privacy
+ * parameter, not only a UX one.
+ */
+export function buildMergeQueuedLeavesInstruction(options) {
+    const config = getConfig();
+    if (options.leaves.length === 0) {
+        throw new Error("merge_queued_leaves needs at least one leaf");
+    }
+    if (options.leaves.length > MAX_MERGE_LEAVES) {
+        throw new Error(`merge_queued_leaves takes at most ${MAX_MERGE_LEAVES} leaves, got ${options.leaves.length}`);
+    }
+    // Duplicates would insert one commitment at two leaf indices, and nullifiers
+    // are derived from (key, leaf index) — the program refuses it, but catching it
+    // here names the problem instead of surfacing NullifierAlreadyUsed.
+    const seen = new Set();
+    for (const { queuedLeaf } of options.leaves) {
+        if (seen.has(queuedLeaf)) {
+            throw new Error(`Duplicate queued leaf in one merge: ${queuedLeaf}`);
+        }
+        seen.add(queuedLeaf);
+    }
+    const accounts = [
+        { address: options.accounts.caller, role: AccountRole.WRITABLE_SIGNER },
+        { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+        { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+    ];
+    for (const { queuedLeaf, rentRecipient } of options.leaves) {
+        accounts.push({ address: queuedLeaf, role: AccountRole.WRITABLE });
+        accounts.push({ address: rentRecipient, role: AccountRole.WRITABLE });
+    }
+    return {
+        programAddress: config.utxopiaProgramId,
+        accounts,
+        data: Uint8Array.of(INSTRUCTION.MERGE_QUEUED_LEAVES),
+    };
+}

package/dist/pda.d.ts

@@ -21,6 +21,7 @@ export declare const PDA_SEEDS: {
     readonly VK_REGISTRY: "vk_registry";
     readonly TOKEN_CONFIG: "token_config";
     readonly POOL_CONFIG: "pool_config";
+    readonly QUEUED_LEAF: "queued_leaf";
 };
 /** `["pool_state", pool_id]` — pool_id is the pool's zkBTC mint. */
 export declare function poolStateSeeds(poolId: Address | Uint8Array): Uint8Array[];
@@ -92,6 +93,18 @@ export declare function derivePoolConfigPDA(poolState: Address | Uint8Array, pro
  * — re-deriving them would make every already-spent note spendable again.
  */
 export declare function deriveNullifierRecordPDA(nullifierHash: Uint8Array, poolState: Address | Uint8Array, treeIndex?: number, programId?: Address): Promise<[Address, number]>;
+/**
+ * Seeds for a `QueuedLeaf`: `["queued_leaf", pool_state, commitment]`.
+ *
+ * The commitment is the seed because it is already unique per output — which
+ * makes a second attempt to queue the same commitment fail on account creation
+ * rather than silently produce a second leaf for one note.
+ */
+export declare function queuedLeafSeeds(poolState: Address | Uint8Array, commitment: Uint8Array): Uint8Array[];
+/**
+ * Derive the `QueuedLeaf` PDA a queued spend creates for one output.
+ */
+export declare function deriveQueuedLeafPDA(poolState: Address | Uint8Array, commitment: Uint8Array, programId?: Address): Promise<[Address, number]>;
 /**
  * Derive one-time PolicyApproval PDA.
  * Seeds: ["policy_approval", pool_state, request_hash, nonce]

package/dist/pda.js

@@ -33,6 +33,7 @@ export const PDA_SEEDS = {
     VK_REGISTRY: "vk_registry",
     TOKEN_CONFIG: "token_config",
     POOL_CONFIG: "pool_config",
+    QUEUED_LEAF: "queued_leaf",
 };
 // =============================================================================
 // Seed builders — the single definition of every program-derived address
@@ -240,6 +241,30 @@ export async function deriveNullifierRecordPDA(nullifierHash, poolState, treeInd
     });
     return [result[0], result[1]];
 }
+/**
+ * Seeds for a `QueuedLeaf`: `["queued_leaf", pool_state, commitment]`.
+ *
+ * The commitment is the seed because it is already unique per output — which
+ * makes a second attempt to queue the same commitment fail on account creation
+ * rather than silently produce a second leaf for one note.
+ */
+export function queuedLeafSeeds(poolState, commitment) {
+    return [
+        enc(PDA_SEEDS.QUEUED_LEAF),
+        seedBytes(poolState, "poolState"),
+        seedBytes(commitment, "commitment"),
+    ];
+}
+/**
+ * Derive the `QueuedLeaf` PDA a queued spend creates for one output.
+ */
+export async function deriveQueuedLeafPDA(poolState, commitment, programId = UTXOPIA_PROGRAM_ID) {
+    const result = await getProgramDerivedAddress({
+        programAddress: programId,
+        seeds: queuedLeafSeeds(poolState, commitment),
+    });
+    return [result[0], result[1]];
+}
 /**
  * Derive one-time PolicyApproval PDA.
  * Seeds: ["policy_approval", pool_state, request_hash, nonce]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utxopia/sdk",
-  "version": "0.1.0-alpha.7",
+  "version": "0.1.0-alpha.8",
   "description": "UTXOpia SDK - Private Bitcoin across Solana and Sui",
   "type": "module",
   "main": "dist/index.js",

package/src/commitment-tree.ts

@@ -230,7 +230,16 @@ export class CommitmentTreeIndex {
       throw new Error("Tree is full");
     }
 
-    // Store in map for lookup
+    // Store in map for lookup.
+    //
+    // Test-only helper, and this map is why: a commitment is NOT unique in the
+    // tree. Paying the same BTC deposit address twice for the same amount yields
+    // byte-identical commitments (complete_deposit hashes note_public_key,
+    // token_id and shielded_amount), so a second add overwrites the first and
+    // getMerkleProof then returns only the later leaf. Production never takes
+    // this path — announcements dedupe on leafIndex and proofs come from
+    // /api/tree/proof/:leaf_index — but do not promote this class to a wallet
+    // path without keying on leafIndex instead.
     const commitmentHex = commitment.toString(16).padStart(64, "0");
     this.commitments.set(commitmentHex, { index: leafIndex, amount });
 

package/src/index.ts

@@ -504,6 +504,8 @@ export {
   derivePoolStatePDA,
   deriveCommitmentTreePDA,
   deriveNullifierRecordPDA,
+  deriveQueuedLeafPDA,
+  queuedLeafSeeds,
   derivePolicyApprovalPDA,
   deriveExitDestinationPDA,
   EXIT_KIND_SOLANA_OWNER,
@@ -717,6 +719,10 @@ export {
   bigintTo32Bytes,
   bytes32ToBigint,
   // JoinSplit transact instruction
+  JSFLAGS,
+  joinSplitFlags,
+  buildMergeQueuedLeavesInstruction,
+  MAX_MERGE_LEAVES,
   buildTransactInstructionData,
   buildTransactInstruction,
   // JoinSplit + BTC redeem instruction
@@ -758,6 +764,8 @@ export {
   buildRotateAuditorInstructionData,
   buildRotateAuditorInstruction,
   type MagicBlockDelegateTarget,
+  type JoinSplitTailOptions,
+  type PolicyTailKind,
   type MagicBlockDelegateInstructionOptions,
   type MagicBlockCommitInstructionOptions,
   type MagicBlockPerPermissionOperation,

package/src/instructions.ts

@@ -85,6 +85,7 @@ const INSTRUCTION = {
   SET_AUDITOR_FROZEN: 28,
   SET_AUDITOR_VIEWING_PUBKEY: 29,
   // MagicBlock ER/PER lifecycle helpers (32-33)
+  MERGE_QUEUED_LEAVES: 40,
   MAGICBLOCK_DELEGATE: 32,
   MAGICBLOCK_COMMIT: 33,
   MAGICBLOCK_PER_PERMISSION: 34,
@@ -619,6 +620,12 @@ export interface TransactInstructionOptions {
   accounts: {
     poolState: Address;
     commitmentTree: Address;
+    /**
+     * Supply one `QueuedLeaf` PDA per output to defer placement. Doing so also
+     * flips poolState and commitmentTree to read-only, which is what lets two
+     * spends run in the same slot.
+     */
+    queuedLeaves?: Address[];
     vkRegistry: Address;
     user: Address;
     /** Nullifier record PDAs (one per input) */
@@ -628,6 +635,63 @@ export interface TransactInstructionOptions {
   };
 }
 
+/**
+ * What a JoinSplit declares it is passing, mirroring `jsflags` on-chain.
+ *
+ * This byte used to be `proof_source`, valued 0 or 1. Bit 0 keeps that exact
+ * meaning so no instruction-data offset moved; the rest replaced the program's
+ * positional heuristics, which recovered the optional account tail by counting
+ * backwards from the end and by asking whether an account "looked like" a
+ * commitment tree or carried the policy program's id.
+ *
+ * A flag only says which slot to read. The program still validates owner,
+ * signer and seeds on every slot, so declaring the wrong thing breaks your own
+ * transaction rather than buying anything.
+ */
+export const JSFLAGS = {
+  PROOF_IN_BUFFER: 1 << 0,
+  RELAYER: 1 << 1,
+  FROZEN_SOURCE_TREE: 1 << 2,
+  POLICY: 1 << 3,
+  QUEUED_LEAVES: 1 << 4,
+  RAGEQUIT: 1 << 5,
+} as const;
+
+/** Which permissioned tail a spend carries. */
+export type PolicyTailKind = "none" | "verified" | "ragequit";
+
+export interface JoinSplitTailOptions {
+  /** 0=inline proof (default), 1=proof in a separate ChadBuffer account */
+  proofSource?: 0 | 1;
+  /** A relayer signs and pays instead of the note owner. transact only. */
+  hasRelayer?: boolean;
+  /** A rotated-out CommitmentTree proves membership of pre-rotation notes. */
+  hasFrozenSourceTree?: boolean;
+  /**
+   * Permissioned tail. "verified" appends (approval, policyProgram);
+   * "ragequit" appends one registered ExitDestination per public output.
+   * Must match the pool: the program cross-checks against pool.permissioned().
+   */
+  policyTail?: PolicyTailKind;
+  /** Outputs are queued as QueuedLeaf PDAs instead of inserted inline. */
+  hasQueuedLeaves?: boolean;
+}
+
+/**
+ * Assemble the flags byte. Kept in one place so the data builders and the
+ * account builders cannot disagree about what was declared.
+ */
+export function joinSplitFlags(options: JoinSplitTailOptions): number {
+  let flags = 0;
+  if ((options.proofSource ?? 0) === 1) flags |= JSFLAGS.PROOF_IN_BUFFER;
+  if (options.hasRelayer) flags |= JSFLAGS.RELAYER;
+  if (options.hasFrozenSourceTree) flags |= JSFLAGS.FROZEN_SOURCE_TREE;
+  if (options.policyTail === "verified") flags |= JSFLAGS.POLICY;
+  if (options.policyTail === "ragequit") flags |= JSFLAGS.RAGEQUIT;
+  if (options.hasQueuedLeaves) flags |= JSFLAGS.QUEUED_LEAVES;
+  return flags;
+}
+
 /**
  * Build transact instruction data (JoinSplit)
  *
@@ -653,11 +717,9 @@ export function buildTransactInstructionData(options: {
   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 {
+} & JoinSplitTailOptions): Uint8Array {
   const { nInputs, nOutputs, proofBytes, merkleRoot, boundParamsHash, nullifiers, commitmentsOut, stealthData, senderMemos } = options;
   const proofSource = options.proofSource ?? 0;
 
@@ -693,7 +755,7 @@ export function buildTransactInstructionData(options: {
   data[offset++] = nInputs;
   data[offset++] = nOutputs;
   data[offset++] = 0; // n_public_outputs = 0 for transact
-  data[offset++] = proofSource;
+  data[offset++] = joinSplitFlags(options);
 
   // Proof (256 bytes, only in inline mode)
   if (proofSource === 0 && proofBytes) {
@@ -743,6 +805,13 @@ export function buildTransactInstructionData(options: {
  */
 export function buildTransactInstruction(options: TransactInstructionOptions): Instruction {
   const config = getConfig();
+  const queuedLeaves = options.accounts.queuedLeaves ?? [];
+  const queued = queuedLeaves.length > 0;
+  if (queued && queuedLeaves.length !== options.nOutputs) {
+    throw new Error(
+      `Queued placement needs one QueuedLeaf PDA per output: expected ${options.nOutputs}, got ${queuedLeaves.length}`
+    );
+  }
 
   const data = buildTransactInstructionData({
     nInputs: options.nInputs,
@@ -754,11 +823,23 @@ export function buildTransactInstruction(options: TransactInstructionOptions): I
     commitmentsOut: options.commitmentsOut,
     stealthData: options.stealthData,
     senderMemos: options.senderMemos,
+    // The account list below appends the policy pair exactly when the caller
+    // supplies an approval, so the declared tail is derived from the same fact
+    // rather than asked for twice.
+    policyTail: options.accounts.policyApproval ? "verified" : "none",
+    hasQueuedLeaves: queued,
   });
 
+  // A queued spend writes neither shared account — the tree is read for
+  // is_valid_root, pool_state for its policy flags — and the program REJECTS
+  // them as writable. Sealevel serialises on the declared metas, not on what
+  // the program does, so leaving them writable would take both locks and
+  // silently cost the parallelism the queue exists for.
+  const sharedRole = queued ? AccountRole.READONLY : AccountRole.WRITABLE;
+
   const accounts: Instruction["accounts"] = [
-    { address: options.accounts.poolState, role: AccountRole.WRITABLE },
-    { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+    { address: options.accounts.poolState, role: sharedRole },
+    { address: options.accounts.commitmentTree, role: sharedRole },
     { address: options.accounts.vkRegistry, role: AccountRole.READONLY },
     { address: options.accounts.user, role: AccountRole.WRITABLE_SIGNER },
     { address: SYSTEM_PROGRAM_ADDRESS, role: AccountRole.READONLY },
@@ -775,6 +856,11 @@ export function buildTransactInstruction(options: TransactInstructionOptions): I
       role: AccountRole.READONLY,
     });
   }
+  // Order matches resolve_joinsplit_tail: relayer, source tree, policy, queued
+  // leaves, proof buffer. One PDA per output, in output order.
+  for (const leaf of queuedLeaves) {
+    accounts.push({ address: leaf, role: AccountRole.WRITABLE });
+  }
 
   return {
     programAddress: config.utxopiaProgramId,
@@ -826,8 +912,7 @@ export function buildRedeemInstructionData(options: {
   /** Unique request nonce(s) — single or array */
   requestNonces: bigint[];
   /** 0=inline proof (default), 1=proof in separate ChadBuffer account */
-  proofSource?: 0 | 1;
-}): Uint8Array {
+} & JoinSplitTailOptions): Uint8Array {
   const {
     nInputs, nOutputs, proofBytes, merkleRoot, boundParamsHash,
     nullifiers, commitmentsOut, stealthData, redeemAmounts, btcScripts, requestNonces,
@@ -888,7 +973,7 @@ export function buildRedeemInstructionData(options: {
   data[offset++] = nInputs;
   data[offset++] = nOutputs;
   data[offset++] = nPublicOutputs;
-  data[offset++] = proofSource;
+  data[offset++] = joinSplitFlags(options);
 
   // Proof (256 bytes, only in inline mode)
   if (proofSource === 0 && proofBytes) {
@@ -1010,8 +1095,7 @@ export function buildUnshieldInstructionData(options: {
   /** Amount(s) being unshielded — single or array */
   unshieldAmounts: bigint[];
   /** 0=inline proof (default), 1=proof in separate ChadBuffer account */
-  proofSource?: 0 | 1;
-}): Uint8Array {
+} & JoinSplitTailOptions): Uint8Array {
   const { nInputs, nOutputs, proofBytes, merkleRoot, boundParamsHash, nullifiers, commitmentsOut, stealthData, unshieldAmounts } = options;
   const nPublicOutputs = options.nPublicOutputs ?? unshieldAmounts.length;
   const proofSource = options.proofSource ?? 0;
@@ -1054,7 +1138,7 @@ export function buildUnshieldInstructionData(options: {
   data[offset++] = nInputs;
   data[offset++] = nOutputs;
   data[offset++] = nPublicOutputs;
-  data[offset++] = proofSource;
+  data[offset++] = joinSplitFlags(options);
 
   // Proof (256 bytes, only in inline mode)
   if (proofSource === 0 && proofBytes) {
@@ -1380,7 +1464,8 @@ export interface MagicBlockDelegateInstructionOptions {
   };
   target: MagicBlockDelegateTarget;
   commitFrequencyMs: number;
-  validator?: Address;
+  /** Required: the PER's TEE validator. An unpinned delegation is rejected on-chain. */
+  validator: Address;
 }
 
 export interface MagicBlockCommitInstructionOptions {
@@ -1431,7 +1516,7 @@ function magicBlockDelegateTargetByte(target: MagicBlockDelegateTarget): number
 export function buildMagicBlockDelegateInstructionData(options: {
   target: MagicBlockDelegateTarget;
   commitFrequencyMs: number;
-  validator?: Address;
+  validator: Address;
 }): Uint8Array {
   if (!Number.isInteger(options.commitFrequencyMs) || options.commitFrequencyMs < 0) {
     throw new Error("commitFrequencyMs must be a non-negative u32");
@@ -1440,14 +1525,12 @@ export function buildMagicBlockDelegateInstructionData(options: {
     throw new Error("commitFrequencyMs must fit in u32");
   }
 
-  const data = new Uint8Array(options.validator ? 38 : 6);
+  const data = new Uint8Array(38);
   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);
-  }
+  data.set(addressToBytes(options.validator), 6);
   return data;
 }
 
@@ -2604,3 +2687,77 @@ export function buildRotateAuditorInstruction(options: RotateAuditorOptions): In
     data: buildRotateAuditorInstructionData(options.auditor, options.viewingPubkey),
   };
 }
+
+// =============================================================================
+// merge_queued_leaves (disc=40)
+// =============================================================================
+
+export interface MergeQueuedLeavesOptions {
+  accounts: {
+    /** Pays the fee. A relayer, or the holder taking the escape hatch. */
+    caller: Address;
+    poolState: Address;
+    commitmentTree: Address;
+  };
+  /**
+   * The leaves to place, in the order they should land: leaf `i` gets
+   * `first_leaf_index + i`. Each needs the payer recorded in the account —
+   * rent goes there, never to the caller, so racing to merge earns nothing.
+   */
+  leaves: { queuedLeaf: Address; rentRecipient: Address }[];
+}
+
+/** Matches MAX_MERGE_LEAVES on-chain: two accounts per leaf under the 64-account cap. */
+export const MAX_MERGE_LEAVES = 24;
+
+/**
+ * Place queued commitments into the tree and close their accounts.
+ *
+ * Permissionless: anyone may call this, which is what makes a QueuedLeaf
+ * recoverable without a timeout — no operator can strand a note, because the
+ * holder can merge it themselves.
+ *
+ * Prefer having a relayer call it. Self-merging links a Solana identity to one
+ * specific leaf and the timing says the holder is in a hurry to spend it, so it
+ * is the escape hatch rather than the path. Merge cadence is a privacy
+ * parameter, not only a UX one.
+ */
+export function buildMergeQueuedLeavesInstruction(
+  options: MergeQueuedLeavesOptions
+): Instruction {
+  const config = getConfig();
+  if (options.leaves.length === 0) {
+    throw new Error("merge_queued_leaves needs at least one leaf");
+  }
+  if (options.leaves.length > MAX_MERGE_LEAVES) {
+    throw new Error(
+      `merge_queued_leaves takes at most ${MAX_MERGE_LEAVES} leaves, got ${options.leaves.length}`
+    );
+  }
+  // Duplicates would insert one commitment at two leaf indices, and nullifiers
+  // are derived from (key, leaf index) — the program refuses it, but catching it
+  // here names the problem instead of surfacing NullifierAlreadyUsed.
+  const seen = new Set<string>();
+  for (const { queuedLeaf } of options.leaves) {
+    if (seen.has(queuedLeaf)) {
+      throw new Error(`Duplicate queued leaf in one merge: ${queuedLeaf}`);
+    }
+    seen.add(queuedLeaf);
+  }
+
+  const accounts: Instruction["accounts"] = [
+    { address: options.accounts.caller, role: AccountRole.WRITABLE_SIGNER },
+    { address: options.accounts.poolState, role: AccountRole.WRITABLE },
+    { address: options.accounts.commitmentTree, role: AccountRole.WRITABLE },
+  ];
+  for (const { queuedLeaf, rentRecipient } of options.leaves) {
+    accounts.push({ address: queuedLeaf, role: AccountRole.WRITABLE });
+    accounts.push({ address: rentRecipient, role: AccountRole.WRITABLE });
+  }
+
+  return {
+    programAddress: config.utxopiaProgramId,
+    accounts,
+    data: Uint8Array.of(INSTRUCTION.MERGE_QUEUED_LEAVES),
+  };
+}

package/src/pda.ts

@@ -46,6 +46,7 @@ export const PDA_SEEDS = {
   VK_REGISTRY: "vk_registry",
   TOKEN_CONFIG: "token_config",
   POOL_CONFIG: "pool_config",
+  QUEUED_LEAF: "queued_leaf",
 } as const;
 
 // =============================================================================
@@ -322,6 +323,39 @@ export async function deriveNullifierRecordPDA(
   return [result[0], result[1]];
 }
 
+/**
+ * Seeds for a `QueuedLeaf`: `["queued_leaf", pool_state, commitment]`.
+ *
+ * The commitment is the seed because it is already unique per output — which
+ * makes a second attempt to queue the same commitment fail on account creation
+ * rather than silently produce a second leaf for one note.
+ */
+export function queuedLeafSeeds(
+  poolState: Address | Uint8Array,
+  commitment: Uint8Array
+): Uint8Array[] {
+  return [
+    enc(PDA_SEEDS.QUEUED_LEAF),
+    seedBytes(poolState, "poolState"),
+    seedBytes(commitment, "commitment"),
+  ];
+}
+
+/**
+ * Derive the `QueuedLeaf` PDA a queued spend creates for one output.
+ */
+export async function deriveQueuedLeafPDA(
+  poolState: Address | Uint8Array,
+  commitment: Uint8Array,
+  programId: Address = UTXOPIA_PROGRAM_ID
+): Promise<[Address, number]> {
+  const result = await getProgramDerivedAddress({
+    programAddress: programId,
+    seeds: queuedLeafSeeds(poolState, commitment),
+  });
+  return [result[0], result[1]];
+}
+
 /**
  * Derive one-time PolicyApproval PDA.
  * Seeds: ["policy_approval", pool_state, request_hash, nonce]