@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/stealth.js

@@ -0,0 +1,703 @@
+/**
+ * Stealth address utilities for UTXOPIA
+ *
+ * Dual-curve stealth flow (Railgun-style):
+ *
+ * Stealth Deposit Flow:
+ * ```
+ * Sender:
+ *   1. ephemeral = random Ed25519 keypair
+ *   2. sharedSecret = X25519(ephemeral.priv, recipientViewingPub)
+ *   3. stealthScalar = SHA256(sharedSecret || domain) mod BJJ_ORDER
+ *   4. stealthPub = spendingPub + stealthScalar × BASE8 (Baby Jubjub)
+ *   5. commitment = Poseidon(stealthPub.x, amount)
+ *   6. encryptedAmount = amount XOR sha256(sharedSecret)[0..8]
+ *
+ * Recipient (viewing key only - can detect and see amount):
+ *   1. sharedSecret = X25519(viewingPriv, ephemeralPub)
+ *   2. amount = encryptedAmount XOR sha256(sharedSecret)[0..8]
+ *   3. stealthPub = spendingPub + stealthScalar × BASE8
+ *   4. Verify: commitment == Poseidon(stealthPub.x, amount)
+ *
+ * Recipient (spending key - can claim):
+ *   1. stealthPriv = spendingPriv + stealthScalar (mod BJJ_ORDER)
+ *   2. nullifier = Poseidon(stealthPriv, leafIndex)
+ * ```
+ *
+ * Format (90 bytes on-chain):
+ * - ephemeral_pub (32 bytes) - Ed25519 public key
+ * - encrypted_amount (8 bytes) - XOR encrypted with shared secret
+ * - commitment (32 bytes) - Poseidon hash for Merkle tree
+ * - leaf_index (8 bytes) - Position in Merkle tree
+ * - created_at (8 bytes) - Timestamp
+ */
+// ========== Constants (defined before imports to ensure availability) ==========
+/** Announcement type: deposit (plaintext amount) */
+export const ANNOUNCEMENT_TYPE_DEPOSIT = 0;
+/** Announcement type: transfer (XOR-encrypted amount) */
+export const ANNOUNCEMENT_TYPE_TRANSFER = 1;
+function isKnownAnnouncementType(value) {
+    return value === ANNOUNCEMENT_TYPE_DEPOSIT || value === ANNOUNCEMENT_TYPE_TRANSFER;
+}
+// ========== 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 { deriveKeysFromWallet } from "./keys";
+import { computeMPKSync, computeNPKSync, computeJoinSplitCommitmentSync, computeJoinSplitNullifierSync, } from "./poseidon";
+import { getConfig } from "./config";
+import { deriveRawXOnlyP2TRAddress } from "./bitcoin/ika";
+// ========== Amount Encryption Helpers ==========
+/**
+ * Encrypt amount using XOR with shared secret
+ */
+export function encryptAmount(amount, sharedSecret) {
+    return encryptAmountEd25519(amount, sharedSecret);
+}
+/**
+ * Decrypt amount using XOR with shared secret
+ */
+export function decryptAmount(encryptedAmount, sharedSecret) {
+    return decryptAmountEd25519(encryptedAmount, sharedSecret);
+}
+// Re-export combined note data encryption
+export { encryptNoteData, decryptNoteData } from "./crypto-ed25519";
+// ========== Type Guard ==========
+/**
+ * Type guard to distinguish between WalletSignerAdapter and UTXOpiaKeys
+ */
+export function isWalletAdapter(source) {
+    return (typeof source === "object" &&
+        source !== null &&
+        "signMessage" in source &&
+        typeof source.signMessage === "function");
+}
+// ========== Helper Functions ==========
+/** Domain separator for stealth key derivation.
+ *  "Utxopia-stealth-v1" is LOAD-BEARING — once real stealth addresses exist this
+ *  exact byte sequence is FROZEN; sender and receiver must use the identical
+ *  value or payments won't be detected. Bump the suffix only as a deliberate
+ *  v2 break. */
+const STEALTH_KEY_DOMAIN = new TextEncoder().encode("Utxopia-stealth-v1");
+// tokenId removed — use computeTokenId(mintBytes) from poseidon.ts instead
+/**
+ * Derive stealth scalar from X25519 shared secret
+ *
+ * stealthScalar = SHA256(sharedSecret || domain) mod BJJ_ORDER
+ */
+function deriveStealthScalar(sharedSecret) {
+    const hashInput = new Uint8Array(sharedSecret.length + STEALTH_KEY_DOMAIN.length);
+    hashInput.set(sharedSecret, 0);
+    hashInput.set(STEALTH_KEY_DOMAIN, sharedSecret.length);
+    const hash = sha256(hashInput);
+    return scalarFromBytes(hash);
+}
+/**
+ * Derive stealth public key (Baby Jubjub)
+ *
+ * stealthPub = spendingPub + stealthScalar × BASE8
+ */
+function deriveStealthPubKey(spendingPub, sharedSecret) {
+    const scalar = deriveStealthScalar(sharedSecret);
+    const scalarPoint = babyJubMul(scalar, BABYJUB_BASE8);
+    return babyJubAdd(spendingPub, scalarPoint);
+}
+/**
+ * Derive stealth private key (Baby Jubjub scalar addition)
+ *
+ * stealthPriv = spendingPriv + stealthScalar (mod BJJ_ORDER)
+ */
+function deriveStealthPrivKey(spendingPriv, sharedSecret) {
+    const scalar = deriveStealthScalar(sharedSecret);
+    return (spendingPriv + scalar) % BABYJUB_ORDER;
+}
+// ========== Sender Functions ==========
+/**
+ * Create a stealth deposit (JoinSplit-compatible)
+ *
+ * 1. Generate Ed25519 ephemeral keypair
+ * 2. sharedSecret = X25519(ephemeral.priv, viewingPub)
+ * 3. stealthPub = spendingPub + hash(sharedSecret) × BASE8
+ * 4. stealthMPK = Poseidon(stealthPub.x, stealthPub.y, nullifyingKey)
+ *    (sender uses recipientMPK from meta-address for stealth deposits)
+ * 5. npk = Poseidon(recipientMPK, random)
+ * 6. commitment = Poseidon(npk, tokenId, amount)
+ * 7. encryptedAmount = amount XOR sha256(sharedSecret)[0..8]
+ */
+export async function createStealthDeposit(recipientMeta, amountSats, tokenId) {
+    // Only viewingPubKey + mpk needed (spendingPubKey not used by sender)
+    const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
+    // Generate Ed25519 ephemeral keypair
+    const ephemeral = ed25519GenerateKeyPair();
+    // X25519 ECDH: shared secret
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
+    // Derive stealth scalar as the random value for NPK
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    // Use recipient's MPK from meta-address to compute NPK
+    const recipientMPK = bytesToBigint(recipientMeta.mpk);
+    const npk = computeNPKSync(recipientMPK, stealthScalar);
+    // Compute JoinSplit commitment = Poseidon(npk, token, amount)
+    const commitmentBigint = computeJoinSplitCommitmentSync(npk, tokenId, amountSats);
+    const commitment = bigintToBytes(commitmentBigint);
+    // Encrypt amount
+    const encryptedAmount = encryptAmount(amountSats, sharedSecret);
+    return {
+        ephemeralPub: new Uint8Array(ephemeral.pubKey),
+        encryptedAmount,
+        commitment,
+        createdAt: Date.now(),
+    };
+}
+/**
+ * Create stealth deposit with npk for JoinSplit circuit input
+ */
+export async function createStealthDepositWithKeys(recipientMeta, amountSats, tokenId) {
+    // Only viewingPubKey + mpk needed (spendingPubKey not used by sender)
+    const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
+    const ephemeral = ed25519GenerateKeyPair();
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    const recipientMPK = bytesToBigint(recipientMeta.mpk);
+    const npk = computeNPKSync(recipientMPK, stealthScalar);
+    const commitmentBigint = computeJoinSplitCommitmentSync(npk, tokenId, amountSats);
+    const commitment = bigintToBytes(commitmentBigint);
+    const encryptedAmount = encryptAmount(amountSats, sharedSecret);
+    return {
+        ephemeralPub: new Uint8Array(ephemeral.pubKey),
+        encryptedAmount,
+        commitment,
+        stealthPubKeyX: npk,
+        npkBytes: bigintToBytes(npk),
+    };
+}
+export async function createNonInteractiveDeposit(recipientMeta, custodyInternalKey, network = "testnet", userRefundPubkey, opReturnContext) {
+    if (!opReturnContext) {
+        throw new Error("deposit OP_RETURN context is required");
+    }
+    // Only viewingPubKey + mpk needed (spendingPubKey not used by sender)
+    const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
+    // 1. Generate ephemeral Ed25519 keypair
+    const ephemeral = ed25519GenerateKeyPair();
+    // 2. X25519 ECDH shared secret
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
+    // 3. Derive stealth scalar → NPK (no commitment — computed on-chain)
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    const recipientMPK = bytesToBigint(recipientMeta.mpk);
+    const npkBigint = computeNPKSync(recipientMPK, stealthScalar);
+    const npk = bigintToBytes(npkBigint);
+    const ephemeralPub = new Uint8Array(ephemeral.pubKey);
+    if (userRefundPubkey) {
+        // Refund path: Taproot with script tree containing refund script
+        const { deriveTaprootAddressWithRefund, buildDepositOpReturn } = await import("./taproot");
+        const { address: btcAddress, outputKey, merkleRoot, controlBlock, refundScript, } = deriveTaprootAddressWithRefund(npk, userRefundPubkey, custodyInternalKey, network);
+        // Still build OP_RETURN so the backend can detect the deposit
+        const opReturnPayload = buildDepositOpReturn(ephemeralPub, npk, opReturnContext);
+        return {
+            btcAddress,
+            depositOutputKey: outputKey,
+            opReturnPayload,
+            npk,
+            ephemeralPub,
+            merkleRoot,
+            controlBlock,
+            refundScript,
+        };
+    }
+    // Standard path: key-path-only Taproot address
+    const { deriveTaprootAddress, buildDepositOpReturn } = await import("./taproot");
+    const { address: btcAddress, outputKey } = deriveTaprootAddress(npk, network, custodyInternalKey);
+    const opReturnPayload = buildDepositOpReturn(ephemeralPub, npk, opReturnContext);
+    return {
+        btcAddress,
+        depositOutputKey: outputKey,
+        opReturnPayload,
+        npk,
+        ephemeralPub,
+    };
+}
+/**
+ * Create a non-interactive deposit directly to an Ika-controlled vault.
+ *
+ * The BTC address is the raw Ika x-only Taproot witness program, so Ika can
+ * later sign and spend the UTXO. Privacy/ownership metadata stays per-deposit
+ * in OP_RETURN(header || poolTag || ephemeralPub || npk), and the destination chain
+ * credits the note from that transaction.
+ */
+export async function createDirectVaultDeposit(recipientMeta, vaultXOnlyPubkey, network = "testnet", opReturnContext) {
+    if (!opReturnContext) {
+        throw new Error("deposit OP_RETURN context is required");
+    }
+    if (vaultXOnlyPubkey.length !== 32) {
+        throw new Error("vaultXOnlyPubkey must be 32 bytes");
+    }
+    const viewingPubKey = new Uint8Array(recipientMeta.viewingPubKey);
+    const ephemeral = ed25519GenerateKeyPair();
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, viewingPubKey);
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    const recipientMPK = bytesToBigint(recipientMeta.mpk);
+    const npkBigint = computeNPKSync(recipientMPK, stealthScalar);
+    const npk = bigintToBytes(npkBigint);
+    const ephemeralPub = new Uint8Array(ephemeral.pubKey);
+    const { buildDepositOpReturn } = await import("./taproot");
+    const opReturnPayload = buildDepositOpReturn(ephemeralPub, npk, opReturnContext);
+    return {
+        btcAddress: deriveRawXOnlyP2TRAddress(vaultXOnlyPubkey, network),
+        depositOutputKey: vaultXOnlyPubkey,
+        opReturnPayload,
+        npk,
+        ephemeralPub,
+    };
+}
+/**
+ * Create a non-interactive deposit using the current SDK config.
+ *
+ * Direct-vault/Ika deposit helper.
+ *
+ * Deposits go to the raw Ika x-only P2TR vault address. Recipient binding
+ * stays per-deposit in OP_RETURN(header || poolTag || ephemeralPub || npk), and the destination chain
+ * credits the note by SPV-verifying that deposit transaction directly. Legacy sweep-mode
+ * address derivation is intentionally not selected from config anymore.
+ */
+export async function createDepositFromConfig(recipientMeta, network = "testnet", opReturnContext) {
+    const config = getConfig();
+    const ikaKey = pickIkaCustodyKey(config);
+    if (!ikaKey) {
+        throw new Error("Ika direct-vault deposits require ikaDwalletXOnlyPubkey in config");
+    }
+    if (config.depositMode && !isDirectVaultDepositMode(config.depositMode)) {
+        throw new Error(`Unsupported depositMode "${config.depositMode}"; only Ika direct-vault deposits are supported`);
+    }
+    return createDirectVaultDeposit(recipientMeta, ikaKey, network, opReturnContext);
+}
+export function isDirectVaultDepositMode(mode) {
+    return mode === "direct" || mode === "direct_vault" || mode === "ika_direct";
+}
+/**
+ * Choose the Taproot internal key for deposit-address derivation.
+ * The Ika dWallet x-only pubkey is the sole custody key; throws if unset.
+ * Exported for unit tests; non-test callers should use `createDepositFromConfig`.
+ */
+export function pickCustodyInternalKey(config) {
+    const ikaKey = pickIkaCustodyKey(config);
+    if (!ikaKey) {
+        throw new Error("PoolConfig.ika_dwallet_xonly_pubkey is required; pool custody key is not configured");
+    }
+    return ikaKey;
+}
+export function pickIkaCustodyKey(config) {
+    const ikaHex = config.ikaDwalletXOnlyPubkey ?? "";
+    if (ikaHex && /[1-9a-f]/i.test(ikaHex)) {
+        return hexToBytes(ikaHex);
+    }
+    return null;
+}
+// ========== Recipient Scanning (Viewing Key Only) ==========
+/**
+ * Scan announcements using viewing key only
+ */
+export async function scanAnnouncements(source, announcements, tokenId) {
+    const keys = isWalletAdapter(source) ? await deriveKeysFromWallet(source) : source;
+    const found = [];
+    const MAX_SATS = 21000000n * 100000000n;
+    // Compute MPK for this key set
+    const mpk = computeMPKSync(keys.spendingPubKey.x, keys.spendingPubKey.y, keys.nullifyingKey);
+    for (const ann of announcements) {
+        try {
+            // X25519 ECDH with viewing key
+            const sharedSecret = x25519Ecdh(keys.viewingPrivKey, ann.ephemeralPub);
+            // Decrypt amount
+            const amount = decryptAmount(ann.encryptedAmount, sharedSecret);
+            if (amount <= 0n || amount > MAX_SATS) {
+                continue;
+            }
+            // Derive stealth public key (still needed for spending)
+            const stealthPub = deriveStealthPubKey(keys.spendingPubKey, sharedSecret);
+            // Derive stealth scalar as random for NPK
+            const stealthScalar = deriveStealthScalar(sharedSecret);
+            // Compute expected NPK and commitment (JoinSplit format)
+            const npk = computeNPKSync(mpk, stealthScalar);
+            const expectedCommitment = computeJoinSplitCommitmentSync(npk, tokenId, amount);
+            const actualCommitment = bytesToBigint(ann.commitment);
+            if (expectedCommitment !== actualCommitment) {
+                continue;
+            }
+            found.push({
+                amount,
+                ephemeralPub: ann.ephemeralPub,
+                stealthPub,
+                leafIndex: ann.leafIndex,
+                commitment: ann.commitment,
+            });
+        }
+        catch (error) {
+            // Re-throw programming errors; only skip data/crypto mismatches
+            if (error instanceof TypeError || error instanceof RangeError) {
+                throw error;
+            }
+            continue;
+        }
+    }
+    return found;
+}
+/**
+ * Scan announcements with VIEW-ONLY keys against SEVERAL token ids in one pass.
+ * Same one-ECDH-per-announcement economics as {@link scanUnifiedNotesMulti}.
+ */
+export async function scanAnnouncementsViewOnlyMulti(viewOnlyKeys, announcements, tokenIds) {
+    return matchAnnouncements(viewOnlyKeys, announcements, tokenIds).map((match) => ({
+        amount: match.amount,
+        leafIndex: match.announcement.leafIndex,
+        commitment: match.commitment,
+        ephemeralPub: match.announcement.ephemeralPub,
+        blockTime: match.announcement.blockTime ?? 0,
+        tokenId: match.tokenId,
+    }));
+}
+/**
+ * Scan announcements with VIEW-ONLY keys.
+ * Latest announcement rows must carry an explicit type.
+ */
+export async function scanAnnouncementsViewOnly(viewOnlyKeys, announcements, tokenId) {
+    return scanAnnouncementsViewOnlyMulti(viewOnlyKeys, announcements, [tokenId]);
+}
+/**
+ * Export view-only keys from full UTXOpiaKeys
+ */
+export function exportViewOnlyKeys(keys) {
+    return {
+        viewingPrivKey: keys.viewingPrivKey,
+        spendingPubKey: keys.spendingPubKey,
+        nullifyingKey: keys.nullifyingKey,
+    };
+}
+/**
+ * Encode view-only keys as a hex string for sharing
+ * Format: viewingPrivKey(32) + compressedSpendingPub(32) + nullifyingKey(32) = 96 bytes
+ */
+export function encodeViewOnlyKeys(keys) {
+    const compressed = babyJubCompress(keys.spendingPubKey);
+    const nullBytes = bigintToBytes(keys.nullifyingKey);
+    const combined = new Uint8Array(96);
+    combined.set(keys.viewingPrivKey, 0);
+    combined.set(compressed, 32);
+    combined.set(nullBytes, 64);
+    return bytesToHex(combined);
+}
+/**
+ * Decode view-only keys from a hex string
+ */
+export function decodeViewOnlyKeys(encoded) {
+    const bytes = hexToBytes(encoded);
+    if (bytes.length !== 96) {
+        throw new Error("Invalid view-only key length (expected 96 bytes)");
+    }
+    const viewingPrivKey = bytes.slice(0, 32);
+    const compressed = bytes.slice(32, 64);
+    const spendingPubKey = babyJubDecompress(compressed);
+    const nullifyingKey = bytesToBigint(bytes.slice(64, 96));
+    return { viewingPrivKey, spendingPubKey, nullifyingKey };
+}
+// ========== Claim Preparation (Spending Key Required) ==========
+/**
+ * Prepare claim inputs for ZK proof generation
+ */
+export async function prepareClaimInputs(source, note, merkleProof) {
+    const keys = isWalletAdapter(source) ? await deriveKeysFromWallet(source) : source;
+    // X25519 ECDH to recover shared secret
+    const sharedSecret = x25519Ecdh(keys.viewingPrivKey, note.ephemeralPub);
+    // Derive stealth private key (Baby Jubjub scalar addition)
+    const stealthPrivKey = deriveStealthPrivKey(keys.spendingPrivKey, sharedSecret);
+    // Verify stealth public key matches
+    const expectedStealthPub = babyJubMul(stealthPrivKey, BABYJUB_BASE8);
+    if (expectedStealthPub.x !== note.stealthPub.x || expectedStealthPub.y !== note.stealthPub.y) {
+        throw new Error("Stealth key mismatch - this note may not belong to you or the announcement is invalid");
+    }
+    // Derive the random value (stealth scalar) for NPK
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    // Compute MPK and NPK
+    const mpk = computeMPKSync(keys.spendingPubKey.x, keys.spendingPubKey.y, keys.nullifyingKey);
+    const npk = computeNPKSync(mpk, stealthScalar);
+    // Compute JoinSplit nullifier
+    const nullifier = computeJoinSplitNullifierSync(keys.nullifyingKey, BigInt(note.leafIndex));
+    return {
+        stealthPrivKey,
+        nullifyingKey: keys.nullifyingKey,
+        amount: note.amount,
+        leafIndex: note.leafIndex,
+        merklePath: merkleProof.pathElements,
+        merkleIndices: merkleProof.pathIndices,
+        merkleRoot: merkleProof.root,
+        nullifier,
+        npk,
+        random: stealthScalar,
+    };
+}
+const MAX_SATS = 21000000n * 100000000n;
+/**
+ * Trial-decrypt each announcement ONCE and test the result against every token
+ * id, instead of redoing the whole derivation per token.
+ *
+ * Everything up to the commitment — the x25519 ECDH, the amount, the stealth
+ * scalar, the NPK — is token-independent; only the closing
+ * Poseidon(npk, tokenId, amount) comparison is not. Scanning T tokens the naive
+ * way therefore paid T ECDHs per announcement to answer one question, and the
+ * ECDH is the expensive half.
+ *
+ * A commitment binds exactly one token id, so the first match wins and the
+ * remaining ids are skipped.
+ */
+function matchAnnouncements(viewKeys, announcements, tokenIds) {
+    if (tokenIds.length === 0)
+        return [];
+    const matches = [];
+    const mpk = computeMPKSync(viewKeys.spendingPubKey.x, viewKeys.spendingPubKey.y, viewKeys.nullifyingKey);
+    for (const ann of announcements) {
+        try {
+            if (!isKnownAnnouncementType(ann.announcementType)) {
+                continue;
+            }
+            // X25519 ECDH with viewing key — once per announcement, not per token
+            const sharedSecret = x25519Ecdh(viewKeys.viewingPrivKey, ann.ephemeralPub);
+            // Get amount based on type
+            let amount;
+            if (ann.announcementType === ANNOUNCEMENT_TYPE_DEPOSIT) {
+                // Plaintext u64 LE
+                const view = new DataView(ann.encryptedAmount.buffer, ann.encryptedAmount.byteOffset, 8);
+                amount = view.getBigUint64(0, true);
+            }
+            else {
+                // XOR-encrypted
+                amount = decryptAmount(ann.encryptedAmount, sharedSecret);
+            }
+            if (amount <= 0n || amount > MAX_SATS) {
+                continue;
+            }
+            // Derive stealth scalar and expected NPK (computed locally)
+            const stealthScalar = deriveStealthScalar(sharedSecret);
+            const npk = computeNPKSync(mpk, stealthScalar);
+            const onChain = bytesToBigint(ann.commitment);
+            for (const tokenId of tokenIds) {
+                // Verify the recomputed commitment against the on-chain one for BOTH
+                // deposits and transfers — a foreign transfer whose XOR-decrypted amount
+                // lands in range would otherwise become a phantom note.
+                const commitmentBigint = computeJoinSplitCommitmentSync(npk, tokenId, amount);
+                if (commitmentBigint !== onChain)
+                    continue;
+                matches.push({
+                    announcement: ann,
+                    amount,
+                    tokenId,
+                    // Use on-chain commitment bytes for transfers (preserves exact on-chain value)
+                    commitment: ann.announcementType === ANNOUNCEMENT_TYPE_DEPOSIT
+                        ? bigintToBytes(commitmentBigint)
+                        : new Uint8Array(ann.commitment),
+                    sharedSecret,
+                });
+                break;
+            }
+        }
+        catch (error) {
+            if (error instanceof TypeError || error instanceof RangeError) {
+                throw error;
+            }
+            continue;
+        }
+    }
+    return matches;
+}
+/**
+ * Scan unified StealthAnnouncement notes (both deposits and transfers) against
+ * SEVERAL token ids in one pass.
+ *
+ * Prefer this over calling {@link scanUnifiedNotes} once per token: the cost is
+ * one ECDH per announcement either way, plus one Poseidon per token id tried.
+ */
+export async function scanUnifiedNotesMulti(source, announcements, tokenIds) {
+    const keys = isWalletAdapter(source) ? await deriveKeysFromWallet(source) : source;
+    return matchAnnouncements(exportViewOnlyKeys(keys), announcements, tokenIds).map((match) => ({
+        amount: match.amount,
+        ephemeralPub: match.announcement.ephemeralPub,
+        // Stealth public key, for spending
+        stealthPub: deriveStealthPubKey(keys.spendingPubKey, match.sharedSecret),
+        leafIndex: match.announcement.leafIndex,
+        commitment: match.commitment,
+        blockTime: match.announcement.blockTime ?? 0,
+        tokenId: match.tokenId,
+    }));
+}
+/**
+ * Scan unified StealthAnnouncement notes (both deposits and transfers).
+ *
+ * For each announcement:
+ * - type=0 (deposit): amount is plaintext u64 LE in amount_bytes
+ * - type=1 (transfer): amount is XOR-encrypted in amount_bytes
+ *
+ * Commitment is computed locally: Poseidon(npk, tokenId, amount) and compared
+ * against the on-chain one, which is what proves the note is ours.
+ */
+export async function scanUnifiedNotes(source, announcements, tokenId) {
+    return scanUnifiedNotesMulti(source, announcements, [tokenId]);
+}
+/**
+ * Pack encrypted amount (no y_sign needed for Ed25519 — 32-byte keys, no prefix)
+ *
+ * Layout: bits 0-63 = encrypted amount (little-endian), bit 64 = 0 (reserved)
+ */
+export function packEncryptedAmountWithSign(encryptedAmount, _ySign = false) {
+    if (encryptedAmount.length !== 8) {
+        throw new Error("Encrypted amount must be 8 bytes");
+    }
+    let amount = 0n;
+    for (let i = 7; i >= 0; i--) {
+        amount = (amount << 8n) | BigInt(encryptedAmount[i]);
+    }
+    // For Ed25519, we don't have a y_sign prefix, but keep the bit for compatibility
+    if (_ySign) {
+        amount |= (1n << 64n);
+    }
+    return amount;
+}
+/**
+ * Convert StealthOutputData to circuit-ready format
+ */
+export function packStealthOutputForCircuit(output) {
+    // Ed25519 ephemeral pub is 32 bytes — interpret as big-endian bigint
+    const ephemeralPubX = bytesToBigint(output.ephemeralPub);
+    const encryptedAmountWithSign = packEncryptedAmountWithSign(output.encryptedAmount);
+    return {
+        ephemeralPubX,
+        encryptedAmountWithSign,
+    };
+}
+/**
+ * Unpack encrypted amount from packed Field element
+ */
+export function unpackEncryptedAmountWithSign(packed) {
+    const ySign = (packed & (1n << 64n)) !== 0n;
+    const amount = packed & ((1n << 64n) - 1n);
+    const encryptedAmount = new Uint8Array(8);
+    let temp = amount;
+    for (let i = 0; i < 8; i++) {
+        encryptedAmount[i] = Number(temp & 0xffn);
+        temp >>= 8n;
+    }
+    return { encryptedAmount, ySign };
+}
+/**
+ * Create stealth output data for a self-send (change output)
+ */
+export async function createStealthOutput(keys, amountSats, tokenId) {
+    const ephemeral = ed25519GenerateKeyPair();
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, keys.viewingPubKey);
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    const mpk = computeMPKSync(keys.spendingPubKey.x, keys.spendingPubKey.y, keys.nullifyingKey);
+    const npk = computeNPKSync(mpk, stealthScalar);
+    const commitmentBigint = computeJoinSplitCommitmentSync(npk, tokenId, amountSats);
+    const commitment = bigintToBytes(commitmentBigint);
+    const encryptedAmount = encryptAmount(amountSats, sharedSecret);
+    return {
+        ephemeralPub: new Uint8Array(ephemeral.pubKey),
+        encryptedAmount,
+        commitment,
+    };
+}
+/**
+ * Create stealth output with npk for JoinSplit circuit input
+ */
+export async function createStealthOutputWithKeys(keys, amountSats, tokenId) {
+    const ephemeral = ed25519GenerateKeyPair();
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, keys.viewingPubKey);
+    const stealthScalar = deriveStealthScalar(sharedSecret);
+    const mpk = computeMPKSync(keys.spendingPubKey.x, keys.spendingPubKey.y, keys.nullifyingKey);
+    const npk = computeNPKSync(mpk, stealthScalar);
+    const commitmentBigint = computeJoinSplitCommitmentSync(npk, tokenId, amountSats);
+    const commitment = bigintToBytes(commitmentBigint);
+    const encryptedAmount = encryptAmount(amountSats, sharedSecret);
+    return {
+        ephemeralPub: new Uint8Array(ephemeral.pubKey),
+        encryptedAmount,
+        commitment,
+        stealthPubKeyX: npk,
+        npkBytes: bigintToBytes(npk),
+    };
+}
+/**
+ * Create stealth output data with pre-computed commitment
+ */
+export async function createStealthOutputForCommitment(keys, amountSats, existingCommitment) {
+    const ephemeral = ed25519GenerateKeyPair();
+    const sharedSecret = x25519Ecdh(ephemeral.privKey, keys.viewingPubKey);
+    const encryptedAmount = encryptAmount(amountSats, sharedSecret);
+    return {
+        ephemeralPub: new Uint8Array(ephemeral.pubKey),
+        encryptedAmount,
+        commitment: existingCommitment,
+    };
+}
+// ========== Nullifier Computation ==========
+/**
+ * Compute nullifier hash for a scanned note
+ */
+export function computeNullifierHashForNote(keys, note) {
+    // In JoinSplit model, nullifier = Poseidon(nullifyingKey, leafIndex)
+    // No extra hash layer — the nullifier IS the public output
+    const nullifier = computeJoinSplitNullifierSync(keys.nullifyingKey, BigInt(note.leafIndex));
+    return bigintToBytes(nullifier);
+}
+/**
+ * Compute nullifier hash for a note and return as raw bytes.
+ * Convenience wrapper — avoids importing computeJoinSplitNullifierSync + bigintToBytes in consumers.
+ */
+export function computeNullifierBytes(nullifyingKey, leafIndex) {
+    const nullifier = computeJoinSplitNullifierSync(nullifyingKey, BigInt(leafIndex));
+    return bigintToBytes(nullifier);
+}
+// ========== Announcement Parsing ==========
+/**
+ * Parse backend announcement rows (hex strings) into the format scanUnifiedNotes expects.
+ */
+export function parseAnnouncementsFromHex(rows) {
+    return rows.map((r) => ({
+        announcementType: r.announcement_type,
+        ephemeralPub: hexToBytes(r.ephemeral_pub),
+        encryptedAmount: hexToBytes(r.encrypted_amount),
+        commitment: hexToBytes(r.commitment),
+        leafIndex: r.leaf_index,
+        tokenIdHex: r.token_id ?? undefined,
+    }));
+}
+// ========== Deposit Ownership Check ==========
+/**
+ * Check if a deposit (identified by its OP_RETURN ephemeralPub + npk) belongs
+ * to the given viewing key holder.
+ *
+ * Performs X25519 ECDH between the viewer's private key and the deposit's
+ * ephemeral public key, derives the expected NPK, and compares it with the
+ * deposit's actual NPK.
+ */
+export function isDepositForViewer(viewingPrivKey, spendingPubKey, nullifyingKey, ephemeralPub, depositNpk) {
+    try {
+        const sharedSecret = x25519Ecdh(viewingPrivKey, ephemeralPub);
+        const mpk = computeMPKSync(spendingPubKey.x, spendingPubKey.y, nullifyingKey);
+        const stealthScalar = deriveStealthScalar(sharedSecret);
+        const expectedNpk = computeNPKSync(mpk, stealthScalar);
+        return expectedNpk === depositNpk;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if a deposit belongs to this viewer — accepts hex string inputs.
+ * Convenience wrapper around isDepositForViewer for frontend use.
+ */
+export function isDepositForViewerHex(keys, ephemeralPubHex, npkHex) {
+    try {
+        const ephPub = hexToBytes(ephemeralPubHex);
+        const npk = bytesToBigint(hexToBytes(npkHex));
+        return isDepositForViewer(keys.viewingPrivKey, keys.spendingPubKey, keys.nullifyingKey, ephPub, npk);
+    }
+    catch {
+        return false;
+    }
+}