@utxopia/sdk 0.1.0-alpha.1

package/packages/sdk/README.md

@@ -0,0 +1,277 @@
+# @utxopia/sdk
+
+TypeScript SDK for interacting with the UTXOpia protocol - a privacy-preserving Bitcoin-to-Solana bridge using Zero-Knowledge Proofs.
+
+## Installation
+
+```bash
+bun add @utxopia/sdk
+# or
+npm install @utxopia/sdk
+```
+
+## Quick Start
+
+```typescript
+import {
+  deriveKeysFromWallet,
+  createStealthDeposit,
+  scanAnnouncements,
+  resolveSnsName,
+} from '@utxopia/sdk';
+
+// 1. Derive keys from wallet
+const keys = await deriveKeysFromWallet(walletAdapter);
+
+// 2. Look up recipient by .utxopia.sol name
+const recipient = await resolveSnsName(connection, 'alice');
+
+// 3. Create stealth deposit
+const deposit = await createStealthDeposit(recipient, 100000n);
+
+// 4. Scan for incoming deposits
+const notes = await scanAnnouncements(keys, announcements);
+```
+
+## Core Features
+
+### Key Derivation
+
+Derive spending and viewing keys from a Solana wallet signature (RAILGUN-style):
+
+```typescript
+import { deriveKeysFromWallet, type UTXOpiaKeys } from '@utxopia/sdk';
+
+const keys: UTXOpiaKeys = await deriveKeysFromWallet(walletAdapter);
+// keys.spendingPubKey - for receiving funds
+// keys.viewingPubKey  - for scanning deposits
+// keys.spendingPrivKey - for claiming (keep secret!)
+// keys.viewingPrivKey  - for scanning (can delegate)
+```
+
+### Stealth Addresses (EIP-5564/DKSAP Pattern)
+
+Create private deposits that only the recipient can detect and claim:
+
+```typescript
+import {
+  createStealthDeposit,
+  scanAnnouncements,
+  prepareClaimInputs,
+} from '@utxopia/sdk';
+
+// Sender: Create stealth deposit
+const deposit = await createStealthDeposit(recipientMeta, amountSats);
+// deposit.ephemeralPub - publish on-chain
+// deposit.commitment   - add to Merkle tree
+// deposit.amountSats   - verified BTC amount
+
+// Recipient: Scan for deposits
+const notes = await scanAnnouncements(keys, onChainAnnouncements);
+
+// Recipient: Prepare claim inputs for ZK proof
+const claimInputs = await prepareClaimInputs(keys, note, merkleProof);
+```
+
+### Note Generation
+
+Create and manage shielded notes:
+
+```typescript
+import {
+  generateNote,
+  deriveNote,
+  createClaimLink,
+  parseClaimLink,
+} from '@utxopia/sdk';
+
+// Generate random note
+const note = generateNote(100000n);
+
+// Derive deterministic note from seed
+const note = deriveNote('my-secret-phrase', 0, 100000n);
+
+// Create shareable claim link
+const link = createClaimLink(note);
+
+// Parse claim link
+const parsed = parseClaimLink(link);
+```
+
+### Taproot Address Derivation
+
+Generate BTC deposit addresses:
+
+```typescript
+import { deriveTaprootAddress, verifyTaprootAddress } from '@utxopia/sdk';
+
+// Use the configured FROST/Ika custody public key; there is no safe default.
+const custodyInternalKey = getConfiguredCustodyInternalKey();
+const { address } = deriveTaprootAddress(
+  commitment,
+  'testnet',
+  custodyInternalKey,
+);
+
+// Verify address matches commitment
+const isValid = verifyTaprootAddress(address, commitment, custodyInternalKey);
+```
+
+### Merkle Proofs
+
+Work with the on-chain commitment tree:
+
+```typescript
+import {
+  createMerkleProof,
+  proofToNoirFormat,
+  TREE_DEPTH,
+} from '@utxopia/sdk';
+
+const proof = createMerkleProof(leaves, leafIndex);
+const noirProof = proofToNoirFormat(proof);
+```
+
+## API Reference
+
+### Stealth Module
+
+| Function | Description |
+|----------|-------------|
+| `createStealthDeposit(recipient, amount)` | Create stealth deposit for recipient |
+| `scanAnnouncements(keys, announcements)` | Scan for deposits using viewing key |
+| `prepareClaimInputs(keys, note, proof)` | Prepare inputs for ZK claim proof |
+| `scanUnifiedNotes(keys, announcements)` | Scan announcement events for owned notes |
+| `resolveSnsName(conn, name)` | Look up .utxopia.sol name to stealth address |
+
+### Key Derivation Module
+
+| Function | Description |
+|----------|-------------|
+| `deriveKeysFromWallet(wallet)` | Derive keys from wallet signature |
+| `deriveKeysFromSignature(sig)` | Derive keys from raw signature |
+| `deriveKeysFromSeed(seed)` | Derive keys from seed bytes |
+| `createStealthMetaAddress(keys)` | Create stealth meta-address |
+| `createDelegatedViewKey(keys, perms, expiry)` | Create delegated view key |
+
+### Constants
+
+```typescript
+// Program IDs
+UTXOPIA_PROGRAM_ID        // Main UTXOpia program (devnet)
+CHADBUFFER_PROGRAM_ID    // ChadBuffer for SPV proofs
+
+// Merkle Tree
+TREE_DEPTH              // 20
+MAX_LEAVES              // 2^20
+ZERO_VALUE              // Empty leaf value
+
+```
+
+## Types
+
+### UTXOpiaKeys
+
+```typescript
+interface UTXOpiaKeys {
+  spendingPubKey: BabyJubPoint;
+  spendingPrivKey: bigint;
+  viewingPubKey: Uint8Array;
+  viewingPrivKey: Uint8Array;
+  nullifyingKey: bigint;
+}
+```
+
+### StealthDeposit
+
+```typescript
+interface StealthDeposit {
+  ephemeralPub: Uint8Array;  // 32 bytes (Ed25519)
+  amountSats: bigint;
+  commitment: Uint8Array;    // 32 bytes
+  createdAt: number;
+}
+```
+
+### ScannedNote
+
+```typescript
+interface ScannedNote {
+  amount: bigint;
+  ephemeralPub: Uint8Array;
+  stealthPub: BabyJubPoint;
+  leafIndex: number;
+  commitment: Uint8Array;
+}
+```
+
+### ConnectionAdapter
+
+```typescript
+interface ConnectionAdapter {
+  getAccountInfo: (
+    pubkey: { toBytes(): Uint8Array }
+  ) => Promise<{ data: Uint8Array } | null>;
+}
+```
+
+## Security Considerations
+
+1. **Never expose spending private key** - Only needed for claiming
+2. **Viewing key can be delegated** - For balance monitoring without spend capability
+3. **Nullifiers prevent double-spending** - Derived from spending key + leaf index
+4. **Commitments hide amounts** - Poseidon hash of NPK, token, and amount
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Build
+bun run build
+
+# Run tests
+bun test
+```
+
+## Verify it yourself: rebuild the tree from chain
+
+Spending a note needs a Merkle proof, and a Merkle proof needs the whole leaf
+set — which normally comes from our indexer. If the leaves weren't recoverable
+from the chain itself, "you can exit without the operator" would be a promise
+rather than a property.
+
+This script rebuilds a pool's entire leaf set from Solana transaction logs and
+checks the result against the root the program is verifying against. It talks to
+a public RPC endpoint and nothing else — no backend, no indexer, no API key:
+
+```bash
+TREE=<commitment-tree-pda> bun run scripts/rebuild-tree-from-chain.ts
+```
+
+```
+on-chain: 123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
+  134/134 scanned, 123 leaves
+recovered 123/123 leaves from logs
+rebuilt:  123 leaves, root 2994f7d670d12cd8dcbd89af708ff55f9e877bbb387aac4cf09e688a615650ce
+
+MATCH — the leaf set is recoverable from chain alone
+```
+
+It exits non-zero on a mismatch or on missing leaves, so it works as a check in
+CI as well as by hand.
+
+| Env | Default | |
+|---|---|---|
+| `RPC` | devnet | Any Solana RPC endpoint |
+| `TREE` | `DEVNET_CONFIG.commitmentTreePda` | Commitment tree PDA to rebuild |
+| `EPOCH_SIG` | — | Tree's `INITIALIZE` signature. Optional; set it to skip a dead epoch if the PDA was closed and recreated |
+| `PACE_MS` | `120` | Delay between requests. Raise it if your endpoint throttles you |
+
+Public endpoints rate-limit this scan aggressively — the script paces itself and
+backs off, so expect it to take a minute or two rather than to fail.
+
+## License
+
+MIT

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

@@ -0,0 +1,64 @@
+/**
+ * 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";
+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;
+export declare class AnnouncementClient {
+    protected config: AnnouncementClientConfig;
+    protected ws: WebSocket | null;
+    protected wsReconnectDelay: number;
+    protected wsConnected: boolean;
+    protected listeners: Set<AnnouncementListener>;
+    protected cachedAnnouncements: OnChainStealthAnnouncement[];
+    protected latestLeafIndex: number;
+    protected backendHealthy: boolean;
+    protected closed: boolean;
+    protected reconnectTimer: ReturnType<typeof setTimeout> | null;
+    private lastRpcFetchAt;
+    private rpcCooldownMs;
+    protected restTimeout: number;
+    protected wsMaxReconnect: number;
+    private maxLag;
+    protected wsUrl: string;
+    constructor(config: AnnouncementClientConfig);
+    /** Start WS connection and perform initial data load */
+    start(): Promise<void>;
+    /** Fetch all announcements using fallback chain */
+    fetchAll(): Promise<OnChainStealthAnnouncement[]>;
+    /** Subscribe to new announcement events. Returns unsubscribe function. */
+    onAnnouncement(listener: AnnouncementListener): () => void;
+    /** Stop client, close WS */
+    close(): void;
+    /** Whether the backend WS is currently connected */
+    get isWsConnected(): boolean;
+    /** Whether the backend REST was reachable on last attempt */
+    get isBackendHealthy(): boolean;
+    protected fetchFromBackend(since?: number): Promise<OnChainStealthAnnouncement[]>;
+    private fetchFromRpc;
+    private checkConsistency;
+    protected connectWs(): void;
+    protected scheduleReconnect(): void;
+}

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

@@ -0,0 +1,337 @@
+/**
+ * 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 { parseProgramEvents } from "./events";
+import { hexToBytes } from "./crypto";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function rowToAnnouncement(row) {
+    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) {
+    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 {
+    constructor(config) {
+        this.config = config;
+        this.ws = null;
+        this.wsReconnectDelay = 1000;
+        this.wsConnected = false;
+        this.listeners = new Set();
+        this.cachedAnnouncements = [];
+        this.latestLeafIndex = -1;
+        this.backendHealthy = true;
+        this.closed = false;
+        this.reconnectTimer = null;
+        this.lastRpcFetchAt = 0;
+        this.rpcCooldownMs = 30000; // minimum 30s between RPC fallback calls
+        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() {
+        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() {
+        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) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Stop client, close WS */
+    close() {
+        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() {
+        return this.wsConnected;
+    }
+    /** Whether the backend REST was reachable on last attempt */
+    get isBackendHealthy() {
+        return this.backendHealthy;
+    }
+    // -----------------------------------------------------------------------
+    // Internal: Backend REST
+    // -----------------------------------------------------------------------
+    async fetchFromBackend(since) {
+        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 = await resp.json();
+        if (!data.success)
+            throw new Error("Backend returned success=false");
+        return data.announcements.map(rowToAnnouncement);
+    }
+    // -----------------------------------------------------------------------
+    // Internal: Direct RPC fallback
+    // -----------------------------------------------------------------------
+    async fetchFromRpc(since) {
+        // 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 = (sigsData.result || []).map((s) => s.signature);
+        if (signatures.length === 0)
+            return [];
+        // Fetch transactions in batches of 10
+        const announcements = [];
+        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 = 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();
+        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
+    // -----------------------------------------------------------------------
+    async checkConsistency() {
+        try {
+            const statusResp = await fetch(`${this.config.backendUrl}/api/announcements/status`, { signal: AbortSignal.timeout(this.restTimeout) });
+            if (!statusResp.ok)
+                return;
+            const status = 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();
+                    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
+    // -----------------------------------------------------------------------
+    connectWs() {
+        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 = 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();
+        }
+    }
+    scheduleReconnect() {
+        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);
+    }
+}