@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/dist/stealth.d.ts

@@ -0,0 +1,429 @@
+/**
+ * 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
+ */
+/** Announcement type: deposit (plaintext amount) */
+export declare const ANNOUNCEMENT_TYPE_DEPOSIT = 0;
+/** Announcement type: transfer (XOR-encrypted amount) */
+export declare const ANNOUNCEMENT_TYPE_TRANSFER = 1;
+import { type BabyJubPoint } from "./crypto";
+import type { StealthMetaAddress, UTXOpiaKeys, WalletSignerAdapter } from "./keys";
+import type { DepositOpReturnContext } from "./taproot";
+/**
+ * Encrypt amount using XOR with shared secret
+ */
+export declare function encryptAmount(amount: bigint, sharedSecret: Uint8Array): Uint8Array;
+/**
+ * Decrypt amount using XOR with shared secret
+ */
+export declare function decryptAmount(encryptedAmount: Uint8Array, sharedSecret: Uint8Array): bigint;
+export { encryptNoteData, decryptNoteData } from "./crypto-ed25519";
+/**
+ * Type guard to distinguish between WalletSignerAdapter and UTXOpiaKeys
+ */
+export declare function isWalletAdapter(source: unknown): source is WalletSignerAdapter;
+/**
+ * Stealth Deposit with single Ed25519 ephemeral key
+ */
+export interface StealthDeposit {
+    /** Ed25519 ephemeral public key (32 bytes) */
+    ephemeralPub: Uint8Array;
+    /** Encrypted amount (8 bytes) */
+    encryptedAmount: Uint8Array;
+    /** Commitment for Merkle tree (32 bytes) - Poseidon(stealthPub.x, amount) */
+    commitment: Uint8Array;
+    /** Unix timestamp when created */
+    createdAt: number;
+}
+/**
+ * Scanned note from announcement (viewing key can detect)
+ */
+export interface ScannedNote {
+    /** Amount in satoshis */
+    amount: bigint;
+    /** Ed25519 ephemeral public key (needed for shared secret) */
+    ephemeralPub: Uint8Array;
+    /** Computed stealth public key (Baby Jubjub) */
+    stealthPub: BabyJubPoint;
+    /** Leaf index in Merkle tree */
+    leafIndex: number;
+    /** Original announcement commitment */
+    commitment: Uint8Array;
+    /** Unix timestamp (seconds) from on-chain block_time, 0 if unavailable */
+    blockTime?: number;
+}
+/**
+ * Prepared claim inputs for JoinSplit ZK proof (requires spending key)
+ */
+export interface ClaimInputs {
+    stealthPrivKey: bigint;
+    nullifyingKey: bigint;
+    amount: bigint;
+    leafIndex: number;
+    merklePath: bigint[];
+    merkleIndices: number[];
+    merkleRoot: bigint;
+    nullifier: bigint;
+    npk: bigint;
+    random: bigint;
+}
+/**
+ * Parsed stealth announcement from on-chain data
+ */
+export interface OnChainStealthAnnouncement {
+    /** 0 = deposit (plaintext amount), 1 = transfer (encrypted amount) */
+    announcementType: number;
+    ephemeralPub: Uint8Array;
+    /** Raw amount bytes: plaintext if type=0, encrypted if type=1 */
+    encryptedAmount: Uint8Array;
+    /** Commitment = Poseidon(npk, token, amount) stored on-chain */
+    commitment: Uint8Array;
+    leafIndex: number;
+    /** Unix timestamp (seconds) from on-chain block_time, 0 if unavailable */
+    blockTime?: number;
+    /** Solana slot the announcement was emitted in. Needed for auditor slot-range scoping. */
+    slot?: number;
+    /** Token id hex from the backend indexer, when available. */
+    tokenIdHex?: string;
+}
+/**
+ * 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 declare function createStealthDeposit(recipientMeta: StealthMetaAddress, amountSats: bigint, tokenId: bigint): Promise<StealthDeposit>;
+/**
+ * Extended stealth output data including the derived stealth pub key
+ */
+export interface StealthOutputWithKeys extends StealthOutputData {
+    stealthPubKeyX: bigint;
+    /** npk as 32-byte LE Uint8Array — ready for on-chain instruction data */
+    npkBytes: Uint8Array;
+}
+/**
+ * Create stealth deposit with npk for JoinSplit circuit input
+ */
+export declare function createStealthDepositWithKeys(recipientMeta: StealthMetaAddress, amountSats: bigint, tokenId: bigint): Promise<StealthOutputWithKeys>;
+/**
+ * Result of a non-interactive deposit preparation.
+ * Contains everything needed to build a PSBT with an OP_RETURN output.
+ *
+ * npk-based flow: user can send any amount of BTC. The commitment is
+ * computed on-chain from npk + actual amount.
+ */
+export interface NonInteractiveDepositResult {
+    /** Taproot address to send BTC to */
+    btcAddress: string;
+    /** 32-byte x-only output key for the deposit P2TR output */
+    depositOutputKey: Uint8Array;
+    /** 73-byte OP_RETURN payload: header || poolTag || ephemeralPub || npk */
+    opReturnPayload: Uint8Array;
+    /** 32-byte note public key (for tracking) */
+    npk: Uint8Array;
+    /** 32-byte Ed25519 ephemeral public key */
+    ephemeralPub: Uint8Array;
+}
+/**
+ * Extended result when a user refund pubkey is provided.
+ * Includes Taproot script-path data for the refund spending path.
+ */
+export interface NonInteractiveDepositWithRefundResult extends NonInteractiveDepositResult {
+    /** 32-byte Merkle root (TapLeaf hash of the refund script) */
+    merkleRoot: Uint8Array;
+    /** 33-byte control block for script-path spend (leaf_version|parity + internal_key) */
+    controlBlock: Uint8Array;
+    /** 73-byte refund script */
+    refundScript: Uint8Array;
+}
+/**
+ * Create a non-interactive stealth deposit (npk-based).
+ *
+ * This is the client-side-only deposit flow: no backend API call needed.
+ * The ephemeral key and npk are embedded in the BTC transaction's OP_RETURN
+ * output so the backend can passively detect them.
+ *
+ * The user can send ANY amount of BTC — the commitment is computed on-chain
+ * from the npk + actual BTC amount received.
+ *
+ * When `userRefundPubkey` is provided, the Taproot address includes a
+ * script-path with a time-locked refund spending condition (144 blocks).
+ *
+ * @param recipientMeta - Recipient's stealth meta-address
+ * @param custodyInternalKey - Pool custody x-only pubkey (32 bytes), used as the Taproot internal key
+ * @param network - Bitcoin network for address encoding
+ * @param userRefundPubkey - Optional 32-byte x-only pubkey for refund script path
+ */
+export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAddress, custodyInternalKey: Uint8Array, network?: "mainnet" | "testnet" | "regtest", userRefundPubkey?: undefined, opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+export declare function createNonInteractiveDeposit(recipientMeta: StealthMetaAddress, custodyInternalKey: Uint8Array, network: "mainnet" | "testnet" | "regtest", userRefundPubkey: Uint8Array, opReturnContext: DepositOpReturnContext): Promise<NonInteractiveDepositWithRefundResult>;
+/**
+ * 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 declare function createDirectVaultDeposit(recipientMeta: StealthMetaAddress, vaultXOnlyPubkey: Uint8Array, network?: "mainnet" | "testnet" | "regtest", opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+/**
+ * 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 declare function createDepositFromConfig(recipientMeta: StealthMetaAddress, network?: "mainnet" | "testnet" | "regtest", opReturnContext?: DepositOpReturnContext): Promise<NonInteractiveDepositResult>;
+export declare function isDirectVaultDepositMode(mode?: string): boolean;
+/**
+ * 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 declare function pickCustodyInternalKey(config: {
+    ikaDwalletXOnlyPubkey?: string;
+}): Uint8Array;
+export declare function pickIkaCustodyKey(config: {
+    ikaDwalletXOnlyPubkey?: string;
+}): Uint8Array | null;
+/**
+ * Scan announcements using viewing key only
+ */
+export declare function scanAnnouncements(source: WalletSignerAdapter | UTXOpiaKeys, announcements: {
+    ephemeralPub: Uint8Array;
+    encryptedAmount: Uint8Array;
+    commitment: Uint8Array;
+    leafIndex: number;
+}[], tokenId: bigint): Promise<ScannedNote[]>;
+/**
+ * View-only keys for scanning without spending capability
+ */
+export interface ViewOnlyKeys {
+    /** Ed25519 viewing private key (32 bytes) */
+    viewingPrivKey: Uint8Array;
+    /** Baby Jubjub spending public key */
+    spendingPubKey: BabyJubPoint;
+    /** Nullifying key (needed for MPK computation in JoinSplit scanning) */
+    nullifyingKey: bigint;
+}
+/**
+ * Scanned note from view-only scanning
+ */
+export interface ViewOnlyScannedNote {
+    amount: bigint;
+    leafIndex: number;
+    commitment: Uint8Array;
+    ephemeralPub: Uint8Array;
+    /** Unix timestamp (seconds) from on-chain block_time, 0 if unavailable */
+    blockTime?: number;
+}
+/**
+ * Scan announcements with VIEW-ONLY keys against SEVERAL token ids in one pass.
+ * Same one-ECDH-per-announcement economics as {@link scanUnifiedNotesMulti}.
+ */
+export declare function scanAnnouncementsViewOnlyMulti(viewOnlyKeys: ViewOnlyKeys, announcements: {
+    announcementType: number;
+    ephemeralPub: Uint8Array;
+    encryptedAmount: Uint8Array;
+    commitment: Uint8Array;
+    leafIndex: number;
+    blockTime?: number;
+}[], tokenIds: bigint[]): Promise<Array<ViewOnlyScannedNote & {
+    tokenId: bigint;
+}>>;
+/**
+ * Scan announcements with VIEW-ONLY keys.
+ * Latest announcement rows must carry an explicit type.
+ */
+export declare function scanAnnouncementsViewOnly(viewOnlyKeys: ViewOnlyKeys, announcements: {
+    announcementType: number;
+    ephemeralPub: Uint8Array;
+    encryptedAmount: Uint8Array;
+    commitment: Uint8Array;
+    leafIndex: number;
+    blockTime?: number;
+}[], tokenId: bigint): Promise<ViewOnlyScannedNote[]>;
+/**
+ * Export view-only keys from full UTXOpiaKeys
+ */
+export declare function exportViewOnlyKeys(keys: UTXOpiaKeys): ViewOnlyKeys;
+/**
+ * Encode view-only keys as a hex string for sharing
+ * Format: viewingPrivKey(32) + compressedSpendingPub(32) + nullifyingKey(32) = 96 bytes
+ */
+export declare function encodeViewOnlyKeys(keys: ViewOnlyKeys): string;
+/**
+ * Decode view-only keys from a hex string
+ */
+export declare function decodeViewOnlyKeys(encoded: string): ViewOnlyKeys;
+/**
+ * Prepare claim inputs for ZK proof generation
+ */
+export declare function prepareClaimInputs(source: WalletSignerAdapter | UTXOpiaKeys, note: ScannedNote, merkleProof: {
+    root: bigint;
+    pathElements: bigint[];
+    pathIndices: number[];
+}): Promise<ClaimInputs>;
+/** A note found by a multi-token scan, tagged with the token id it matched. */
+export type MultiScannedNote = ScannedNote & {
+    tokenId: bigint;
+};
+/**
+ * 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 declare function scanUnifiedNotesMulti(source: WalletSignerAdapter | UTXOpiaKeys, announcements: OnChainStealthAnnouncement[], tokenIds: bigint[]): Promise<MultiScannedNote[]>;
+/**
+ * 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 declare function scanUnifiedNotes(source: WalletSignerAdapter | UTXOpiaKeys, announcements: OnChainStealthAnnouncement[], tokenId: bigint): Promise<ScannedNote[]>;
+import type { Address } from "@solana/kit";
+export interface ConnectionAdapter {
+    getAccountInfo: (pubkey: Address) => Promise<{
+        data: Uint8Array;
+    } | null>;
+}
+export interface StealthOutputData {
+    /** Ed25519 ephemeral public key (32 bytes) */
+    ephemeralPub: Uint8Array;
+    /** XOR encrypted amount (8 bytes) */
+    encryptedAmount: Uint8Array;
+    /** Commitment = Poseidon(stealthPub.x, amount) */
+    commitment: Uint8Array;
+}
+/**
+ * Circuit-ready stealth output data
+ */
+export interface CircuitStealthOutput {
+    /** Ephemeral pubkey (32 bytes as bigint) */
+    ephemeralPubX: bigint;
+    /** Packed: bits 0-63 = encrypted amount, bit 64 = reserved (0 for Ed25519) */
+    encryptedAmountWithSign: bigint;
+}
+/**
+ * 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 declare function packEncryptedAmountWithSign(encryptedAmount: Uint8Array, _ySign?: boolean): bigint;
+/**
+ * Convert StealthOutputData to circuit-ready format
+ */
+export declare function packStealthOutputForCircuit(output: StealthOutputData): CircuitStealthOutput;
+/**
+ * Unpack encrypted amount from packed Field element
+ */
+export declare function unpackEncryptedAmountWithSign(packed: bigint): {
+    encryptedAmount: Uint8Array;
+    ySign: boolean;
+};
+/**
+ * Create stealth output data for a self-send (change output)
+ */
+export declare function createStealthOutput(keys: UTXOpiaKeys, amountSats: bigint, tokenId: bigint): Promise<StealthOutputData>;
+/**
+ * Create stealth output with npk for JoinSplit circuit input
+ */
+export declare function createStealthOutputWithKeys(keys: UTXOpiaKeys, amountSats: bigint, tokenId: bigint): Promise<StealthOutputWithKeys>;
+/**
+ * Create stealth output data with pre-computed commitment
+ */
+export declare function createStealthOutputForCommitment(keys: UTXOpiaKeys, amountSats: bigint, existingCommitment: Uint8Array): Promise<StealthOutputData>;
+/**
+ * Compute nullifier hash for a scanned note
+ */
+export declare function computeNullifierHashForNote(keys: UTXOpiaKeys, note: ScannedNote): Uint8Array;
+/**
+ * Compute nullifier hash for a note and return as raw bytes.
+ * Convenience wrapper — avoids importing computeJoinSplitNullifierSync + bigintToBytes in consumers.
+ */
+export declare function computeNullifierBytes(nullifyingKey: bigint, leafIndex: number): Uint8Array;
+/**
+ * Parse backend announcement rows (hex strings) into the format scanUnifiedNotes expects.
+ */
+export declare function parseAnnouncementsFromHex(rows: Array<{
+    announcement_type: number;
+    ephemeral_pub: string;
+    encrypted_amount: string;
+    commitment: string;
+    leaf_index: number;
+    token_id?: string | null;
+}>): Array<{
+    announcementType: number;
+    ephemeralPub: Uint8Array;
+    encryptedAmount: Uint8Array;
+    commitment: Uint8Array;
+    leafIndex: number;
+    tokenIdHex?: string;
+}>;
+/**
+ * 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 declare function isDepositForViewer(viewingPrivKey: Uint8Array, spendingPubKey: {
+    x: bigint;
+    y: bigint;
+}, nullifyingKey: bigint, ephemeralPub: Uint8Array, depositNpk: bigint): boolean;
+/**
+ * Check if a deposit belongs to this viewer — accepts hex string inputs.
+ * Convenience wrapper around isDepositForViewer for frontend use.
+ */
+export declare function isDepositForViewerHex(keys: {
+    viewingPrivKey: Uint8Array;
+    spendingPubKey: {
+        x: bigint;
+        y: bigint;
+    };
+    nullifyingKey: bigint;
+}, ephemeralPubHex: string, npkHex: string): boolean;