@utxopia/sdk 0.1.0-alpha.2 → 0.1.0-alpha.3

package/{packages/sdk/dist → dist}/instructions.d.ts

@@ -33,7 +33,7 @@ export declare const INSTRUCTION_DISCRIMINATORS: {
     readonly COMPLETE_DEPOSIT: 11;
     readonly SHIELD: 12;
     /** OP_RETURN-free deposit: note keys ride in instruction data, proven by the
-     *  deposit address's Taproot tweak. */
+     *  deposit address's tapleaf. */
     readonly VERIFY_DEPOSIT: 25;
     readonly TRANSACT: 13;
     readonly UNSHIELD: 14;
@@ -762,16 +762,19 @@ export declare function buildCompleteDepositInstructionData(params: {
  *
  * The OP_RETURN-free deposit path. `notePublicKey` + `ephemeralPubkey` travel in
  * instruction data instead of in the Bitcoin transaction, and the program proves
- * them against the deposit output's Taproot tweak — a different key pair derives
- * a different address, which the funding transaction did not pay. Nothing marks
- * the deposit as a UTXOpia transaction on chain, so any wallet or exchange that
- * can send to a P2TR address can fund it.
+ * them against the deposit output's tapleaf — a different key pair derives a
+ * different leaf, and so a different address, which the funding transaction did
+ * not pay. Nothing marks the deposit as a UTXOpia transaction on chain, so any
+ * wallet or exchange that can send to a P2TR address can fund it.
  *
- * The address must be derived from `depositTweakCommitment(npk, eph)`, NOT from
- * the note key alone — the program hashes both, so that a caller cannot swap in
- * an ephemeral key that leaves the note undiscoverable.
+ * Derive the address with `deriveDepositAddress(depositTweakCommitment(npk, eph),
+ * ikaXOnlyPubkey)`. Both keys are hashed into the leaf, so a caller cannot swap
+ * in an ephemeral key that leaves the note undiscoverable.
  *
- * Sweep mode only: `depositTxSize` must be non-zero. The receipt PDA is seeded
+ * No sweep: the deposit output's tapleaf names the pool's own dWallet key, so it
+ * is already under pool custody and is recorded as a pool UTXO directly. The
+ * SPV-verified transaction must therefore BE the deposit — `depositTxSize` is 0
+ * and `depositTxid` defaults to `sweepTxid`. The receipt PDA is seeded
  * `["deposit_receipt", txid, vout]`, so pass `depositVout` to
  * `deriveDepositReceiptPDA` for this flow.
  *
@@ -783,12 +786,26 @@ export declare function buildVerifyDepositInstructionData(params: {
     sweepTxid: Uint8Array;
     blockHeight: number;
     sweepTxSize: number;
-    depositTxSize: number;
-    depositTxid: Uint8Array;
+    depositTxSize?: number;
+    depositTxid?: Uint8Array;
     ephemeralPubkey: Uint8Array;
     notePublicKey: Uint8Array;
     depositVout: number;
 }): Uint8Array;
+/**
+ * Build utxopia verify_deposit_permissioned instruction data (disc=26).
+ *
+ * `buildVerifyDepositInstructionData`'s payload with a different discriminator
+ * and an auditor ciphertext appended. The tapleaf already tells the pools apart —
+ * each carries its own Ika custody key — but that is not the same as clearing the
+ * pool's policy, which is what a permissioned pool exists for.
+ *
+ * The one-time PolicyApproval is bound to the WHOLE payload, ciphertext included,
+ * so these exact bytes must be the ones approved.
+ */
+export declare function buildVerifyDepositPermissionedInstructionData(params: Parameters<typeof buildVerifyDepositInstructionData>[0] & {
+    auditorCiphertext?: Uint8Array;
+}): Uint8Array;
 /** PoolConfig account discriminator (0x0a) */
 export declare const POOL_CONFIG_DISCRIMINATOR = 10;
 /** Serialized PoolConfig account length (bytes) */

package/{packages/sdk/dist → dist}/instructions.js

@@ -8,6 +8,7 @@
  */
 import { AccountRole, } from "@solana/kit";
 import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex as toHex } from "./crypto";
 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";
@@ -37,7 +38,7 @@ const INSTRUCTION = {
     COMPLETE_DEPOSIT: 11,
     SHIELD: 12,
     /** OP_RETURN-free deposit: note keys ride in instruction data, proven by the
-     *  deposit address's Taproot tweak. */
+     *  deposit address's tapleaf. */
     VERIFY_DEPOSIT: 25,
     // JoinSplit (13-15) — all share n_in + n_out + n_pub + proof_source header
     TRANSACT: 13,
@@ -72,6 +73,8 @@ const INSTRUCTION = {
 const PERMISSIONED_DISC = {
     INITIALIZE_PERMISSIONED: 21,
     COMPLETE_DEPOSIT_PERMISSIONED: 22,
+    /** Same binding as VERIFY_DEPOSIT, plus the permissioned pool's policy gate. */
+    VERIFY_DEPOSIT_PERMISSIONED: 26,
     SHIELD_PERMISSIONED: 23,
     REGISTER_EXIT_DESTINATION: 39,
 };
@@ -1311,16 +1314,19 @@ export function buildCompleteDepositInstructionData(params) {
  *
  * The OP_RETURN-free deposit path. `notePublicKey` + `ephemeralPubkey` travel in
  * instruction data instead of in the Bitcoin transaction, and the program proves
- * them against the deposit output's Taproot tweak — a different key pair derives
- * a different address, which the funding transaction did not pay. Nothing marks
- * the deposit as a UTXOpia transaction on chain, so any wallet or exchange that
- * can send to a P2TR address can fund it.
+ * them against the deposit output's tapleaf — a different key pair derives a
+ * different leaf, and so a different address, which the funding transaction did
+ * not pay. Nothing marks the deposit as a UTXOpia transaction on chain, so any
+ * wallet or exchange that can send to a P2TR address can fund it.
  *
- * The address must be derived from `depositTweakCommitment(npk, eph)`, NOT from
- * the note key alone — the program hashes both, so that a caller cannot swap in
- * an ephemeral key that leaves the note undiscoverable.
+ * Derive the address with `deriveDepositAddress(depositTweakCommitment(npk, eph),
+ * ikaXOnlyPubkey)`. Both keys are hashed into the leaf, so a caller cannot swap
+ * in an ephemeral key that leaves the note undiscoverable.
  *
- * Sweep mode only: `depositTxSize` must be non-zero. The receipt PDA is seeded
+ * No sweep: the deposit output's tapleaf names the pool's own dWallet key, so it
+ * is already under pool custody and is recorded as a pool UTXO directly. The
+ * SPV-verified transaction must therefore BE the deposit — `depositTxSize` is 0
+ * and `depositTxid` defaults to `sweepTxid`. The receipt PDA is seeded
  * `["deposit_receipt", txid, vout]`, so pass `depositVout` to
  * `deriveDepositReceiptPDA` for this flow.
  *
@@ -1329,9 +1335,10 @@ export function buildCompleteDepositInstructionData(params) {
  *         + note_public_key(32) + deposit_vout(u32 LE) = 149 bytes
  */
 export function buildVerifyDepositInstructionData(params) {
+    const depositTxid = params.depositTxid ?? params.sweepTxid;
     for (const [name, value] of [
         ["sweepTxid", params.sweepTxid],
-        ["depositTxid", params.depositTxid],
+        ["depositTxid", depositTxid],
         ["ephemeralPubkey", params.ephemeralPubkey],
         ["notePublicKey", params.notePublicKey],
     ]) {
@@ -1339,8 +1346,11 @@ export function buildVerifyDepositInstructionData(params) {
             throw new Error(`${name} must be 32 bytes, got ${value.length}`);
         }
     }
-    if (params.depositTxSize === 0) {
-        throw new Error("verify_deposit is sweep-mode only: depositTxSize must be non-zero");
+    if (params.depositTxSize) {
+        throw new Error("verify_deposit takes no second transaction: depositTxSize must be 0");
+    }
+    if (toHex(depositTxid) !== toHex(params.sweepTxid)) {
+        throw new Error("verify_deposit proves the deposit itself: depositTxid must equal sweepTxid");
     }
     const data = new Uint8Array(149);
     const view = new DataView(data.buffer);
@@ -1352,9 +1362,9 @@ export function buildVerifyDepositInstructionData(params) {
     offset += 8;
     view.setUint32(offset, params.sweepTxSize, true);
     offset += 4;
-    view.setUint32(offset, params.depositTxSize, true);
-    offset += 4;
-    data.set(params.depositTxid, offset);
+    view.setUint32(offset, 0, true);
+    offset += 4; // no second transaction
+    data.set(depositTxid, offset);
     offset += 32;
     data.set(params.ephemeralPubkey, offset);
     offset += 32;
@@ -1364,6 +1374,26 @@ export function buildVerifyDepositInstructionData(params) {
     offset += 4;
     return data;
 }
+/**
+ * Build utxopia verify_deposit_permissioned instruction data (disc=26).
+ *
+ * `buildVerifyDepositInstructionData`'s payload with a different discriminator
+ * and an auditor ciphertext appended. The tapleaf already tells the pools apart —
+ * each carries its own Ika custody key — but that is not the same as clearing the
+ * pool's policy, which is what a permissioned pool exists for.
+ *
+ * The one-time PolicyApproval is bound to the WHOLE payload, ciphertext included,
+ * so these exact bytes must be the ones approved.
+ */
+export function buildVerifyDepositPermissionedInstructionData(params) {
+    const base = buildVerifyDepositInstructionData(params);
+    const ciphertext = params.auditorCiphertext ?? new Uint8Array(0);
+    const data = new Uint8Array(base.length + ciphertext.length);
+    data.set(base, 0);
+    data.set(ciphertext, base.length);
+    data[0] = PERMISSIONED_DISC.VERIFY_DEPOSIT_PERMISSIONED;
+    return data;
+}
 // =============================================================================
 // UTXOpia Set Pool Config (disc=2)
 // =============================================================================

package/{packages/sdk/dist → dist}/stealth.d.ts

@@ -127,7 +127,7 @@ export interface OnChainStealthAnnouncement {
  * 6. commitment = Poseidon(npk, tokenId, amount)
  * 7. encryptedAmount = amount XOR sha256(sharedSecret)[0..8]
  */
-export declare function createStealthDeposit(recipientMeta: StealthMetaAddress, amountSats: bigint, tokenId: bigint): Promise<StealthDeposit>;
+export declare function createStealthDeposit(recipientMeta: StealthMetaAddress, amountSats: bigint, tokenId: bigint, outgoing?: OutgoingRecoveryMaterial): Promise<StealthDeposit>;
 /**
  * Extended stealth output data including the derived stealth pub key
  */
@@ -200,6 +200,86 @@ export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAd
  * credits the note from that transaction.
  */
 export declare function createDirectVaultDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest", opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+/**
+ * The delegable half of deposit recovery.
+ *
+ * Deposit addresses are derived from this node, so whoever holds it can rebuild
+ * every address the owner was ever handed, and with it every tapleaf and control
+ * block needed to spend those coins. It grants no spend authority over notes:
+ * that needs the spending key and the nullifying key, neither of which is
+ * derivable from here.
+ *
+ * Derived from the viewing key rather than the master seed on purpose. It means
+ * an owner can hand a chosen party — another device, a custodian, the pool
+ * operator — the ability to recover their BTC without handing over the ability
+ * to spend their notes. Same split Fluidkey uses for its ephemeral key nodes.
+ */
+export declare function depositViewingNode(viewingPrivKey: Uint8Array): Uint8Array;
+/**
+ * The delegable half of *outgoing* history.
+ *
+ * An announcement is encrypted to the recipient's viewing key, and the sender
+ * discards the ephemeral private key — so today a sender cannot rediscover what
+ * they paid out. Their history exists only in local storage. Indexing the
+ * ephemeral key off this node makes every outgoing payment recomputable from
+ * keys alone. Zcash calls the equivalent an outgoing viewing key.
+ *
+ * Deliberately a different node from `depositViewingNode`. The two authorise
+ * different things, and one should not smuggle in the other:
+ *
+ * - deposit node  → "you can recover my BTC"
+ * - outgoing node → "you can see who I paid"
+ */
+export declare function outgoingViewingNode(viewingPrivKey: Uint8Array): Uint8Array;
+/** Which outgoing payment an ephemeral key belongs to. */
+export interface OutgoingRecoveryMaterial {
+    /** From `outgoingViewingNode(viewingPrivKey)`. */
+    outgoingNode: Uint8Array;
+    /** Monotonic per-sender counter. One payment per index. */
+    sendIndex: number;
+}
+/** `sha256(domain || outgoingNode || sendIndex)` → Ed25519 ephemeral keypair. */
+export declare function outgoingEphemeralKeyPair(outgoing: OutgoingRecoveryMaterial): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};
+/**
+ * Recover the next unused send index by walking 0 upward against the ephemeral
+ * pubkeys already on chain.
+ *
+ * An index is "used" when some announcement carries the ephemeral pubkey it
+ * derives. Scanning stops after `gapLimit` consecutive misses, because a
+ * derived-but-never-broadcast payment leaves a hole — an abandoned or failed
+ * transaction — and stopping at the first hole would hand back an index that is
+ * already spoken for.
+ *
+ * This is a FLOOR, not the live counter. A payment broadcast but not yet indexed
+ * is invisible here, so a sender that keeps local state must take
+ * `max(localCounter, findNextSendIndex(...))`. Reusing an index re-derives the
+ * same ephemeral key, and to the same recipient that means the same note
+ * commitment twice.
+ */
+export declare function findNextSendIndex(outgoingNode: Uint8Array, seenEphemeralPubs: Iterable<Uint8Array>, gapLimit?: number): number;
+/**
+ * What makes a deposit address reconstructable.
+ *
+ * The ephemeral key is NOT random. A deposit address commits to it via the
+ * tapleaf, and the key path is a NUMS point, so an address whose ephemeral key
+ * is lost is an address nobody — not the owner, not the pool — can ever spend.
+ * Indexing it off the viewing node makes that node a complete backup: walk
+ * `depositIndex` upward and every address comes back.
+ */
+export interface DepositRecoveryMaterial {
+    /** From `depositViewingNode(viewingPrivKey)`. */
+    viewingNode: Uint8Array;
+    /** Monotonic per-owner counter. One address per index. */
+    depositIndex: number;
+}
+/** `sha256(domain || viewingNode || depositIndex)` → Ed25519 ephemeral keypair. */
+export declare function depositEphemeralKeyPair(recovery: DepositRecoveryMaterial): {
+    privKey: Uint8Array;
+    pubKey: Uint8Array;
+};
 /** A deposit whose address alone binds the note keys — no OP_RETURN. */
 export interface TweakDepositResult {
     /** Taproot address to send BTC to */
@@ -210,8 +290,14 @@ export interface TweakDepositResult {
     npk: Uint8Array;
     /** 32-byte Ed25519 ephemeral public key */
     ephemeralPub: Uint8Array;
-    /** sha256(npk || ephemeralPub) — the commitment the address is tweaked by */
+    /** sha256(npk || ephemeralPub) — the commitment carried in the tapleaf */
     tweakCommitment: Uint8Array;
+    /** The tapleaf: `<commitment> OP_DROP <ika_xonly> OP_CHECKSIG` */
+    leafScript: Uint8Array;
+    /** Its BIP-341 tapleaf hash, which is also the merkle root (single leaf) */
+    leafHash: Uint8Array;
+    /** Script-path witness is `[signature, leafScript, controlBlock]` */
+    controlBlock: Uint8Array;
 }
 /**
  * Create a deposit for the OP_RETURN-free flow (`verify_deposit`, disc 25).
@@ -219,15 +305,24 @@ export interface TweakDepositResult {
  * The transaction carries nothing but a payment, so anything that can send to a
  * P2TR address can fund it — a hardware wallet, an exchange withdrawal, a faucet.
  * The note keys are recovered from instruction data at completion time and proven
- * against this address's Taproot tweak, so substituting either key derives a
- * different address that the funding transaction never paid.
+ * against this address's tapleaf, so substituting either key derives a different
+ * leaf, and so a different address that the funding transaction never paid.
+ *
+ * The address is spendable only by `vaultXOnlyPubkey` via the script path; its
+ * key path is a NUMS point. That keeps the deposit under Ika custody from the
+ * moment it confirms, and it is also the only shape Ika can sign for — its MPC
+ * cannot produce a signature for a tweaked key.
+ *
+ * `recovery` is not optional on purpose. The address commits to the ephemeral
+ * key and the key path is unspendable, so a random ephemeral key that is later
+ * lost burns the coins outright. Indexing it off the viewing node means that
+ * node is the backup — and it can be delegated without granting spend authority.
  *
- * Sweep mode: the pool sweeps this address into its own custody, and that sweep
- * is what gets SPV-verified. Register the address with the tracker BEFORE any
- * coins are sent — a deposit with no OP_RETURN is invisible to block scanning,
- * so an unregistered address is one nobody is watching.
+ * Register the address with the tracker BEFORE any coins are sent — a deposit
+ * with no OP_RETURN is invisible to block scanning, so an unregistered address
+ * is one nobody is watching.
  */
-export declare function createTweakDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest"): Promise<TweakDepositResult>;
+export declare function createTweakDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, recovery: DepositRecoveryMaterial, network?: "mainnet" | "testnet" | "regtest"): Promise<TweakDepositResult>;
 /**
  * Create a non-interactive deposit using the current SDK config.
  *

package/{packages/sdk/dist → dist}/stealth.js

@@ -42,7 +42,7 @@ function isKnownAnnouncementType(value) {
 // ========== Imports ==========
 import { sha256 } from "@noble/hashes/sha2.js";
 import { bigintToBytes, bytesToBigint, bytesToHex, hexToBytes, babyJubMul, babyJubAdd, babyJubCompress, babyJubDecompress, BABYJUB_BASE8, BABYJUB_ORDER, scalarFromBytes, } from "./crypto";
-import { ed25519GenerateKeyPair, x25519Ecdh, encryptAmountEd25519, decryptAmountEd25519, } from "./crypto-ed25519";
+import { ed25519GenerateKeyPair, ed25519KeyPairFromMaterial, x25519Ecdh, encryptAmountEd25519, decryptAmountEd25519, } from "./crypto-ed25519";
 import { deriveKeysFromWallet } from "./keys";
 import { computeMPKSync, computeNPKSync, computeJoinSplitCommitmentSync, computeJoinSplitNullifierSync, } from "./poseidon";
 import { getConfig } from "./config";
@@ -124,11 +124,17 @@ function deriveStealthPrivKey(spendingPriv, sharedSecret) {
  * 6. commitment = Poseidon(npk, tokenId, amount)
  * 7. encryptedAmount = amount XOR sha256(sharedSecret)[0..8]
  */
-export async function createStealthDeposit(recipientMeta, amountSats, tokenId) {
+export async function createStealthDeposit(recipientMeta, amountSats, tokenId, outgoing) {
     // Only viewingPubKey + mpk needed (spendingPubKey not used by sender)
     const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
-    // Generate Ed25519 ephemeral keypair
-    const ephemeral = ed25519GenerateKeyPair();
+    // Indexed off the sender's outgoing node when supplied, so they can recompute
+    // this payment later; random otherwise, which works but leaves no trace the
+    // sender can recover. Optional rather than required because the cost of
+    // omitting it is a lost record, not lost funds — unlike a deposit address,
+    // where the ephemeral key IS the only way to ever spend the coins.
+    const ephemeral = outgoing
+        ? outgoingEphemeralKeyPair(outgoing)
+        : ed25519GenerateKeyPair();
     // X25519 ECDH: shared secret
     const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
     // Derive stealth scalar as the random value for NPK
@@ -248,40 +254,166 @@ export async function createDirectVaultDeposit(recipientMeta, vaultXOnlyPubkey,
         ephemeralPub,
     };
 }
+const DEPOSIT_VIEWING_NODE_DOMAIN = new TextEncoder().encode("utxopia:deposit-viewing-node:v1");
+const DEPOSIT_EPHEMERAL_DOMAIN = new TextEncoder().encode("utxopia:deposit-ephemeral:v1");
+/**
+ * The delegable half of deposit recovery.
+ *
+ * Deposit addresses are derived from this node, so whoever holds it can rebuild
+ * every address the owner was ever handed, and with it every tapleaf and control
+ * block needed to spend those coins. It grants no spend authority over notes:
+ * that needs the spending key and the nullifying key, neither of which is
+ * derivable from here.
+ *
+ * Derived from the viewing key rather than the master seed on purpose. It means
+ * an owner can hand a chosen party — another device, a custodian, the pool
+ * operator — the ability to recover their BTC without handing over the ability
+ * to spend their notes. Same split Fluidkey uses for its ephemeral key nodes.
+ */
+export function depositViewingNode(viewingPrivKey) {
+    if (viewingPrivKey.length === 0) {
+        throw new Error("viewingPrivKey must not be empty");
+    }
+    const material = new Uint8Array(DEPOSIT_VIEWING_NODE_DOMAIN.length + viewingPrivKey.length);
+    material.set(DEPOSIT_VIEWING_NODE_DOMAIN, 0);
+    material.set(viewingPrivKey, DEPOSIT_VIEWING_NODE_DOMAIN.length);
+    return sha256(material);
+}
+const OUTGOING_VIEWING_NODE_DOMAIN = new TextEncoder().encode("utxopia:outgoing-viewing-node:v1");
+const OUTGOING_EPHEMERAL_DOMAIN = new TextEncoder().encode("utxopia:outgoing-ephemeral:v1");
+/**
+ * The delegable half of *outgoing* history.
+ *
+ * An announcement is encrypted to the recipient's viewing key, and the sender
+ * discards the ephemeral private key — so today a sender cannot rediscover what
+ * they paid out. Their history exists only in local storage. Indexing the
+ * ephemeral key off this node makes every outgoing payment recomputable from
+ * keys alone. Zcash calls the equivalent an outgoing viewing key.
+ *
+ * Deliberately a different node from `depositViewingNode`. The two authorise
+ * different things, and one should not smuggle in the other:
+ *
+ * - deposit node  → "you can recover my BTC"
+ * - outgoing node → "you can see who I paid"
+ */
+export function outgoingViewingNode(viewingPrivKey) {
+    if (viewingPrivKey.length === 0) {
+        throw new Error("viewingPrivKey must not be empty");
+    }
+    const material = new Uint8Array(OUTGOING_VIEWING_NODE_DOMAIN.length + viewingPrivKey.length);
+    material.set(OUTGOING_VIEWING_NODE_DOMAIN, 0);
+    material.set(viewingPrivKey, OUTGOING_VIEWING_NODE_DOMAIN.length);
+    return sha256(material);
+}
+/** `sha256(domain || outgoingNode || sendIndex)` → Ed25519 ephemeral keypair. */
+export function outgoingEphemeralKeyPair(outgoing) {
+    const { outgoingNode, sendIndex } = outgoing;
+    if (outgoingNode.length === 0) {
+        throw new Error("outgoingNode must not be empty");
+    }
+    if (!Number.isInteger(sendIndex) || sendIndex < 0) {
+        throw new Error(`invalid sendIndex: ${sendIndex}`);
+    }
+    const material = new Uint8Array(OUTGOING_EPHEMERAL_DOMAIN.length + outgoingNode.length + 4);
+    material.set(OUTGOING_EPHEMERAL_DOMAIN, 0);
+    material.set(outgoingNode, OUTGOING_EPHEMERAL_DOMAIN.length);
+    new DataView(material.buffer).setUint32(OUTGOING_EPHEMERAL_DOMAIN.length + outgoingNode.length, sendIndex, true);
+    return ed25519KeyPairFromMaterial(material);
+}
+/**
+ * Recover the next unused send index by walking 0 upward against the ephemeral
+ * pubkeys already on chain.
+ *
+ * An index is "used" when some announcement carries the ephemeral pubkey it
+ * derives. Scanning stops after `gapLimit` consecutive misses, because a
+ * derived-but-never-broadcast payment leaves a hole — an abandoned or failed
+ * transaction — and stopping at the first hole would hand back an index that is
+ * already spoken for.
+ *
+ * This is a FLOOR, not the live counter. A payment broadcast but not yet indexed
+ * is invisible here, so a sender that keeps local state must take
+ * `max(localCounter, findNextSendIndex(...))`. Reusing an index re-derives the
+ * same ephemeral key, and to the same recipient that means the same note
+ * commitment twice.
+ */
+export function findNextSendIndex(outgoingNode, seenEphemeralPubs, gapLimit = 20) {
+    const seen = new Set();
+    for (const pub of seenEphemeralPubs)
+        seen.add(bytesToHex(pub));
+    let highestUsed = -1;
+    let misses = 0;
+    for (let index = 0; misses <= gapLimit; index++) {
+        if (seen.has(bytesToHex(outgoingEphemeralKeyPair({ outgoingNode, sendIndex: index }).pubKey))) {
+            highestUsed = index;
+            misses = 0;
+        }
+        else {
+            misses++;
+        }
+    }
+    return highestUsed + 1;
+}
+/** `sha256(domain || viewingNode || depositIndex)` → Ed25519 ephemeral keypair. */
+export function depositEphemeralKeyPair(recovery) {
+    const { viewingNode, depositIndex } = recovery;
+    if (viewingNode.length === 0) {
+        throw new Error("deposit viewingNode must not be empty");
+    }
+    if (!Number.isInteger(depositIndex) || depositIndex < 0) {
+        throw new Error(`invalid depositIndex: ${depositIndex}`);
+    }
+    const material = new Uint8Array(DEPOSIT_EPHEMERAL_DOMAIN.length + viewingNode.length + 4);
+    material.set(DEPOSIT_EPHEMERAL_DOMAIN, 0);
+    material.set(viewingNode, DEPOSIT_EPHEMERAL_DOMAIN.length);
+    new DataView(material.buffer).setUint32(DEPOSIT_EPHEMERAL_DOMAIN.length + viewingNode.length, depositIndex, true);
+    return ed25519KeyPairFromMaterial(material);
+}
 /**
  * Create a deposit for the OP_RETURN-free flow (`verify_deposit`, disc 25).
  *
  * The transaction carries nothing but a payment, so anything that can send to a
  * P2TR address can fund it — a hardware wallet, an exchange withdrawal, a faucet.
  * The note keys are recovered from instruction data at completion time and proven
- * against this address's Taproot tweak, so substituting either key derives a
- * different address that the funding transaction never paid.
+ * against this address's tapleaf, so substituting either key derives a different
+ * leaf, and so a different address that the funding transaction never paid.
  *
- * Sweep mode: the pool sweeps this address into its own custody, and that sweep
- * is what gets SPV-verified. Register the address with the tracker BEFORE any
- * coins are sent — a deposit with no OP_RETURN is invisible to block scanning,
- * so an unregistered address is one nobody is watching.
+ * The address is spendable only by `vaultXOnlyPubkey` via the script path; its
+ * key path is a NUMS point. That keeps the deposit under Ika custody from the
+ * moment it confirms, and it is also the only shape Ika can sign for — its MPC
+ * cannot produce a signature for a tweaked key.
+ *
+ * `recovery` is not optional on purpose. The address commits to the ephemeral
+ * key and the key path is unspendable, so a random ephemeral key that is later
+ * lost burns the coins outright. Indexing it off the viewing node means that
+ * node is the backup — and it can be delegated without granting spend authority.
+ *
+ * Register the address with the tracker BEFORE any coins are sent — a deposit
+ * with no OP_RETURN is invisible to block scanning, so an unregistered address
+ * is one nobody is watching.
  */
-export async function createTweakDeposit(recipientMeta, vaultXOnlyPubkey, network = "testnet") {
+export async function createTweakDeposit(recipientMeta, vaultXOnlyPubkey, recovery, network = "testnet") {
     if (vaultXOnlyPubkey.length !== 32) {
         throw new Error("vaultXOnlyPubkey must be 32 bytes");
     }
     const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
-    const ephemeral = ed25519GenerateKeyPair();
+    const ephemeral = depositEphemeralKeyPair(recovery);
     const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
     const stealthScalar = deriveStealthScalar(sharedSecret);
     const recipientMPK = bytesToBigint(recipientMeta.mpk);
     const npk = bigintToBytes(computeNPKSync(recipientMPK, stealthScalar));
     const ephemeralPub = new Uint8Array(ephemeral.pubKey);
-    const { depositTweakCommitment, deriveTaprootAddress } = await import("./taproot");
+    const { depositTweakCommitment, deriveDepositAddress } = await import("./taproot");
     const tweakCommitment = depositTweakCommitment(npk, ephemeralPub);
-    const { address, outputKey } = deriveTaprootAddress(tweakCommitment, network, vaultXOnlyPubkey);
+    const { address, outputKey, leafScript, leafHash, controlBlock } = deriveDepositAddress(tweakCommitment, vaultXOnlyPubkey, network);
     return {
         btcAddress: address,
         depositOutputKey: outputKey,
         npk,
         ephemeralPub,
         tweakCommitment,
+        leafScript,
+        leafHash,
+        controlBlock,
     };
 }
 /**

package/{packages/sdk/dist → dist}/taproot.d.ts

@@ -22,18 +22,55 @@ export declare function deriveTaprootAddress(commitment: Uint8Array, network?: "
     address: string;
     outputKey: Uint8Array;
     tweak: Uint8Array;
+    /** y-parity of the output key — the low bit of a script-path control block. */
+    parity: number;
 };
 /**
- * Commitment a `verify_deposit` (disc 25) deposit address is derived from.
+ * Per-deposit commitment carried in a `verify_deposit` (disc 25) address's tapleaf.
  *
  * Both keys are hashed in. Binding the note key alone would leave the ephemeral
  * pubkey caller-chosen on the Solana side: the credited amount and owner would
  * still be right, but a substituted ephemeral key makes the stealth announcement
  * undecryptable and the recipient never finds their note.
  *
- * Feed the result to `deriveTaprootAddress` as the commitment.
+ * Feed the result to `deriveDepositAddress`.
  */
 export declare function depositTweakCommitment(notePublicKey: Uint8Array, ephemeralPubkey: Uint8Array): Uint8Array;
+/**
+ * BIP-341's suggested NUMS point, used as the deposit address's internal key.
+ *
+ * Nobody knows its discrete log, so the key path is unspendable and custody
+ * rests entirely on the script path. That is deliberate: Ika's MPC cannot sign
+ * for a tweaked key, so an address whose internal key were the dWallet key plus
+ * a per-deposit tweak would be unspendable by the custodian meant to sweep it.
+ */
+export declare const DEPOSIT_NUMS_INTERNAL_KEY: Uint8Array<ArrayBufferLike>;
+/**
+ * The single tapleaf a deposit address commits to:
+ *
+ * ```text
+ * <commitment> OP_DROP <ika_xonly> OP_CHECKSIG
+ * ```
+ *
+ * The commitment rides in the script purely to make the leaf — and so the
+ * address — unique per deposit; `OP_DROP` discards it at spend time. Only the
+ * dWallet key can satisfy the `OP_CHECKSIG`, and it signs untweaked.
+ */
+export declare function depositLeafScript(commitment: Uint8Array, ikaXOnlyPubkey: Uint8Array): Uint8Array;
+/**
+ * Derive a deposit address bound to `commitment`, spendable only by the pool's
+ * Ika dWallet via the script path.
+ *
+ * Returns everything the sweeper needs to spend it: a script-path witness is
+ * `[signature, leafScript, controlBlock]`.
+ */
+export declare function deriveDepositAddress(commitment: Uint8Array, ikaXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest"): {
+    address: string;
+    outputKey: Uint8Array;
+    leafScript: Uint8Array;
+    leafHash: Uint8Array;
+    controlBlock: Uint8Array;
+};
 /**
  * Verify that a Taproot address is correctly derived from a commitment
  *