@zbase-protocol/core 0.1.0

package/dist/noteScanner.js

@@ -0,0 +1,422 @@
+/**
+ * @zbase-protocol/core — WebSocket UTXO note scanner (Phase 1B)
+ *
+ * Subscribes to a UTXOPool's `Spent` and `Transferred` events over a WS RPC,
+ * trial-decrypts every transferred ciphertext with the user's viewing key,
+ * and yields decrypted notes as an async iterable. Wallets and facilitators
+ * use this to track balance + spendable notes without polling.
+ *
+ * Naming: this file is `noteScanner.ts` (NOT `scanner.ts`) because
+ * `scanner.ts` is already in use for the chain-agnostic x402-exposure scorer.
+ * The two scanners do unrelated things; consolidating later is a separate
+ * refactor and would break public API.
+ *
+ * Transport: we depend ONLY on the WHATWG `WebSocket` global (available in
+ * browser, Node ≥22 native, Cloudflare Workers, Bun). No `ethers` or `viem`
+ * import is needed for the WS layer — both libraries would force a heavier
+ * dependency surface and we already speak JSON-RPC. ABI encoding/decoding of
+ * event logs is done by hand for the two specific events we care about. If
+ * this proves brittle, the next iteration can swap to viem's `decodeEventLog`
+ * (already a root dependency of the consuming Next.js app).
+ *
+ * Reconnect policy: exponential backoff capped at 30 s. The async iterable
+ * yields a `{type:"connected"}` marker on every successful (re)connect so
+ * callers can persist the last-seen block and replay if they care about
+ * historical correctness across disconnects.
+ */
+import { keccak_256 } from "@noble/hashes/sha3";
+import { decryptNoteWithAAD, } from "./notes.js";
+// -----------------------------------------------------------------------------
+// Topic hashes (keccak256 of canonical event signatures, hex-prefixed)
+// -----------------------------------------------------------------------------
+function toHex(bytes) {
+    return "0x" + Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function keccakTopic(signature) {
+    return toHex(keccak_256(new TextEncoder().encode(signature)));
+}
+/**
+ * Spent(uint256,uint256,uint256,uint256,uint256)
+ * Two indexed nullifier hashes + non-indexed (amount, commitment0, commitment1).
+ */
+export const SPENT_TOPIC = keccakTopic("Spent(uint256,uint256,uint256,uint256,uint256)");
+/**
+ * Transferred(uint256,uint256,uint256,uint256,(bytes32[4],bytes32,bytes32,bytes32,bytes32),(bytes32[4],bytes32,bytes32,bytes32,bytes32))
+ *
+ * The two `CommitmentCiphertext` structs are ABI-encoded as tuples. This is
+ * the canonical event-signature form Solidity uses for keccak256(topic[0]).
+ */
+export const TRANSFERRED_TOPIC = keccakTopic("Transferred(uint256,uint256,uint256,uint256,(bytes32[4],bytes32,bytes32,bytes32,bytes32),(bytes32[4],bytes32,bytes32,bytes32,bytes32))");
+const DEFAULT_RECONNECT_BACKOFF_MS = [
+    1_000, 2_000, 4_000, 8_000, 16_000, 30_000,
+];
+// -----------------------------------------------------------------------------
+// Log decoding (Phase 1B: hand-decode, swap to viem if maintenance burden grows)
+// -----------------------------------------------------------------------------
+function hexToBytes(hex) {
+    const s = hex.startsWith("0x") ? hex.slice(2) : hex;
+    if (s.length % 2 !== 0) {
+        throw new Error(`hexToBytes: odd-length hex ${hex}`);
+    }
+    const out = new Uint8Array(s.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
+function hexToBigint(hex) {
+    return BigInt(hex);
+}
+function readWord(bytes, wordIndex) {
+    const start = wordIndex * 32;
+    if (start + 32 > bytes.length) {
+        throw new Error(`readWord: out-of-range word ${wordIndex} (bytes length ${bytes.length})`);
+    }
+    return bytes.slice(start, start + 32);
+}
+function readWordAsBigint(bytes, wordIndex) {
+    const w = readWord(bytes, wordIndex);
+    let v = 0n;
+    for (const b of w)
+        v = (v << 8n) | BigInt(b);
+    return v;
+}
+/**
+ * Decode the data field of a `Spent` log:
+ *   words: [withdrawnAmount, outputCommitment0, outputCommitment1]
+ * The two indexed nullifier hashes live in `topics[1..3]`, not in data.
+ */
+export function decodeSpentLog(log) {
+    if (log.topics.length < 3) {
+        throw new Error("decodeSpentLog: expected 3 topics (signature + 2 indexed)");
+    }
+    const data = hexToBytes(log.data);
+    return {
+        nullifierHash0: hexToBigint(log.topics[1]),
+        nullifierHash1: hexToBigint(log.topics[2]),
+        withdrawnAmount: readWordAsBigint(data, 0),
+        outputCommitment0: readWordAsBigint(data, 1),
+        outputCommitment1: readWordAsBigint(data, 2),
+        blockNumber: hexToBigint(log.blockNumber),
+        txHash: log.transactionHash,
+        logIndex: Number(hexToBigint(log.logIndex)),
+    };
+}
+export function decodeTransferredLog(log) {
+    if (log.topics.length < 3) {
+        throw new Error("decodeTransferredLog: expected 3 topics (signature + 2 indexed)");
+    }
+    const data = hexToBytes(log.data);
+    const outputCommitment0 = readWordAsBigint(data, 0);
+    const outputCommitment1 = readWordAsBigint(data, 1);
+    // ciphertext0 occupies words 2..9, ciphertext1 occupies 10..17.
+    const ct0Blob = new Uint8Array(128);
+    for (let i = 0; i < 4; i++)
+        ct0Blob.set(readWord(data, 2 + i), i * 32);
+    const ct0Aad = readWord(data, 9);
+    const ct1Blob = new Uint8Array(128);
+    for (let i = 0; i < 4; i++)
+        ct1Blob.set(readWord(data, 10 + i), i * 32);
+    const ct1Aad = readWord(data, 17);
+    return {
+        nullifierHash0: hexToBigint(log.topics[1]),
+        nullifierHash1: hexToBigint(log.topics[2]),
+        outputCommitment0,
+        outputCommitment1,
+        ciphertext0Blob: ct0Blob,
+        ciphertext0Aad: ct0Aad,
+        ciphertext1Blob: ct1Blob,
+        ciphertext1Aad: ct1Aad,
+        blockNumber: hexToBigint(log.blockNumber),
+        txHash: log.transactionHash,
+        logIndex: Number(hexToBigint(log.logIndex)),
+    };
+}
+/**
+ * Trial-decrypt both ciphertexts of a Transferred log against the viewing
+ * key. Returns the matching event or `null` if neither ciphertext belongs to
+ * this wallet.
+ *
+ * The encrypted blob fed to `decryptNoteWithAAD` is the on-chain wire format
+ * that `encryptNoteForTransfer` produces — see notes.ts `EncryptedNote`
+ * layout. The contract stores it spread across four bytes32 words; we
+ * reassemble it back into the linear byte buffer here.
+ *
+ * Phase 1B caveat: the v0 `encryptNote` envelope (ephPub|viewTag|nonce|ct)
+ * does not yet fit neatly inside bytes32[4]. A follow-up will define a
+ * compact wire layout; the v0 wire is the linear blob and that's what we
+ * decode here. The hand-decoder above is a placeholder that will need to
+ * track that schema once it's frozen.
+ */
+export function tryDecryptTransferred(decoded, viewingPrivateKey) {
+    // Try output 0
+    const note0 = decryptNoteWithAAD(decoded.ciphertext0Blob, viewingPrivateKey, decoded.outputCommitment0);
+    if (note0) {
+        return {
+            type: "transferred-in",
+            outputIndex: 0,
+            commitment: decoded.outputCommitment0,
+            note: note0,
+            siblingNullifierHash: decoded.nullifierHash1,
+            blockNumber: decoded.blockNumber,
+            txHash: decoded.txHash,
+            logIndex: decoded.logIndex,
+        };
+    }
+    // Try output 1
+    const note1 = decryptNoteWithAAD(decoded.ciphertext1Blob, viewingPrivateKey, decoded.outputCommitment1);
+    if (note1) {
+        return {
+            type: "transferred-in",
+            outputIndex: 1,
+            commitment: decoded.outputCommitment1,
+            note: note1,
+            siblingNullifierHash: decoded.nullifierHash0,
+            blockNumber: decoded.blockNumber,
+            txHash: decoded.txHash,
+            logIndex: decoded.logIndex,
+        };
+    }
+    return {
+        type: "transferred-other",
+        outputCommitment0: decoded.outputCommitment0,
+        outputCommitment1: decoded.outputCommitment1,
+        blockNumber: decoded.blockNumber,
+        txHash: decoded.txHash,
+        logIndex: decoded.logIndex,
+    };
+}
+/**
+ * Create an async iterable scanner over a UTXOPool's events.
+ *
+ * Usage:
+ * ```ts
+ * for await (const ev of createScanner({ wsUrl, utxoPoolAddress, viewingKey })) {
+ *   if (ev.type === "transferred-in") {
+ *     wallet.addNote(ev.commitment, ev.note);
+ *   } else if (ev.type === "spent") {
+ *     wallet.markSpent(ev.nullifierHash0, ev.nullifierHash1);
+ *   }
+ * }
+ * ```
+ *
+ * Cancellation: pass `signal: AbortSignal` (or break out of the for-await).
+ * On abort, the underlying WebSocket is closed cleanly.
+ */
+export async function* createScanner(options) {
+    const backoff = options.reconnectBackoffMs && options.reconnectBackoffMs.length > 0
+        ? options.reconnectBackoffMs
+        : DEFAULT_RECONNECT_BACKOFF_MS;
+    const WsCtor = options.webSocketCtor ?? globalThis.WebSocket;
+    if (!WsCtor) {
+        throw new Error("createScanner: WebSocket constructor not available; pass options.webSocketCtor explicitly");
+    }
+    let reconnectAttempt = 0;
+    let lastSeenBlock = options.fromBlock ?? 0n;
+    outer: while (!options.signal?.aborted) {
+        let ws;
+        try {
+            ws = new WsCtor(options.wsUrl);
+        }
+        catch (err) {
+            yield { type: "error", message: "websocket-open-failed", cause: err };
+            const wait = backoff[Math.min(reconnectAttempt, backoff.length - 1)];
+            reconnectAttempt++;
+            await sleep(wait, options.signal);
+            continue;
+        }
+        const queue = new EventQueue();
+        let subscriptionId = null;
+        let nextRpcId = 1;
+        const onOpen = () => {
+            const subscribe = {
+                jsonrpc: "2.0",
+                id: nextRpcId++,
+                method: "eth_subscribe",
+                params: [
+                    "logs",
+                    {
+                        address: options.utxoPoolAddress,
+                        topics: [[SPENT_TOPIC, TRANSFERRED_TOPIC]],
+                    },
+                ],
+            };
+            ws.send(JSON.stringify(subscribe));
+        };
+        const onMessage = (raw) => {
+            let parsed;
+            try {
+                parsed = JSON.parse(String(raw.data));
+            }
+            catch (err) {
+                queue.push({
+                    type: "error",
+                    message: "rpc-parse-failed",
+                    cause: err,
+                });
+                return;
+            }
+            if (parsed.error) {
+                queue.push({
+                    type: "error",
+                    message: `rpc-error: ${parsed.error.message}`,
+                });
+                return;
+            }
+            if (parsed.result && typeof parsed.result === "string" && subscriptionId === null) {
+                subscriptionId = parsed.result;
+                queue.push({ type: "connected", reconnectAttempt, startBlock: lastSeenBlock });
+                return;
+            }
+            if (parsed.method === "eth_subscription" && parsed.params) {
+                const log = parsed.params.result;
+                if (log.removed)
+                    return;
+                try {
+                    const topic0 = log.topics[0]?.toLowerCase();
+                    if (topic0 === SPENT_TOPIC.toLowerCase()) {
+                        const ev = decodeSpentLog(log);
+                        lastSeenBlock = ev.blockNumber;
+                        queue.push({ type: "spent", ...ev });
+                    }
+                    else if (topic0 === TRANSFERRED_TOPIC.toLowerCase()) {
+                        const decoded = decodeTransferredLog(log);
+                        lastSeenBlock = decoded.blockNumber;
+                        queue.push(tryDecryptTransferred(decoded, options.viewingKey.privateKey));
+                    }
+                }
+                catch (err) {
+                    queue.push({
+                        type: "error",
+                        message: "log-decode-failed",
+                        cause: err,
+                    });
+                }
+            }
+        };
+        const onClose = () => {
+            queue.close();
+        };
+        const onError = (err) => {
+            queue.push({ type: "error", message: "websocket-error", cause: err });
+            queue.close();
+        };
+        ws.addEventListener("open", onOpen);
+        ws.addEventListener("message", onMessage);
+        ws.addEventListener("close", onClose);
+        ws.addEventListener("error", onError);
+        const abortListener = () => {
+            try {
+                ws.close();
+            }
+            catch {
+                /* already closed */
+            }
+            queue.close();
+        };
+        options.signal?.addEventListener("abort", abortListener, { once: true });
+        try {
+            for await (const ev of queue) {
+                yield ev;
+            }
+        }
+        finally {
+            options.signal?.removeEventListener("abort", abortListener);
+            try {
+                ws.close();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        if (options.signal?.aborted)
+            break outer;
+        const wait = backoff[Math.min(reconnectAttempt, backoff.length - 1)];
+        reconnectAttempt++;
+        await sleep(wait, options.signal);
+    }
+}
+// -----------------------------------------------------------------------------
+// Pure helpers used by both the live scanner and the unit tests
+// -----------------------------------------------------------------------------
+/**
+ * In-memory equivalent of the live scanner: feed it an array of already-decoded
+ * Transferred logs and the user's viewing key, get back exactly the events
+ * the live scanner would have yielded. Used by tests and by historical replay
+ * callers that have already fetched logs via `eth_getLogs`.
+ */
+export function scanTransferredLogs(logs, viewingPrivateKey) {
+    return logs.map((log) => tryDecryptTransferred(log, viewingPrivateKey));
+}
+// -----------------------------------------------------------------------------
+// Internal: bounded async queue used to bridge WS callbacks → async iterator
+// -----------------------------------------------------------------------------
+class EventQueue {
+    buffer = [];
+    waiters = [];
+    closed = false;
+    push(event) {
+        if (this.closed)
+            return;
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter({ value: event, done: false });
+        }
+        else {
+            this.buffer.push(event);
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter({ value: undefined, done: true });
+        }
+    }
+    [Symbol.asyncIterator]() {
+        const self = this;
+        return {
+            next() {
+                const buffered = self.buffer.shift();
+                if (buffered !== undefined) {
+                    return Promise.resolve({ value: buffered, done: false });
+                }
+                if (self.closed) {
+                    return Promise.resolve({
+                        value: undefined,
+                        done: true,
+                    });
+                }
+                return new Promise((resolve) => {
+                    self.waiters.push(resolve);
+                });
+            },
+            return() {
+                self.close();
+                return Promise.resolve({
+                    value: undefined,
+                    done: true,
+                });
+            },
+        };
+    }
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted) {
+            resolve();
+            return;
+        }
+        const handle = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(handle);
+            resolve();
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}