@utxopia/sdk 0.1.0-alpha.1

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

@@ -0,0 +1,59 @@
+/**
+ * Cryptographic utilities for UTXOpia
+ *
+ * This module provides:
+ * - Field constants (BN254)
+ * - Byte conversion utilities
+ * - SHA-256 and tagged hashing
+ * - Re-exports from Baby Jubjub (spending keys) and Ed25519 (viewing keys)
+ *
+ * Baby Jubjub: Twisted Edwards curve for SNARK-friendly spending key operations
+ * Ed25519/X25519: Fast standard curve for viewing key ECDH (off-chain only)
+ *
+ * @module crypto
+ */
+/** BN254 field prime (used by circom/snarkjs, also Baby Jubjub base field) */
+export declare const BN254_FIELD_PRIME = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+export { BABYJUB_FIELD_PRIME, BABYJUB_A, BABYJUB_D, BABYJUB_ORDER, BABYJUB_BASE8, BABYJUB_IDENTITY, babyJubAdd, babyJubDouble, babyJubMul, babyJubNegate, isOnBabyJubCurve, isIdentity, babyJubCompress, babyJubDecompress, generateBabyJubKeyPair, deriveBabyJubKeyFromSeed, babyJubScalarFromBytes, babyJubScalarToBytes, type BabyJubPoint, } from "./crypto-babyjub";
+export { ed25519GenerateKeyPair, ed25519GetPublicKey, ed25519DeriveKeyFromSeed, ed25519PubToX25519, ed25519PrivToX25519, x25519Ecdh, x25519PubFromPriv, x25519EcdhRaw, deriveAmountKey, encryptAmountEd25519, decryptAmountEd25519, encryptNoteData, decryptNoteData, } from "./crypto-ed25519";
+/**
+ * Generate a random field element (< BN254 prime)
+ */
+export declare function randomFieldElement(): bigint;
+/**
+ * Convert bigint to 32-byte Uint8Array (big-endian)
+ */
+export declare function bigintToBytes(value: bigint): Uint8Array;
+/**
+ * Convert Uint8Array to bigint (big-endian)
+ */
+export declare function bytesToBigint(bytes: Uint8Array): bigint;
+/**
+ * Convert hex string to Uint8Array
+ */
+export declare function hexToBytes(hex: string): Uint8Array;
+/**
+ * Convert Uint8Array to hex string
+ */
+export declare function bytesToHex(bytes: Uint8Array): string;
+/**
+ * SHA-256 hash using @noble/hashes
+ */
+export declare function sha256Hash(data: Uint8Array): Uint8Array;
+/**
+ * Double SHA256 hash (Bitcoin standard)
+ */
+export declare function doubleSha256(data: Uint8Array): Uint8Array;
+/**
+ * Tagged hash as used in BIP-340/341 (Taproot)
+ * H_tag(x) = SHA256(SHA256(tag) || SHA256(tag) || x)
+ */
+export declare function taggedHash(tag: string, data: Uint8Array): Uint8Array;
+/**
+ * Derive a scalar from bytes (reduces modulo Baby Jubjub subgroup order)
+ */
+export declare function scalarFromBytes(bytes: Uint8Array): bigint;
+/**
+ * Convert a bigint scalar to 32 bytes (big-endian)
+ */
+export declare function scalarToBytes(scalar: bigint): Uint8Array;

package/packages/sdk/dist/crypto.js

@@ -0,0 +1,140 @@
+/**
+ * Cryptographic utilities for UTXOpia
+ *
+ * This module provides:
+ * - Field constants (BN254)
+ * - Byte conversion utilities
+ * - SHA-256 and tagged hashing
+ * - Re-exports from Baby Jubjub (spending keys) and Ed25519 (viewing keys)
+ *
+ * Baby Jubjub: Twisted Edwards curve for SNARK-friendly spending key operations
+ * Ed25519/X25519: Fast standard curve for viewing key ECDH (off-chain only)
+ *
+ * @module crypto
+ */
+import { sha256 } from "@noble/hashes/sha2.js";
+// =============================================================================
+// Field Constants
+// =============================================================================
+/** BN254 field prime (used by circom/snarkjs, also Baby Jubjub base field) */
+export const BN254_FIELD_PRIME = 21888242871839275222246405745257275088548364400416034343698204186575808495617n;
+// =============================================================================
+// Re-exports from Baby Jubjub (spending keys)
+// =============================================================================
+export { BABYJUB_FIELD_PRIME, BABYJUB_A, BABYJUB_D, BABYJUB_ORDER, BABYJUB_BASE8, BABYJUB_IDENTITY, babyJubAdd, babyJubDouble, babyJubMul, babyJubNegate, isOnBabyJubCurve, isIdentity, babyJubCompress, babyJubDecompress, generateBabyJubKeyPair, deriveBabyJubKeyFromSeed, babyJubScalarFromBytes, babyJubScalarToBytes, } from "./crypto-babyjub";
+// =============================================================================
+// Re-exports from Ed25519 (viewing keys)
+// =============================================================================
+export { ed25519GenerateKeyPair, ed25519GetPublicKey, ed25519DeriveKeyFromSeed, ed25519PubToX25519, ed25519PrivToX25519, x25519Ecdh, x25519PubFromPriv, x25519EcdhRaw, deriveAmountKey, encryptAmountEd25519, decryptAmountEd25519, encryptNoteData, decryptNoteData, } from "./crypto-ed25519";
+// =============================================================================
+// Byte Conversion Utilities
+// =============================================================================
+/**
+ * Generate a random field element (< BN254 prime)
+ */
+export function randomFieldElement() {
+    const bytes = new Uint8Array(32);
+    crypto.getRandomValues(bytes);
+    return bytesToBigint(bytes) % BN254_FIELD_PRIME;
+}
+/**
+ * Convert bigint to 32-byte Uint8Array (big-endian)
+ */
+export function bigintToBytes(value) {
+    const bytes = new Uint8Array(32);
+    let temp = value;
+    for (let i = 31; i >= 0; i--) {
+        bytes[i] = Number(temp & 0xffn);
+        temp = temp >> 8n;
+    }
+    return bytes;
+}
+/**
+ * Convert Uint8Array to bigint (big-endian)
+ */
+export function bytesToBigint(bytes) {
+    let result = 0n;
+    for (let i = 0; i < bytes.length; i++) {
+        result = (result << 8n) | BigInt(bytes[i]);
+    }
+    return result;
+}
+/**
+ * Convert hex string to Uint8Array
+ */
+export function hexToBytes(hex) {
+    const cleanHex = hex.startsWith("0x") ? hex.slice(2) : hex;
+    const bytes = new Uint8Array(cleanHex.length / 2);
+    for (let i = 0; i < cleanHex.length; i += 2) {
+        bytes[i / 2] = parseInt(cleanHex.substr(i, 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Convert Uint8Array to hex string
+ */
+export function bytesToHex(bytes) {
+    return Array.from(bytes)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+// =============================================================================
+// Hashing Utilities
+// =============================================================================
+/**
+ * SHA-256 hash using @noble/hashes
+ */
+export function sha256Hash(data) {
+    return sha256(data);
+}
+/**
+ * Double SHA256 hash (Bitcoin standard)
+ */
+export function doubleSha256(data) {
+    return sha256(sha256(data));
+}
+/**
+ * Tagged hash as used in BIP-340/341 (Taproot)
+ * H_tag(x) = SHA256(SHA256(tag) || SHA256(tag) || x)
+ */
+export function taggedHash(tag, data) {
+    const encoder = new TextEncoder();
+    const tagBytes = encoder.encode(tag);
+    const tagHash = sha256(tagBytes);
+    // Concatenate: SHA256(tag) || SHA256(tag) || data
+    const combined = new Uint8Array(64 + data.length);
+    combined.set(tagHash, 0);
+    combined.set(tagHash, 32);
+    combined.set(data, 64);
+    return sha256(combined);
+}
+// =============================================================================
+// Scalar Utilities (curve-agnostic, uses Baby Jubjub order)
+// =============================================================================
+import { BABYJUB_ORDER } from "./crypto-babyjub";
+function mod(n, p) {
+    const result = n % p;
+    return result >= 0n ? result : result + p;
+}
+/**
+ * Derive a scalar from bytes (reduces modulo Baby Jubjub subgroup order)
+ */
+export function scalarFromBytes(bytes) {
+    let result = 0n;
+    for (let i = 0; i < bytes.length; i++) {
+        result = (result << 8n) | BigInt(bytes[i]);
+    }
+    return mod(result, BABYJUB_ORDER);
+}
+/**
+ * Convert a bigint scalar to 32 bytes (big-endian)
+ */
+export function scalarToBytes(scalar) {
+    const bytes = new Uint8Array(32);
+    let temp = mod(scalar, BABYJUB_ORDER);
+    for (let i = 31; i >= 0; i--) {
+        bytes[i] = Number(temp & 0xffn);
+        temp = temp >> 8n;
+    }
+    return bytes;
+}

package/packages/sdk/dist/event-client.d.ts

@@ -0,0 +1,64 @@
+/**
+ * EventClient — Unified event stream client extending AnnouncementClient
+ *
+ * Handles all three backend event types via /ws/events:
+ * - leaf_inserted (tree updates)
+ * - nullifier_spent
+ * - stealth_announcement (delegated to parent AnnouncementClient)
+ *
+ * Also provides REST helpers for tree status and nullifier fetching.
+ */
+import { AnnouncementClient } from "./announcement-client";
+export interface LeafInsertedEvent {
+    type: "leaf_inserted";
+    leaf_index: number;
+    commitment: string;
+    new_root: string;
+}
+export interface NullifierSpentEvent {
+    type: "nullifier_spent";
+    nullifier_hash: string;
+    slot: number;
+}
+export interface AnnouncementEvent {
+    type: "stealth_announcement";
+    announcement_type: number;
+    ephemeral_pub: string;
+    encrypted_amount: string;
+    commitment: string;
+    leaf_index: number;
+    block_time?: number;
+}
+export type ServerEvent = LeafInsertedEvent | NullifierSpentEvent | AnnouncementEvent;
+export type EventListener<T> = (event: T) => void;
+export interface TreeStatusResponse {
+    root: string;
+    next_index: number;
+    size: number;
+}
+export interface NullifierPdasResponse {
+    pdas: string[];
+    total: number;
+    latest_slot: number;
+}
+export declare class EventClient extends AnnouncementClient {
+    private treeListeners;
+    private nullifierListeners;
+    private spentNullifiers;
+    private nullifierLatestSlot;
+    /** Subscribe to tree (leaf_inserted) events */
+    onTreeUpdate(listener: EventListener<LeafInsertedEvent>): () => void;
+    /** Subscribe to nullifier (nullifier_spent) events */
+    onNullifierSpent(listener: EventListener<NullifierSpentEvent>): () => void;
+    /** Fetch tree status from backend */
+    fetchTreeStatus(): Promise<TreeStatusResponse | null>;
+    /** Fetch spent nullifier PDAs with incremental caching */
+    fetchSpentNullifiers(): Promise<Set<string>>;
+    /** Check if a specific nullifier PDA is in the spent set */
+    isNullifierSpent(pda: string): boolean;
+    /** Stop client, close WS, clear extra listeners */
+    close(): void;
+    protected connectWs(): void;
+    private dispatchEvent;
+    private handleAnnouncementEvent;
+}

package/packages/sdk/dist/event-client.js

@@ -0,0 +1,165 @@
+/**
+ * EventClient — Unified event stream client extending AnnouncementClient
+ *
+ * Handles all three backend event types via /ws/events:
+ * - leaf_inserted (tree updates)
+ * - nullifier_spent
+ * - stealth_announcement (delegated to parent AnnouncementClient)
+ *
+ * Also provides REST helpers for tree status and nullifier fetching.
+ */
+import { AnnouncementClient, } from "./announcement-client";
+import { hexToBytes } from "./crypto";
+// ---------------------------------------------------------------------------
+// EventClient
+// ---------------------------------------------------------------------------
+export class EventClient extends AnnouncementClient {
+    constructor() {
+        super(...arguments);
+        this.treeListeners = new Set();
+        this.nullifierListeners = new Set();
+        this.spentNullifiers = new Set();
+        this.nullifierLatestSlot = 0;
+    }
+    /** Subscribe to tree (leaf_inserted) events */
+    onTreeUpdate(listener) {
+        this.treeListeners.add(listener);
+        return () => this.treeListeners.delete(listener);
+    }
+    /** Subscribe to nullifier (nullifier_spent) events */
+    onNullifierSpent(listener) {
+        this.nullifierListeners.add(listener);
+        return () => this.nullifierListeners.delete(listener);
+    }
+    /** Fetch tree status from backend */
+    async fetchTreeStatus() {
+        try {
+            const resp = await fetch(`${this.config.backendUrl}/api/tree/status`, { signal: AbortSignal.timeout(this.restTimeout) });
+            if (!resp.ok)
+                return null;
+            return (await resp.json());
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Fetch spent nullifier PDAs with incremental caching */
+    async fetchSpentNullifiers() {
+        try {
+            const since = this.nullifierLatestSlot > 0
+                ? `?since=${this.nullifierLatestSlot}`
+                : "";
+            const resp = await fetch(`${this.config.backendUrl}/api/nullifiers${since}`, { signal: AbortSignal.timeout(this.restTimeout) });
+            if (!resp.ok)
+                return this.spentNullifiers;
+            const data = await resp.json();
+            for (const pda of data.pdas || [])
+                this.spentNullifiers.add(pda);
+            if (data.latest_slot > this.nullifierLatestSlot) {
+                this.nullifierLatestSlot = data.latest_slot;
+            }
+            return this.spentNullifiers;
+        }
+        catch {
+            return this.spentNullifiers;
+        }
+    }
+    /** Check if a specific nullifier PDA is in the spent set */
+    isNullifierSpent(pda) {
+        return this.spentNullifiers.has(pda);
+    }
+    /** Stop client, close WS, clear extra listeners */
+    close() {
+        super.close();
+        this.treeListeners.clear();
+        this.nullifierListeners.clear();
+    }
+    // -----------------------------------------------------------------------
+    // Override: connect to /ws/events instead of /ws/announcements
+    // -----------------------------------------------------------------------
+    connectWs() {
+        if (this.closed)
+            return;
+        try {
+            const url = `${this.wsUrl}/ws/events`;
+            this.ws = new WebSocket(url);
+            this.ws.onopen = () => {
+                this.wsConnected = true;
+                this.wsReconnectDelay = 1000;
+            };
+            this.ws.onmessage = (event) => {
+                try {
+                    const data = JSON.parse(typeof event.data === "string" ? event.data : "");
+                    this.dispatchEvent(data);
+                }
+                catch {
+                    // Ignore malformed messages
+                }
+            };
+            this.ws.onclose = () => {
+                this.wsConnected = false;
+                this.ws = null;
+                this.scheduleReconnect();
+            };
+            this.ws.onerror = () => {
+                // onclose will fire after onerror
+            };
+        }
+        catch {
+            this.wsConnected = false;
+            this.scheduleReconnect();
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Internal: route events to appropriate listeners
+    // -----------------------------------------------------------------------
+    dispatchEvent(event) {
+        switch (event.type) {
+            case "stealth_announcement":
+                this.handleAnnouncementEvent(event);
+                break;
+            case "leaf_inserted":
+                for (const listener of this.treeListeners) {
+                    try {
+                        listener(event);
+                    }
+                    catch { /* ignore */ }
+                }
+                break;
+            case "nullifier_spent":
+                for (const listener of this.nullifierListeners) {
+                    try {
+                        listener(event);
+                    }
+                    catch { /* ignore */ }
+                }
+                break;
+        }
+    }
+    handleAnnouncementEvent(event) {
+        const announcement = {
+            announcementType: event.announcement_type,
+            ephemeralPub: hexToBytes(event.ephemeral_pub),
+            encryptedAmount: hexToBytes(event.encrypted_amount),
+            commitment: hexToBytes(event.commitment),
+            leafIndex: event.leaf_index,
+            blockTime: event.block_time ?? 0,
+        };
+        // Update cache (same logic as parent AnnouncementClient.connectWs)
+        if (announcement.leafIndex > this.latestLeafIndex) {
+            this.latestLeafIndex = announcement.leafIndex;
+        }
+        if (!this.cachedAnnouncements.some((a) => a.leafIndex === announcement.leafIndex)) {
+            this.cachedAnnouncements.push(announcement);
+        }
+        // Notify announcement listeners
+        for (const listener of this.listeners) {
+            try {
+                listener([announcement]);
+            }
+            catch {
+                // Listener errors shouldn't crash the client
+            }
+        }
+    }
+}

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

@@ -0,0 +1,127 @@
+/**
+ * Event parser for UTXOpia sol_log_data events
+ *
+ * Events are emitted by the on-chain program as base64-encoded log data.
+ * Transaction logs contain lines like: "Program data: <base64>"
+ * Each base64 segment decodes to one slice from sol_log_data.
+ *
+ * ## Events
+ *
+ * - 0x02 NullifierSpent: disc(1) + hash(32) + op_type(1) = 34 bytes
+ * - 0x03 StealthAnnouncement: disc(1) + type(1) + ephemeral(32) + amount(8) + commitment(32) + leaf_index(4) = 78 bytes
+ * - 0x0B NullifiersBatch: flat payload in single segment
+ * - 0x0C AnnouncementsBatch: flat payload in single segment
+ */
+/** Event discriminators matching contracts/programs/utxopia/src/utils/events.rs */
+export declare const EVENT_NULLIFIER_SPENT = 2;
+export declare const EVENT_STEALTH_ANNOUNCEMENT = 3;
+export declare const EVENT_NULLIFIERS_BATCH = 11;
+export declare const EVENT_ANNOUNCEMENTS_BATCH = 12;
+/** Phase 2: sender memo (XChaCha20-Poly1305 AEAD payload). */
+export declare const EVENT_SENDER_MEMO = 18;
+export declare const EVENT_BTC_ORIGIN_ATTESTATION = 21;
+/** Method-Y: auditor ciphertext emitted alongside every shielded deposit into a permissioned pool. */
+export declare const EVENT_AUDITOR_CIPHERTEXT = 22;
+/** Parsed nullifier spent event */
+export interface NullifierSpentEvent {
+    type: "nullifier_spent";
+    nullifierHash: Uint8Array;
+    operationType: number;
+}
+/** Parsed stealth announcement event (includes token_id) */
+export interface StealthAnnouncementEvent {
+    type: "stealth_announcement";
+    announcementType: number;
+    ephemeralPub: Uint8Array;
+    encryptedAmount: Uint8Array;
+    commitment: Uint8Array;
+    leafIndex: number;
+    tokenId?: Uint8Array;
+}
+/** Parsed sender memo event (Phase 2). */
+export interface SenderMemoEvent {
+    type: "sender_memo";
+    /** 24-byte XChaCha20 nonce. */
+    nonce: Uint8Array;
+    /** 56-byte ChaCha20 ciphertext + Poly1305 tag. */
+    ciphertextWithTag: Uint8Array;
+    /** Commitment of the output this memo covers (also AAD). */
+    commitment: Uint8Array;
+    /** Leaf index of the covered output (also AAD). */
+    leafIndex: number;
+}
+/**
+ * BTC origin attestation, emitted alongside every SPV-verified deposit.
+ * Lets third-party auditors anchor commitments to their on-chain BTC
+ * origin without trusting our backend.
+ *
+ * Layout matches the Rust `emit_btc_origin_attestation` in
+ * `contracts/programs/utxopia/src/utils/events.rs`.
+ */
+export interface BtcOriginAttestationEvent {
+    type: "btc_origin_attestation";
+    blockHeight: bigint;
+    /** Bitcoin deposit txid in internal byte order (same as `complete_deposit` instruction data). */
+    depositTxid: Uint8Array;
+    /** Sweep transaction's output index that paid the pool. */
+    sweepVout: number;
+    /** Commitment inserted into the JoinSplit tree for this deposit. */
+    commitment: Uint8Array;
+    /** Pool-received amount in satoshis (after sweep fees). */
+    amountSats: bigint;
+}
+/**
+ * Auditor ciphertext event (Method-Y permissioned pools).
+ *
+ * Emitted alongside every shielded deposit into a permissioned pool so that
+ * a designated auditor can decrypt note viewing data off-chain.
+ */
+export interface AuditorCiphertextEvent {
+    type: "auditor_ciphertext";
+    /** 32-byte Poseidon commitment of the shielded note. */
+    commitment: Uint8Array;
+    /** 112-byte encrypted blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56). */
+    blob: Uint8Array;
+}
+export type ProgramEvent = NullifierSpentEvent | StealthAnnouncementEvent | SenderMemoEvent | BtcOriginAttestationEvent | AuditorCiphertextEvent;
+/**
+ * Parse a nullifier spent event from decoded sol_log_data segments.
+ * Expected: disc(1) + nullifier_hash(32) + op_type(1)
+ */
+export declare function parseNullifierSpentEvent(segments: Uint8Array[]): NullifierSpentEvent | null;
+/**
+ * Parse a stealth announcement event from decoded sol_log_data segments.
+ * v1: disc(1) + type(1) + ephemeral_pub(32) + encrypted_amount(8) + commitment(32) + leaf_index(4) = 6 segments
+ * v2: + token_id(32) = 7 segments
+ */
+export declare function parseStealthAnnouncementEvent(segments: Uint8Array[]): StealthAnnouncementEvent | null;
+/**
+ * Parse an association-set update event (Phase 3) from decoded sol_log_data segments.
+ * Layout: disc(1) + new_root(32) + status(1) + version_le(8)
+ */
+/**
+ * Parse a BTC origin attestation event from decoded sol_log_data segments.
+ * Layout: disc(1) + block_height(8 LE) + deposit_txid(32) + sweep_vout(4 LE)
+ *       + commitment(32) + amount_sats(8 LE)
+ */
+export declare function parseBtcOriginAttestationEvent(segments: Uint8Array[]): BtcOriginAttestationEvent | null;
+/**
+ * Parse a sender memo event (Phase 2) from decoded sol_log_data segments.
+ * Layout: disc(1) + nonce(24) + ciphertext_and_tag(56) + commitment(32) + leaf_index(4)
+ */
+export declare function parseSenderMemoEvent(segments: Uint8Array[]): SenderMemoEvent | null;
+/**
+ * Parse an auditor ciphertext event (Method-Y) from decoded sol_log_data segments.
+ * Layout: disc(1) + commitment(32) + blob(112)
+ */
+export declare function parseAuditorCiphertextEvent(segments: Uint8Array[]): AuditorCiphertextEvent | null;
+/**
+ * Parse program events from Solana transaction log messages.
+ *
+ * sol_log_data emits log lines in the format:
+ *   "Program data: <base64_segment1> <base64_segment2> ..."
+ *
+ * @param logs - Array of log message strings from a transaction
+ * @param programId - Optional program ID to filter events (matches "Program <id> invoke" blocks)
+ */
+export declare function parseProgramEvents(logs: string[], programId?: string): ProgramEvent[];