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

package/src/announcement-client.ts

@@ -0,0 +1,457 @@
+/**
+ * AnnouncementClient — Production-ready stealth announcement fetcher
+ * with three-tier fallback: Backend WS → Backend REST → Direct RPC.
+ *
+ * - Backend WS: sub-second push via /ws/announcements
+ * - Backend REST: initial load + catch-up via /api/announcements
+ * - Direct RPC: last resort if backend is unavailable
+ */
+
+import type { OnChainStealthAnnouncement } from "./stealth";
+import { parseProgramEvents } from "./events";
+import { hexToBytes } from "./crypto";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AnnouncementClientConfig {
+  /** Backend REST base URL, e.g. "http://localhost:8080" */
+  backendUrl: string;
+  /** Backend WS base URL — derived from backendUrl if omitted */
+  backendWsUrl?: string;
+  /** Solana RPC URL (for direct RPC fallback) */
+  solanaRpcUrl: string;
+  /** UTXOpia program ID base58 (for direct RPC fallback) */
+  programId: string;
+  /** Commitment tree PDA base58 — query this instead of program ID for fewer results */
+  commitmentTreeAddress?: string;
+  /** REST request timeout in ms (default 5000) */
+  restTimeoutMs?: number;
+  /** Max WS reconnect delay in ms (default 30000) */
+  wsMaxReconnectMs?: number;
+  /** Max leaves backend can lag before supplementing with RPC (default 2) */
+  maxLagLeaves?: number;
+}
+
+export type AnnouncementListener = (
+  announcements: OnChainStealthAnnouncement[],
+) => void;
+
+/** Shape returned by backend /api/announcements */
+interface BackendAnnouncementRow {
+  leaf_index: number;
+  announcement_type: number;
+  ephemeral_pub: string;
+  encrypted_amount: string;
+  commitment: string;
+  tx_signature: string;
+  slot: number;
+  block_time?: number;
+  token_id?: string | null;
+}
+
+interface BackendAnnouncementsResponse {
+  success: boolean;
+  announcements: BackendAnnouncementRow[];
+  count: number;
+  latest_leaf_index: number | null;
+}
+
+interface BackendStatusResponse {
+  count: number;
+  latest_leaf_index: number | null;
+  tree_next_index: number;
+}
+
+/** WS message shape from /ws/announcements */
+interface WsAnnouncementUpdate {
+  type: string;
+  announcement_type: number;
+  ephemeral_pub: string;
+  encrypted_amount: string;
+  commitment: string;
+  leaf_index: number;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function rowToAnnouncement(row: BackendAnnouncementRow): OnChainStealthAnnouncement {
+  return {
+    announcementType: row.announcement_type,
+    ephemeralPub: hexToBytes(row.ephemeral_pub),
+    encryptedAmount: hexToBytes(row.encrypted_amount),
+    commitment: hexToBytes(row.commitment),
+    leafIndex: row.leaf_index,
+    blockTime: row.block_time ?? 0,
+    slot: row.slot,
+    tokenIdHex: row.token_id ?? undefined,
+  };
+}
+
+function wsUpdateToAnnouncement(update: WsAnnouncementUpdate): OnChainStealthAnnouncement {
+  return {
+    announcementType: update.announcement_type,
+    ephemeralPub: hexToBytes(update.ephemeral_pub),
+    encryptedAmount: hexToBytes(update.encrypted_amount),
+    commitment: hexToBytes(update.commitment),
+    leafIndex: update.leaf_index,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// AnnouncementClient
+// ---------------------------------------------------------------------------
+
+export class AnnouncementClient {
+  protected ws: WebSocket | null = null;
+  protected wsReconnectDelay = 1000;
+  protected wsConnected = false;
+  protected listeners = new Set<AnnouncementListener>();
+  protected cachedAnnouncements: OnChainStealthAnnouncement[] = [];
+  protected latestLeafIndex = -1;
+  protected backendHealthy = true;
+  protected closed = false;
+  protected reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private lastRpcFetchAt = 0;
+  private rpcCooldownMs = 30_000; // minimum 30s between RPC fallback calls
+
+  protected restTimeout: number;
+  protected wsMaxReconnect: number;
+  private maxLag: number;
+  protected wsUrl: string;
+
+  constructor(protected config: AnnouncementClientConfig) {
+    this.restTimeout = config.restTimeoutMs ?? 5000;
+    this.wsMaxReconnect = config.wsMaxReconnectMs ?? 30000;
+    this.maxLag = config.maxLagLeaves ?? 2;
+    this.wsUrl =
+      config.backendWsUrl ??
+      config.backendUrl.replace("http://", "ws://").replace("https://", "wss://");
+  }
+
+  // -----------------------------------------------------------------------
+  // Public API
+  // -----------------------------------------------------------------------
+
+  /** Start WS connection and perform initial data load */
+  async start(): Promise<void> {
+    if (this.closed) return;
+    // Initial load via REST (+ RPC fallback)
+    await this.fetchAll();
+    // Open WS for real-time push
+    this.connectWs();
+  }
+
+  /** Fetch all announcements using fallback chain */
+  async fetchAll(): Promise<OnChainStealthAnnouncement[]> {
+    try {
+      const announcements = await this.fetchFromBackend();
+      this.backendHealthy = true;
+      this.cachedAnnouncements = announcements;
+      this.latestLeafIndex = announcements.length > 0
+        ? Math.max(...announcements.map((a) => a.leafIndex))
+        : -1;
+
+      // Consistency check — supplement from RPC if backend is behind
+      await this.checkConsistency();
+      return this.cachedAnnouncements;
+    } catch {
+      this.backendHealthy = false;
+    }
+
+    // Fallback: direct RPC
+    try {
+      const announcements = await this.fetchFromRpc();
+      this.cachedAnnouncements = announcements;
+      this.latestLeafIndex = announcements.length > 0
+        ? Math.max(...announcements.map((a) => a.leafIndex))
+        : -1;
+      return this.cachedAnnouncements;
+    } catch (e) {
+      console.error("[AnnouncementClient] All sources failed:", e);
+      return this.cachedAnnouncements;
+    }
+  }
+
+  /** Subscribe to new announcement events. Returns unsubscribe function. */
+  onAnnouncement(listener: AnnouncementListener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /** Stop client, close WS */
+  close(): void {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+    this.listeners.clear();
+  }
+
+  /** Whether the backend WS is currently connected */
+  get isWsConnected(): boolean {
+    return this.wsConnected;
+  }
+
+  /** Whether the backend REST was reachable on last attempt */
+  get isBackendHealthy(): boolean {
+    return this.backendHealthy;
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal: Backend REST
+  // -----------------------------------------------------------------------
+
+  protected async fetchFromBackend(
+    since?: number,
+  ): Promise<OnChainStealthAnnouncement[]> {
+    const url = since != null
+      ? `${this.config.backendUrl}/api/announcements?since=${since}`
+      : `${this.config.backendUrl}/api/announcements`;
+
+    const resp = await fetch(url, {
+      signal: AbortSignal.timeout(this.restTimeout),
+    });
+
+    if (!resp.ok) throw new Error(`Backend REST ${resp.status}`);
+
+    const data: BackendAnnouncementsResponse = await resp.json();
+    if (!data.success) throw new Error("Backend returned success=false");
+
+    return data.announcements.map(rowToAnnouncement);
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal: Direct RPC fallback
+  // -----------------------------------------------------------------------
+
+  private async fetchFromRpc(
+    since?: number,
+  ): Promise<OnChainStealthAnnouncement[]> {
+    // Cooldown to avoid 429 spam when backend is down
+    const now = Date.now();
+    if (now - this.lastRpcFetchAt < this.rpcCooldownMs) {
+      return this.cachedAnnouncements;
+    }
+    this.lastRpcFetchAt = now;
+
+    // Query commitment tree PDA (only txs that insert leaves = stealth announcements)
+    // Falls back to program ID if commitmentTreeAddress not configured
+    const queryAddress = this.config.commitmentTreeAddress || this.config.programId;
+    const sigsResp = await fetch(this.config.solanaRpcUrl, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "getSignaturesForAddress",
+        params: [queryAddress, { limit: 200 }],
+      }),
+      signal: AbortSignal.timeout(this.restTimeout * 2),
+    });
+
+    const sigsData = await sigsResp.json();
+    const signatures: string[] = (sigsData.result || []).map(
+      (s: { signature: string }) => s.signature,
+    );
+
+    if (signatures.length === 0) return [];
+
+    // Fetch transactions in batches of 10
+    const announcements: OnChainStealthAnnouncement[] = [];
+    const batchSize = 10;
+
+    for (let i = 0; i < signatures.length; i += batchSize) {
+      const batch = signatures.slice(i, i + batchSize);
+      const txResponses = await Promise.all(
+        batch.map((sig) =>
+          fetch(this.config.solanaRpcUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+              jsonrpc: "2.0",
+              id: 1,
+              method: "getTransaction",
+              params: [sig, { encoding: "json", maxSupportedTransactionVersion: 0 }],
+            }),
+          }).then((r) => r.json()),
+        ),
+      );
+
+      for (const txData of txResponses) {
+        const logs: string[] | undefined =
+          txData?.result?.meta?.logMessages;
+        if (!logs) continue;
+
+        const events = parseProgramEvents(logs, this.config.programId);
+        for (const event of events) {
+          if (event.type === "stealth_announcement") {
+            if (since != null && event.leafIndex <= since) continue;
+            announcements.push({
+              announcementType: event.announcementType,
+              ephemeralPub: event.ephemeralPub,
+              encryptedAmount: event.encryptedAmount,
+              commitment: event.commitment,
+              leafIndex: event.leafIndex,
+            });
+          }
+        }
+      }
+    }
+
+    // Deduplicate by leafIndex and sort
+    const seen = new Map<number, OnChainStealthAnnouncement>();
+    for (const a of announcements) {
+      if (!seen.has(a.leafIndex)) seen.set(a.leafIndex, a);
+    }
+    return Array.from(seen.values()).sort((a, b) => a.leafIndex - b.leafIndex);
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal: Consistency check
+  // -----------------------------------------------------------------------
+
+  private async checkConsistency(): Promise<void> {
+    try {
+      const statusResp = await fetch(
+        `${this.config.backendUrl}/api/announcements/status`,
+        { signal: AbortSignal.timeout(this.restTimeout) },
+      );
+      if (!statusResp.ok) return;
+
+      const status: BackendStatusResponse = await statusResp.json();
+      const backendLatest = status.latest_leaf_index ?? -1;
+      const onChainNext = status.tree_next_index;
+
+      // If backend is more than maxLag behind on-chain, supplement from RPC
+      if (onChainNext - 1 - backendLatest > this.maxLag) {
+        console.warn(
+          `[AnnouncementClient] Backend behind: latest=${backendLatest}, on-chain next=${onChainNext}. Supplementing from RPC.`,
+        );
+        const supplement = await this.fetchFromRpc(backendLatest);
+        if (supplement.length > 0) {
+          // Merge: existing + supplement, dedup by leafIndex
+          const merged = new Map<number, OnChainStealthAnnouncement>();
+          for (const a of this.cachedAnnouncements) merged.set(a.leafIndex, a);
+          for (const a of supplement) merged.set(a.leafIndex, a);
+          this.cachedAnnouncements = Array.from(merged.values()).sort(
+            (a, b) => a.leafIndex - b.leafIndex,
+          );
+          this.latestLeafIndex = Math.max(
+            this.latestLeafIndex,
+            ...supplement.map((a) => a.leafIndex),
+          );
+        }
+      }
+    } catch {
+      // Non-fatal — consistency check is best-effort
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Internal: WebSocket
+  // -----------------------------------------------------------------------
+
+  protected connectWs(): void {
+    if (this.closed) return;
+
+    try {
+      const url = `${this.wsUrl}/ws/announcements`;
+      this.ws = new WebSocket(url);
+
+      this.ws.onopen = () => {
+        this.wsConnected = true;
+        this.wsReconnectDelay = 1000; // reset backoff
+      };
+
+      this.ws.onmessage = (event) => {
+        try {
+          const update: WsAnnouncementUpdate = JSON.parse(
+            typeof event.data === "string" ? event.data : "",
+          );
+          if (update.type !== "stealth_announcement") return;
+
+          const announcement = wsUpdateToAnnouncement(update);
+
+          // Update cache
+          if (announcement.leafIndex > this.latestLeafIndex) {
+            this.latestLeafIndex = announcement.leafIndex;
+          }
+          // Avoid duplicates in cache
+          if (!this.cachedAnnouncements.some((a) => a.leafIndex === announcement.leafIndex)) {
+            this.cachedAnnouncements.push(announcement);
+          }
+
+          // Notify listeners
+          for (const listener of this.listeners) {
+            try {
+              listener([announcement]);
+            } catch {
+              // Listener errors shouldn't crash the client
+            }
+          }
+        } 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();
+    }
+  }
+
+  protected scheduleReconnect(): void {
+    if (this.closed) return;
+
+    this.reconnectTimer = setTimeout(async () => {
+      this.reconnectTimer = null;
+      // Fetch missed announcements before reconnecting WS
+      if (this.latestLeafIndex >= 0) {
+        try {
+          const missed = await this.fetchFromBackend(this.latestLeafIndex);
+          if (missed.length > 0) {
+            for (const a of missed) {
+              if (!this.cachedAnnouncements.some((c) => c.leafIndex === a.leafIndex)) {
+                this.cachedAnnouncements.push(a);
+              }
+              if (a.leafIndex > this.latestLeafIndex) {
+                this.latestLeafIndex = a.leafIndex;
+              }
+            }
+            // Notify listeners of catch-up
+            for (const listener of this.listeners) {
+              try { listener(missed); } catch { /* ignore */ }
+            }
+          }
+        } catch {
+          // Backend may still be down
+        }
+      }
+      this.connectWs();
+    }, this.wsReconnectDelay);
+
+    // Exponential backoff
+    this.wsReconnectDelay = Math.min(
+      this.wsReconnectDelay * 2,
+      this.wsMaxReconnect,
+    );
+  }
+}

package/src/auditor-ciphertext.ts

@@ -0,0 +1,181 @@
+/**
+ * Auditor ciphertext — ECDH encrypt-to-auditor for Method-Y permissioned pools.
+ *
+ * Lets a depositor encrypt note viewing data (tokenId, amount) TO a permissioned-pool
+ * auditor's Ed25519 viewing PUBLIC key. Only the auditor's private key can decrypt.
+ *
+ * Cipher: X25519 ECDH key-agreement + XChaCha20-Poly1305 AEAD.
+ *
+ * Wire format (112 bytes):
+ *   eph_pub        :: 32 bytes  (ephemeral X25519 public key)
+ *   nonce          :: 24 bytes  (random XChaCha20 nonce)
+ *   ciphertext_tag :: 56 bytes  (encrypted tokenId(32 BE) || amount(8 LE) + Poly1305 tag(16))
+ */
+
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { x25519 } from "@noble/curves/ed25519.js";
+import {
+  ed25519PubToX25519,
+  ed25519PrivToX25519,
+  x25519PubFromPriv,
+} from "./crypto-ed25519";
+
+const DOMAIN = new TextEncoder().encode("utxopia.auditor-ciphertext.v1");
+
+const EPH_PUB_BYTES = 32;
+const NONCE_BYTES = 24;
+const PLAINTEXT_BYTES = 40; // tokenId(32) + amount(8)
+const TAG_BYTES = 16;
+const CT_WITH_TAG_BYTES = PLAINTEXT_BYTES + TAG_BYTES; // 56
+export const AUDITOR_CIPHERTEXT_BYTES = EPH_PUB_BYTES + NONCE_BYTES + CT_WITH_TAG_BYTES; // 112
+
+export interface AuditorNotePlain {
+  tokenId: bigint;
+  amount: bigint;
+}
+
+function deriveKey(shared: Uint8Array): Uint8Array {
+  const buf = new Uint8Array(shared.length + DOMAIN.length);
+  buf.set(shared, 0);
+  buf.set(DOMAIN, shared.length);
+  return sha256(buf);
+}
+
+function packPlaintext(plain: AuditorNotePlain): Uint8Array {
+  const out = new Uint8Array(PLAINTEXT_BYTES);
+  // tokenId: 32 bytes big-endian
+  let t = plain.tokenId;
+  for (let i = 31; i >= 0; i--) {
+    out[i] = Number(t & 0xffn);
+    t >>= 8n;
+  }
+  if (t !== 0n) throw new RangeError("tokenId exceeds 256 bits");
+  // amount: 8 bytes little-endian
+  let a = plain.amount;
+  for (let i = 0; i < 8; i++) {
+    out[32 + i] = Number(a & 0xffn);
+    a >>= 8n;
+  }
+  if (a !== 0n) throw new RangeError("amount exceeds 64 bits");
+  return out;
+}
+
+function unpackPlaintext(bytes: Uint8Array): AuditorNotePlain {
+  let tokenId = 0n;
+  for (let i = 0; i < 32; i++) tokenId = (tokenId << 8n) | BigInt(bytes[i]);
+  let amount = 0n;
+  for (let i = 7; i >= 0; i--) amount = (amount << 8n) | BigInt(bytes[32 + i]);
+  return { tokenId, amount };
+}
+
+/**
+ * Encrypt note viewing data to an auditor's Ed25519 viewing public key.
+ *
+ * @param auditorViewingPubKey - 32-byte Ed25519 public key of the auditor
+ * @param plain                - tokenId + amount to encrypt
+ * @param commitment           - 32-byte note commitment (AAD — binds blob to note)
+ * @param ephemeralPriv        - optional 32-byte X25519 private key (random if omitted)
+ * @returns 112-byte blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56)
+ */
+export function encryptAuditorCiphertext(
+  auditorViewingPubKey: Uint8Array,
+  plain: AuditorNotePlain,
+  commitment: Uint8Array,
+  ephemeralPriv?: Uint8Array,
+): Uint8Array {
+  if (auditorViewingPubKey.length !== 32) throw new Error("auditorViewingPubKey must be 32 bytes");
+  if (commitment.length !== 32) throw new Error("commitment must be 32 bytes");
+
+  const ephPriv = ephemeralPriv ?? crypto.getRandomValues(new Uint8Array(32));
+  const ephPub = x25519PubFromPriv(ephPriv);
+  const auditorX = ed25519PubToX25519(auditorViewingPubKey);
+  const shared = x25519.getSharedSecret(ephPriv, auditorX);
+  const key = deriveKey(shared);
+
+  const nonce = crypto.getRandomValues(new Uint8Array(NONCE_BYTES));
+  const aead = xchacha20poly1305(key, nonce, commitment);
+  const ciphertextWithTag = aead.encrypt(packPlaintext(plain));
+
+  const blob = new Uint8Array(AUDITOR_CIPHERTEXT_BYTES);
+  blob.set(ephPub, 0);
+  blob.set(nonce, EPH_PUB_BYTES);
+  blob.set(ciphertextWithTag, EPH_PUB_BYTES + NONCE_BYTES);
+  return blob;
+}
+
+/**
+ * Convenience wrapper: build a 112-byte auditor ciphertext blob from note fields.
+ *
+ * Thin wrapper over {@link encryptAuditorCiphertext} for callers who have the raw
+ * note fields (tokenId, amount, commitment) rather than a pre-packed `AuditorNotePlain`.
+ *
+ * @param input.auditorViewingPubKey - 32-byte Ed25519 public key of the auditor
+ * @param input.tokenId              - token id (field element, fits in 256 bits)
+ * @param input.amount               - note amount (≤ 64 bits)
+ * @param input.commitment           - 32-byte note commitment (binds ciphertext to note)
+ * @returns 112-byte blob: eph_pub(32) || nonce(24) || ciphertextWithTag(56)
+ */
+export function buildAuditorCiphertextForNote(input: {
+  auditorViewingPubKey: Uint8Array;
+  tokenId: bigint;
+  amount: bigint;
+  commitment: Uint8Array;
+}): Uint8Array {
+  return encryptAuditorCiphertext(
+    input.auditorViewingPubKey,
+    { tokenId: input.tokenId, amount: input.amount },
+    input.commitment,
+  );
+}
+
+/**
+ * Normalise the `auditorCiphertext` field accepted by permissioned builders.
+ *
+ * Builders accept either:
+ *   - a pre-computed `Uint8Array` blob (advanced / off-chain computed), OR
+ *   - a plain-fields object `{ auditorViewingPubKey, tokenId, amount, commitment }`
+ *     which will be encrypted on the fly via `buildAuditorCiphertextForNote`.
+ *
+ * If both forms are supplied the explicit `Uint8Array` wins.
+ */
+export type AuditorCiphertextInput =
+  | Uint8Array
+  | { auditorViewingPubKey: Uint8Array; tokenId: bigint; amount: bigint; commitment: Uint8Array };
+
+export function resolveAuditorCiphertext(input: AuditorCiphertextInput): Uint8Array {
+  if (input instanceof Uint8Array) return input;
+  return buildAuditorCiphertextForNote(input);
+}
+
+/**
+ * Decrypt an auditor ciphertext blob using the auditor's Ed25519 viewing private key.
+ *
+ * @param auditorViewingPrivKey - 32-byte Ed25519 private key of the auditor
+ * @param blob                  - 112-byte blob from `encryptAuditorCiphertext`
+ * @param commitment            - 32-byte note commitment (must match AAD used during encrypt)
+ * @returns decrypted plain, or null on any failure (wrong key, wrong commitment, corrupt)
+ */
+export function decryptAuditorCiphertext(
+  auditorViewingPrivKey: Uint8Array,
+  blob: Uint8Array,
+  commitment: Uint8Array,
+): AuditorNotePlain | null {
+  if (blob.length !== AUDITOR_CIPHERTEXT_BYTES) return null;
+  if (commitment.length !== 32) return null;
+
+  const ephPub = blob.slice(0, EPH_PUB_BYTES);
+  const nonce = blob.slice(EPH_PUB_BYTES, EPH_PUB_BYTES + NONCE_BYTES);
+  const ciphertextWithTag = blob.slice(EPH_PUB_BYTES + NONCE_BYTES);
+
+  try {
+    const auditorXPriv = ed25519PrivToX25519(auditorViewingPrivKey);
+    const shared = x25519.getSharedSecret(auditorXPriv, ephPub);
+    const key = deriveKey(shared);
+    const aead = xchacha20poly1305(key, nonce, commitment);
+    const plaintext = aead.decrypt(ciphertextWithTag);
+    return unpackPlaintext(plaintext);
+  } catch {
+    return null;
+  }
+}