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

package/src/crypto.ts

@@ -0,0 +1,199 @@
+/**
+ * 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,
+  type BabyJubPoint,
+} 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(): bigint {
+  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: bigint): Uint8Array {
+  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: Uint8Array): bigint {
+  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: string): Uint8Array {
+  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: Uint8Array): string {
+  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: Uint8Array): Uint8Array {
+  return sha256(data);
+}
+
+/**
+ * Double SHA256 hash (Bitcoin standard)
+ */
+export function doubleSha256(data: Uint8Array): Uint8Array {
+  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: string, data: Uint8Array): Uint8Array {
+  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: bigint, p: bigint): bigint {
+  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: Uint8Array): bigint {
+  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: bigint): Uint8Array {
+  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/src/event-client.ts

@@ -0,0 +1,231 @@
+/**
+ * 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,
+  type AnnouncementClientConfig,
+} from "./announcement-client";
+import type { OnChainStealthAnnouncement } from "./stealth";
+import { hexToBytes } from "./crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+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;
+}
+
+// ---------------------------------------------------------------------------
+// EventClient
+// ---------------------------------------------------------------------------
+
+export class EventClient extends AnnouncementClient {
+  private treeListeners = new Set<EventListener<LeafInsertedEvent>>();
+  private nullifierListeners = new Set<EventListener<NullifierSpentEvent>>();
+  private spentNullifiers = new Set<string>();
+  private nullifierLatestSlot = 0;
+
+  /** Subscribe to tree (leaf_inserted) events */
+  onTreeUpdate(listener: EventListener<LeafInsertedEvent>): () => void {
+    this.treeListeners.add(listener);
+    return () => this.treeListeners.delete(listener);
+  }
+
+  /** Subscribe to nullifier (nullifier_spent) events */
+  onNullifierSpent(listener: EventListener<NullifierSpentEvent>): () => void {
+    this.nullifierListeners.add(listener);
+    return () => this.nullifierListeners.delete(listener);
+  }
+
+  /** Fetch tree status from backend */
+  async fetchTreeStatus(): Promise<TreeStatusResponse | null> {
+    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()) as TreeStatusResponse;
+    } catch {
+      return null;
+    }
+  }
+
+  /** Fetch spent nullifier PDAs with incremental caching */
+  async fetchSpentNullifiers(): Promise<Set<string>> {
+    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: NullifierPdasResponse = 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: string): boolean {
+    return this.spentNullifiers.has(pda);
+  }
+
+  /** Stop client, close WS, clear extra listeners */
+  close(): void {
+    super.close();
+    this.treeListeners.clear();
+    this.nullifierListeners.clear();
+  }
+
+  // -----------------------------------------------------------------------
+  // Override: connect to /ws/events instead of /ws/announcements
+  // -----------------------------------------------------------------------
+
+  protected connectWs(): void {
+    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: ServerEvent = 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
+  // -----------------------------------------------------------------------
+
+  private dispatchEvent(event: ServerEvent): void {
+    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;
+    }
+  }
+
+  private handleAnnouncementEvent(event: AnnouncementEvent): void {
+    const announcement: OnChainStealthAnnouncement = {
+      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
+      }
+    }
+  }
+}