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

package/dist/spend-doc.d.ts

@@ -0,0 +1,63 @@
+/**
+ * "What am I proving?" — a canonical sentence for a shielded spend.
+ *
+ * The text is not the point. The point is that `renderSpendDoc` recomputes the
+ * proof's public signals from the numbers it is about to print and throws if
+ * they disagree, so a UI cannot caption a proof with an amount or a destination
+ * the proof does not actually contain.
+ *
+ * Nothing here changes the circuit. Every value below is already bound to the
+ * user's spending key by the in-circuit EdDSA over
+ * Poseidon(merkleRoot, boundParamsHash, nullifiers.., commitmentsOut..).
+ */
+import { type SolanaPrivacyDomainContext } from "./bound-params";
+export interface SpendDoc {
+    mode: "transfer" | "unshield" | "redeem";
+    /** Display label, e.g. "Solana Devnet". */
+    network: string;
+    /** Display label, e.g. "zkBTC". */
+    asset: string;
+    decimals: number;
+    /** Destination as shown to the user (a .sol name, a BTC address, a pubkey). */
+    recipient: string;
+    /**
+     * The destination bytes actually folded into boundParamsHash: 32-byte Solana
+     * owner for `unshield`, raw scriptPubKey for `redeem`. Omitted for `transfer`,
+     * where the destination is private and provably absent from the signals.
+     */
+    recipientBytes?: Uint8Array;
+    /** Raw units the recipient receives. */
+    amount: bigint;
+    relayerFee: bigint;
+    change: bigint;
+}
+/** The public signals of the proof about to be generated, plus what built them. */
+export interface SpendSignals {
+    /** `outputs.map(o => o.value)` from JoinSplitProofInputs. */
+    outputValues: bigint[];
+    /** The boundParamsHash going into the proof. */
+    boundParamsHash: bigint;
+    stealthDataHash: Uint8Array;
+    chainId: bigint;
+    domain: SolanaPrivacyDomainContext;
+    /** Redeem only: the on-chain requester bound into the proof. */
+    requester?: Uint8Array;
+    treeNumber?: number;
+}
+export declare class SpendDocMismatch extends Error {
+}
+/**
+ * The statement itself. Show this before the user commits; pass the same `doc`
+ * to `renderSpendDoc` when the proof is built so the string they read is the
+ * string that gets checked.
+ */
+export declare function formatSpendDoc(doc: SpendDoc): string;
+/**
+ * Render the statement, or throw if it does not describe `signals`.
+ *
+ * Checked: every amount on screen is an output value of the proof and there are
+ * no other outputs; the destination reproduces boundParamsHash.
+ * Not checked: that `recipient` (a label) names `recipientBytes` — the doc
+ * prints the bound bytes so that stays verifiable by eye.
+ */
+export declare function renderSpendDoc(doc: SpendDoc, signals: SpendSignals): string;

package/dist/spend-doc.js

@@ -0,0 +1,100 @@
+/**
+ * "What am I proving?" — a canonical sentence for a shielded spend.
+ *
+ * The text is not the point. The point is that `renderSpendDoc` recomputes the
+ * proof's public signals from the numbers it is about to print and throws if
+ * they disagree, so a UI cannot caption a proof with an amount or a destination
+ * the proof does not actually contain.
+ *
+ * Nothing here changes the circuit. Every value below is already bound to the
+ * user's spending key by the in-circuit EdDSA over
+ * Poseidon(merkleRoot, boundParamsHash, nullifiers.., commitmentsOut..).
+ */
+import { computeSolanaDomainBoundParamsHash, createRedeemBoundParams, createTransferBoundParams, createUnshieldBoundParams, } from "./bound-params";
+export class SpendDocMismatch extends Error {
+}
+function fmt(raw, decimals) {
+    const neg = raw < 0n;
+    const s = (neg ? -raw : raw).toString().padStart(decimals + 1, "0");
+    const whole = s.slice(0, s.length - decimals);
+    const frac = decimals === 0 ? "" : s.slice(s.length - decimals).replace(/0+$/, "");
+    return `${neg ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
+}
+const hex = (b) => Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+function sortedValues(v) {
+    return [...v].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0)).join(",");
+}
+function expectedBoundParamsHash(doc, s) {
+    const tree = s.treeNumber ?? 0;
+    switch (doc.mode) {
+        case "transfer":
+            return computeSolanaDomainBoundParamsHash(createTransferBoundParams(s.stealthDataHash, s.chainId, tree), s.domain);
+        case "unshield":
+            if (!doc.recipientBytes)
+                throw new SpendDocMismatch("unshield doc has no recipientBytes");
+            return computeSolanaDomainBoundParamsHash(createUnshieldBoundParams(doc.recipientBytes, s.stealthDataHash, s.chainId, tree), s.domain);
+        case "redeem":
+            if (!doc.recipientBytes)
+                throw new SpendDocMismatch("redeem doc has no recipientBytes");
+            if (!s.requester)
+                throw new SpendDocMismatch("redeem doc has no requester");
+            return computeSolanaDomainBoundParamsHash(createRedeemBoundParams(doc.recipientBytes, s.stealthDataHash, s.requester, s.chainId, tree), s.domain);
+    }
+}
+/**
+ * The statement itself. Show this before the user commits; pass the same `doc`
+ * to `renderSpendDoc` when the proof is built so the string they read is the
+ * string that gets checked.
+ */
+export function formatSpendDoc(doc) {
+    const amt = (v) => `${fmt(v, doc.decimals)} ${doc.asset}`;
+    const action = doc.mode === "redeem"
+        ? `Withdraw ${amt(doc.amount)} to Bitcoin`
+        : doc.mode === "unshield"
+            ? `Unshield ${amt(doc.amount)}`
+            : `Send ${amt(doc.amount)} privately`;
+    const lines = [
+        "UTXOpia Proof",
+        "",
+        "I AM PROVING",
+        action,
+        "",
+        "DETAILS",
+        `Network: ${doc.network}`,
+        `Amount leaving the pool: ${amt(doc.amount)}`,
+        `To: ${doc.recipient}`,
+    ];
+    if (doc.recipientBytes)
+        lines.push(`Bound destination: ${hex(doc.recipientBytes)}`);
+    if (doc.relayerFee > 0n)
+        lines.push(`Relayer fee: ${amt(doc.relayerFee)}`);
+    if (doc.change > 0n)
+        lines.push(`Change back to me: ${amt(doc.change)}`);
+    lines.push("", "ENFORCED BY THE PROOF", "Amounts: these are every output this proof creates", doc.mode === "transfer"
+        ? "Destination: private — not in the public signals. Confirm it with the recipient."
+        : "Destination: bound into boundParamsHash and re-derived onchain");
+    if (doc.mode !== "transfer") {
+        lines.push("Protocol fee: deducted onchain from pool policy, not part of this statement");
+    }
+    lines.push("", "Protocol: utxopia-spend-doc-v1");
+    return lines.join("\n");
+}
+/**
+ * Render the statement, or throw if it does not describe `signals`.
+ *
+ * Checked: every amount on screen is an output value of the proof and there are
+ * no other outputs; the destination reproduces boundParamsHash.
+ * Not checked: that `recipient` (a label) names `recipientBytes` — the doc
+ * prints the bound bytes so that stays verifiable by eye.
+ */
+export function renderSpendDoc(doc, signals) {
+    const shown = [doc.amount, doc.relayerFee, doc.change].filter((v) => v > 0n);
+    if (sortedValues(shown) !== sortedValues(signals.outputValues)) {
+        throw new SpendDocMismatch(`amounts do not match the proof outputs: doc [${sortedValues(shown)}] vs proof [${sortedValues(signals.outputValues)}]`);
+    }
+    const expected = expectedBoundParamsHash(doc, signals);
+    if (expected !== signals.boundParamsHash) {
+        throw new SpendDocMismatch("destination does not match the proof's boundParamsHash");
+    }
+    return formatSpendDoc(doc);
+}

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,129 @@ 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 */
+    btcAddress: string;
+    /** 32-byte x-only output key for the deposit P2TR output */
+    depositOutputKey: Uint8Array;
+    /** 32-byte note public key */
+    npk: Uint8Array;
+    /** 32-byte Ed25519 ephemeral public key */
+    ephemeralPub: Uint8Array;
+    /** 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).
+ *
+ * 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 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.
+ *
+ * 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, 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,6 +254,168 @@ 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 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.
+ *
+ * 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, recovery, network = "testnet") {
+    if (vaultXOnlyPubkey.length !== 32) {
+        throw new Error("vaultXOnlyPubkey must be 32 bytes");
+    }
+    const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
+    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, deriveDepositAddress } = await import("./taproot");
+    const tweakCommitment = depositTweakCommitment(npk, ephemeralPub);
+    const { address, outputKey, leafScript, leafHash, controlBlock } = deriveDepositAddress(tweakCommitment, vaultXOnlyPubkey, network);
+    return {
+        btcAddress: address,
+        depositOutputKey: outputKey,
+        npk,
+        ephemeralPub,
+        tweakCommitment,
+        leafScript,
+        leafHash,
+        controlBlock,
+    };
+}
 /**
  * Create a non-interactive deposit using the current SDK config.
  *

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

@@ -22,6 +22,54 @@ 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;
+};
+/**
+ * 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 `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

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

@@ -68,8 +68,79 @@ export function deriveTaprootAddress(commitment, network = "testnet", internalKe
         address,
         outputKey,
         tweak,
+        parity: outputKeyHex.startsWith("03") ? 1 : 0,
     };
 }
+/**
+ * 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 `deriveDepositAddress`.
+ */
+export function depositTweakCommitment(notePublicKey, ephemeralPubkey) {
+    if (notePublicKey.length !== 32 || ephemeralPubkey.length !== 32) {
+        throw new Error("notePublicKey and ephemeralPubkey must be 32 bytes");
+    }
+    const material = new Uint8Array(64);
+    material.set(notePublicKey, 0);
+    material.set(ephemeralPubkey, 32);
+    return sha256(material);
+}
+/**
+ * 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 const DEPOSIT_NUMS_INTERNAL_KEY = hexToBytes("50929b74c1a04954b78b4b6035e97a5e078a5a0f28ec96d547bfee9ace803ac0");
+/**
+ * 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 function depositLeafScript(commitment, ikaXOnlyPubkey) {
+    if (commitment.length !== 32 || ikaXOnlyPubkey.length !== 32) {
+        throw new Error("commitment and ikaXOnlyPubkey must be 32 bytes");
+    }
+    const script = new Uint8Array(68);
+    script[0] = 0x20; // push 32 bytes
+    script.set(commitment, 1);
+    script[33] = 0x75; // OP_DROP
+    script[34] = 0x20; // push 32 bytes
+    script.set(ikaXOnlyPubkey, 35);
+    script[67] = 0xac; // OP_CHECKSIG
+    return script;
+}
+/**
+ * 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 function deriveDepositAddress(commitment, ikaXOnlyPubkey, network = "testnet") {
+    const leafScript = depositLeafScript(commitment, ikaXOnlyPubkey);
+    // One leaf, so the leaf hash IS the merkle root.
+    const leafHash = computeTapLeafHash(leafScript);
+    const { address, outputKey, parity } = deriveTaprootAddress(leafHash, network, DEPOSIT_NUMS_INTERNAL_KEY);
+    // <leaf_version | parity> || internal_key. No merkle path: single leaf.
+    const controlBlock = new Uint8Array(33);
+    controlBlock[0] = 0xc0 | parity;
+    controlBlock.set(DEPOSIT_NUMS_INTERNAL_KEY, 1);
+    return { address, outputKey, leafScript, leafHash, controlBlock };
+}
 /**
  * Verify that a Taproot address is correctly derived from a commitment
  *