@shroud-fi/scanning 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/scanning",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Receiver-side stealth payment detection for ShroudFi. Scans EIP-5564 announcements with view-tag pre-filtering (~99.6% reduction).",
   "keywords": [
     "shroudfi",
@@ -26,11 +26,14 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
-    "@shroud-fi/core": "0.1.1",
-    "@shroud-fi/transport": "0.1.2"
+    "@shroud-fi/core": "0.1.3",
+    "@shroud-fi/transport": "0.1.4"
   },
   "peerDependencies": {
     "viem": "^2.21.0"

package/src/backend.ts

@@ -0,0 +1,12 @@
+// Thin re-export module that exposes the ScannerBackend interface without
+// pulling the whole index.ts barrel. Lets backend implementations import the
+// minimum surface they need.
+
+export type {
+  ScannerBackend,
+  RawAnnouncement,
+  AnnouncementHandler,
+  UnsubscribeFn,
+  BackendWatchOptions,
+  FinalityLevel,
+} from './types.js';

package/src/constants.ts

@@ -0,0 +1,21 @@
+// Defaults for @shroud-fi/scanning. All values are tunable via ScannerConfig.
+
+import type { FinalityLevel } from './types.js';
+
+/** Default ERC-5564 SCHEME_ID — secp256k1 with view tags. */
+export const DEFAULT_SCHEME_ID = 1n;
+
+/** Reconciliation tick interval — 5 minutes. */
+export const DEFAULT_RECONCILE_INTERVAL_MS = 300_000;
+
+/** LRU dedup capacity — chosen to fit ~30 minutes of Base block production. */
+export const DEFAULT_DEDUP_CAPACITY = 10_000;
+
+/** Max blocks per getLogs call — Alchemy/QuickNode default-safe. */
+export const DEFAULT_GETLOGS_CHUNK_SIZE = 10_000n;
+
+/** Default finality threshold an event must satisfy before yielding. */
+export const DEFAULT_FINALITY: FinalityLevel = 'safe';
+
+/** Minimum metadata length before a view tag can even be read (byte 0). */
+export const MIN_METADATA_LENGTH = 1;

package/src/cursor.ts

@@ -0,0 +1,28 @@
+// Monotonic block cursor used by the detector's reconciliation loop.
+//
+// In-memory only — by design (per types.ts contract). On restart the scanner
+// resets to `startBlock`. Dedup + ECDH verification prevent double-yield.
+
+import { ScanningError } from './errors.js';
+
+export class Cursor {
+  #last: bigint;
+
+  constructor(startBlock: bigint) {
+    if (startBlock < 0n) {
+      throw new ScanningError('startBlock must be non-negative');
+    }
+    this.#last = startBlock;
+  }
+
+  get last(): bigint {
+    return this.#last;
+  }
+
+  /** Advance to `block` if it is strictly greater than the current last. */
+  advanceTo(block: bigint): void {
+    if (block > this.#last) {
+      this.#last = block;
+    }
+  }
+}

package/src/dedup.ts

@@ -0,0 +1,49 @@
+// FIFO LRU deduper for announcement keys (`${txHash}:${logIndex}`).
+//
+// Privacy contract:
+//   - Keys passed in are public on-chain identifiers (txHash + logIndex). The
+//     deduper never sees private key material; nothing here is sensitive on its
+//     own. Still, no console.* logging by policy.
+//   - JS Map iteration order is insertion order, which gives us FIFO eviction
+//     for free without an explicit doubly-linked list.
+
+import { ScanningError } from './errors.js';
+
+export class LRUDeduper {
+  readonly #capacity: number;
+  readonly #map: Map<string, true>;
+
+  constructor(capacity: number) {
+    if (!Number.isInteger(capacity) || capacity < 1) {
+      throw new ScanningError('LRU capacity must be a positive integer');
+    }
+    this.#capacity = capacity;
+    this.#map = new Map<string, true>();
+  }
+
+  has(key: string): boolean {
+    return this.#map.has(key);
+  }
+
+  /** Add a key. Returns true if newly added, false if already present. */
+  add(key: string): boolean {
+    if (this.#map.has(key)) return false;
+    this.#map.set(key, true);
+    if (this.#map.size > this.#capacity) {
+      // FIFO eviction: drop the oldest entry (first in insertion order).
+      for (const oldest of this.#map.keys()) {
+        this.#map.delete(oldest);
+        break;
+      }
+    }
+    return true;
+  }
+
+  clear(): void {
+    this.#map.clear();
+  }
+
+  get size(): number {
+    return this.#map.size;
+  }
+}

package/src/detector.ts

@@ -0,0 +1,497 @@
+// Stealth-payment detector — orchestrates view-tag prefilter, ECDH recovery,
+// finality gating, dedup, and reconciliation backfill.
+//
+// Privacy contract (binding — enforced by tests):
+//   - No console.* anywhere in this file.
+//   - No error message embeds key material, ephemeral pubkey bytes, or stealth
+//     private key. Short structured tags only ("verify failed", "backend
+//     unreachable").
+//   - No JSON.stringify of keys, raw announcements, or RawAnnouncement.metadata.
+//   - The recovered stealth private key only surfaces via the explicit return
+//     value DetectedPayment.stealthPrivateKey — never logged.
+//   - Backpressure note: the live watch() queue is unbounded by design for v1.
+//     A consumer that ignores yields will see memory grow; document if surfaces.
+
+import { bytesToHex, type Hex } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import {
+  checkViewTag,
+  computeStealthKey,
+  InvalidKeyError,
+  StealthAddressError,
+} from '@shroud-fi/core';
+import { ERC5564_ANNOUNCER } from '@shroud-fi/transport';
+import {
+  DEFAULT_DEDUP_CAPACITY,
+  DEFAULT_FINALITY,
+  DEFAULT_GETLOGS_CHUNK_SIZE,
+  DEFAULT_RECONCILE_INTERVAL_MS,
+  DEFAULT_SCHEME_ID,
+  MIN_METADATA_LENGTH,
+} from './constants.js';
+import { Cursor } from './cursor.js';
+import { LRUDeduper } from './dedup.js';
+import {
+  BackendUnreachableError,
+  MissingPublicClientError,
+  ScanningError,
+} from './errors.js';
+import { ViemScannerBackend } from './viem-backend.js';
+import type {
+  DetectedPayment,
+  RawAnnouncement,
+  Scanner,
+  ScannerBackend,
+  ScannerConfig,
+  UnsubscribeFn,
+} from './types.js';
+
+/**
+ * Build a Scanner instance.
+ *
+ * Construction validates config + resolves defaults. The Scanner is inert until
+ * the caller starts iterating watch() or scanRange(). close() is idempotent.
+ */
+export function createScanner(config: ScannerConfig): Scanner {
+  if (config.transport === undefined || config.transport.publicClient === undefined) {
+    throw new MissingPublicClientError();
+  }
+  if (config.startBlock < 0n) {
+    throw new ScanningError('startBlock must be non-negative');
+  }
+
+  const schemeId = config.schemeId ?? DEFAULT_SCHEME_ID;
+  const finality = config.finality ?? DEFAULT_FINALITY;
+  const reconcileIntervalMs =
+    config.reconcileIntervalMs ?? DEFAULT_RECONCILE_INTERVAL_MS;
+  const dedupCapacity = config.dedupCapacity ?? DEFAULT_DEDUP_CAPACITY;
+  const getLogsChunkSize =
+    config.getLogsChunkSize ?? DEFAULT_GETLOGS_CHUNK_SIZE;
+  const contractAddress = config.contractAddress ?? ERC5564_ANNOUNCER;
+
+  const backend: ScannerBackend =
+    config.backend ??
+    new ViemScannerBackend(config.transport.publicClient, {
+      getLogsChunkSize,
+    });
+
+  const dedup = new LRUDeduper(dedupCapacity);
+  const cursor = new Cursor(config.startBlock);
+  const pendingFinality = new Map<string, RawAnnouncement>();
+
+  let reconcileTimer: ReturnType<typeof setInterval> | undefined;
+  let unsubscribe: UnsubscribeFn | undefined;
+  let closed = false;
+  // Reject concurrent watch() calls. The closure singletons above can hold at
+  // most one live subscription + timer; a second watch() would silently leak
+  // the first iterator's resources. Caller must close() before re-watching.
+  let watchActive = false;
+  // Cap pending events so a stuck backend can't grow memory unboundedly.
+  const pendingCap = Math.max(dedupCapacity, 100);
+
+  // ---- Verification pipeline ----------------------------------------------
+
+  /**
+   * Run view-tag prefilter + ECDH derivation + address-match check against
+   * a raw announcement. Returns recovered stealth private key bytes on match,
+   * or null when the announcement is not for this recipient (or is malformed).
+   * Never throws — returning null is the privacy-preserving signal.
+   */
+  function verifyAnnouncement(raw: RawAnnouncement): Uint8Array | null {
+    // Defence: metadata too short to even contain a view tag.
+    if (raw.metadata.length < MIN_METADATA_LENGTH) return null;
+
+    const viewTag = raw.metadata[0]!;
+
+    // Fast-path filter — drops ~99.6% of non-matching announcements.
+    let viewTagMatch: boolean;
+    try {
+      viewTagMatch = checkViewTag(
+        config.scanningKey,
+        raw.ephemeralPubKey,
+        viewTag,
+      );
+    } catch {
+      // Garbage ephemeral pubkey — drop silently.
+      return null;
+    }
+    if (!viewTagMatch) return null;
+
+    // ECDH derivation of stealth private key.
+    let stealthPriv: Uint8Array;
+    try {
+      stealthPriv = computeStealthKey(
+        config.scanningKey,
+        config.spendingKey,
+        raw.ephemeralPubKey,
+      );
+    } catch (err) {
+      if (err instanceof InvalidKeyError || err instanceof StealthAddressError) {
+        return null;
+      }
+      // Re-wrap unknown failure with a privacy-safe message.
+      throw new ScanningError('verify failed');
+    }
+
+    // Address-match check — guards against view-tag false positives and any
+    // log unrelated to this recipient.
+    let derivedAddress: string;
+    try {
+      const stealthPrivHex = bytesToHex(stealthPriv) as Hex;
+      derivedAddress = privateKeyToAccount(stealthPrivHex).address;
+    } catch {
+      return null;
+    }
+
+    if (derivedAddress.toLowerCase() !== raw.stealthAddress.toLowerCase()) {
+      return null;
+    }
+
+    return stealthPriv;
+  }
+
+  function dedupKey(raw: RawAnnouncement): string {
+    return `${raw.txHash}:${raw.logIndex}`;
+  }
+
+  function toDetected(
+    raw: RawAnnouncement,
+    stealthPriv: Uint8Array,
+    payloadFinality: 'safe' | 'finalized',
+  ): DetectedPayment {
+    return {
+      stealthAddress: raw.stealthAddress,
+      ephemeralPubKey: bytesToHex(raw.ephemeralPubKey),
+      stealthPrivateKey: bytesToHex(stealthPriv),
+      blockNumber: raw.blockNumber,
+      blockHash: raw.blockHash,
+      txHash: raw.txHash,
+      logIndex: raw.logIndex,
+      finality: payloadFinality,
+    };
+  }
+
+  // The configured `finality` is 'unsafe' | 'safe' | 'finalized', but the
+  // emitted DetectedPayment.finality is only 'safe' | 'finalized'. Treat
+  // 'unsafe' as 'safe' on the emit path (caller asked for no gating; we still
+  // tag what we yield as the safer label).
+  const emitFinality: 'safe' | 'finalized' =
+    finality === 'finalized' ? 'finalized' : 'safe';
+
+  // ---- watch() ------------------------------------------------------------
+
+  function watch(signal?: AbortSignal): AsyncIterable<DetectedPayment> {
+    return {
+      [Symbol.asyncIterator]: () => {
+        if (watchActive) {
+          // Surface as a rejecting first next() so callers learn via the
+          // async-iterator protocol instead of a sync throw from `for await`.
+          return {
+            next: () =>
+              Promise.reject(
+                new ScanningError('watch already active — close() first'),
+              ),
+            return: () =>
+              Promise.resolve({ value: undefined, done: true } as IteratorResult<
+                DetectedPayment
+              >),
+          };
+        }
+        watchActive = true;
+        const queue: DetectedPayment[] = [];
+        let waiter:
+          | { resolve: (v: IteratorResult<DetectedPayment>) => void }
+          | undefined;
+        let finished = false;
+        let abortListener: (() => void) | undefined;
+
+        function finish(): void {
+          if (finished) return;
+          finished = true;
+          if (waiter !== undefined) {
+            const w = waiter;
+            waiter = undefined;
+            w.resolve({ value: undefined, done: true });
+          }
+        }
+
+        function emit(payment: DetectedPayment): void {
+          if (finished) return;
+          if (waiter !== undefined) {
+            const w = waiter;
+            waiter = undefined;
+            w.resolve({ value: payment, done: false });
+            return;
+          }
+          queue.push(payment);
+        }
+
+        async function tryEmitOrDefer(raw: RawAnnouncement): Promise<void> {
+          const key = dedupKey(raw);
+          // Two-tier dedup: emitted (LRU) + in-flight pending. Skip duplicates
+          // arriving while the first delivery is still mid-pipeline.
+          if (dedup.has(key) || pendingFinality.has(key)) return;
+
+          const stealthPriv = verifyAnnouncement(raw);
+          if (stealthPriv === null) return;
+
+          let tip: bigint;
+          try {
+            tip = await backend.getLatestBlock(finality);
+          } catch {
+            // Backend transient failure — keep the candidate around for the
+            // next reconciliation tick. Do not throw into the consumer stream.
+            pendingFinality.set(key, raw);
+            return;
+          }
+
+          if (raw.blockNumber > tip) {
+            // Cap pending map to prevent unbounded growth on stuck finality.
+            if (pendingFinality.size >= pendingCap) {
+              const oldest = pendingFinality.keys().next().value;
+              if (oldest !== undefined) pendingFinality.delete(oldest);
+            }
+            pendingFinality.set(key, raw);
+            return;
+          }
+
+          // Race guard: if a concurrent path already added this key (e.g. the
+          // same announcement was delivered twice and both passed the initial
+          // has() check before either reached this point), drop the dup.
+          if (!dedup.add(key)) return;
+          pendingFinality.delete(key);
+          emit(toDetected(raw, stealthPriv, emitFinality));
+        }
+
+        // Already-aborted: bail before touching the backend.
+        if (signal?.aborted === true) {
+          finished = true;
+          return {
+            next: () =>
+              Promise.resolve({ value: undefined, done: true } as IteratorResult<
+                DetectedPayment
+              >),
+            return: () =>
+              Promise.resolve({ value: undefined, done: true } as IteratorResult<
+                DetectedPayment
+              >),
+          };
+        }
+
+        // Subscribe to live announcements.
+        try {
+          unsubscribe = backend.watchAnnouncements(
+            (raw) => {
+              if (finished || closed) return;
+              // Fire-and-forget per backend contract.
+              void tryEmitOrDefer(raw).catch(() => {
+                // Swallow — never let pipeline errors crash the watcher.
+              });
+            },
+            { contractAddress, schemeId },
+          );
+        } catch {
+          // If subscription fails outright, surface a privacy-safe error on
+          // the first next() and shut down.
+          finished = true;
+          return {
+            next: () =>
+              Promise.reject(
+                new BackendUnreachableError('watch subscribe failed'),
+              ),
+            return: () =>
+              Promise.resolve({ value: undefined, done: true } as IteratorResult<
+                DetectedPayment
+              >),
+          };
+        }
+
+        // Reconciliation tick — backfill missed blocks + re-check pending.
+        const timer = setInterval(() => {
+          void reconcileOnce().catch(() => {
+            // Never throw out of the interval.
+          });
+        }, reconcileIntervalMs);
+        // Don't keep the Node event loop alive solely on this timer.
+        if (typeof (timer as { unref?: () => void }).unref === 'function') {
+          (timer as { unref: () => void }).unref();
+        }
+        reconcileTimer = timer;
+
+        async function reconcileOnce(): Promise<void> {
+          if (finished || closed) return;
+
+          // Phase 1: backfill any blocks between cursor and current tip.
+          let tip: bigint;
+          try {
+            tip = await backend.getLatestBlock(finality);
+          } catch {
+            return; // Skip this tick — try again later.
+          }
+
+          const from = cursor.last + 1n;
+          if (tip >= from) {
+            let logs: readonly RawAnnouncement[] = [];
+            try {
+              logs = await backend.getAnnouncementsInRange(from, tip, {
+                contractAddress,
+                schemeId,
+              });
+            } catch {
+              // Leave cursor alone — try again next tick.
+              return;
+            }
+
+            for (const raw of logs) {
+              if (finished || closed) return;
+              const key = dedupKey(raw);
+              if (dedup.has(key)) continue;
+              const stealthPriv = verifyAnnouncement(raw);
+              if (stealthPriv === null) continue;
+              if (!dedup.add(key)) continue;
+              pendingFinality.delete(key);
+              emit(toDetected(raw, stealthPriv, emitFinality));
+            }
+            // Re-check after the loop: close() may have run mid-iteration.
+            if (finished || closed) return;
+            cursor.advanceTo(tip);
+          }
+
+          // Phase 2: re-check pending announcements that had not finalized.
+          if (pendingFinality.size > 0) {
+            for (const [key, raw] of Array.from(pendingFinality.entries())) {
+              if (finished || closed) return;
+              if (raw.blockNumber <= tip) {
+                pendingFinality.delete(key);
+                if (dedup.has(key)) continue;
+                const stealthPriv = verifyAnnouncement(raw);
+                if (stealthPriv === null) continue;
+                if (!dedup.add(key)) continue;
+                emit(toDetected(raw, stealthPriv, emitFinality));
+              }
+            }
+          }
+        }
+
+        // Wire abort. Listener handle retained so we can remove it on return().
+        if (signal !== undefined) {
+          abortListener = () => {
+            finish();
+            close();
+          };
+          signal.addEventListener('abort', abortListener, { once: true });
+        }
+
+        function teardown(): void {
+          if (signal !== undefined && abortListener !== undefined) {
+            try {
+              signal.removeEventListener('abort', abortListener);
+            } catch {
+              // Some environments swallow this; safe to ignore.
+            }
+            abortListener = undefined;
+          }
+          watchActive = false;
+        }
+
+        return {
+          next(): Promise<IteratorResult<DetectedPayment>> {
+            // queue.length and waiter assignment are both synchronous within
+            // this tick — no interleaving window exists between the empty
+            // check and the executor body. emit() will see `waiter` set by
+            // the time it can fire (next microtask).
+            if (queue.length > 0) {
+              const value = queue.shift()!;
+              return Promise.resolve({ value, done: false });
+            }
+            if (finished) {
+              return Promise.resolve({ value: undefined, done: true });
+            }
+            return new Promise<IteratorResult<DetectedPayment>>((resolve) => {
+              waiter = { resolve };
+            });
+          },
+          return(): Promise<IteratorResult<DetectedPayment>> {
+            finish();
+            teardown();
+            close();
+            return Promise.resolve({ value: undefined, done: true });
+          },
+          throw(): Promise<IteratorResult<DetectedPayment>> {
+            finish();
+            teardown();
+            close();
+            return Promise.resolve({ value: undefined, done: true });
+          },
+        };
+      },
+    };
+  }
+
+  // ---- scanRange() --------------------------------------------------------
+
+  function scanRange(
+    fromBlock: bigint,
+    toBlock: bigint,
+    signal?: AbortSignal,
+  ): AsyncIterable<DetectedPayment> {
+    return {
+      [Symbol.asyncIterator]: async function* () {
+        if (signal !== undefined && signal.aborted) return;
+        if (toBlock < fromBlock) return;
+
+        let logs: readonly RawAnnouncement[];
+        try {
+          logs = await backend.getAnnouncementsInRange(fromBlock, toBlock, {
+            contractAddress,
+            schemeId,
+          });
+        } catch {
+          throw new BackendUnreachableError('getLogs failed');
+        }
+
+        // Sort deterministically by (blockNumber, logIndex).
+        const sorted = [...logs].sort((a, b) => {
+          if (a.blockNumber === b.blockNumber) {
+            return a.logIndex - b.logIndex;
+          }
+          return a.blockNumber < b.blockNumber ? -1 : 1;
+        });
+
+        for (const raw of sorted) {
+          if (signal !== undefined && signal.aborted) return;
+          const key = dedupKey(raw);
+          if (dedup.has(key)) continue;
+          const stealthPriv = verifyAnnouncement(raw);
+          if (stealthPriv === null) continue;
+          if (!dedup.add(key)) continue;
+          // Caller invoked a historical range — finality is achieved.
+          yield toDetected(raw, stealthPriv, 'safe');
+        }
+      },
+    };
+  }
+
+  // ---- close() ------------------------------------------------------------
+
+  function close(): void {
+    if (closed) return;
+    closed = true;
+    if (unsubscribe !== undefined) {
+      try {
+        unsubscribe();
+      } catch {
+        // Swallow — close must not throw.
+      }
+      unsubscribe = undefined;
+    }
+    if (reconcileTimer !== undefined) {
+      clearInterval(reconcileTimer);
+      reconcileTimer = undefined;
+    }
+    // Reset re-entry guard so close() + new watch() works.
+    watchActive = false;
+  }
+
+  return { watch, scanRange, close };
+}

package/src/errors.ts

@@ -0,0 +1,45 @@
+// Privacy-safe error classes for @shroud-fi/scanning.
+//
+// Invariants enforced by tests in test/privacy-invariants.test.ts:
+//   - Error messages MUST NOT embed any 32-byte hex (key material, txHash is
+//     allowed but should not be the whole error payload).
+//   - Error messages MUST NOT embed ephemeral pubkey bytes.
+//   - Error messages MUST NOT embed transfer amounts.
+//   - Constructors take only short, structured tags (chainId, block, logIndex,
+//     short reason). The thrown error gets its full stack from V8; we don't
+//     attach extra fields.
+
+export class ScanningError extends Error {
+  override readonly name: string = 'ScanningError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class BackendUnreachableError extends ScanningError {
+  override readonly name: string = 'BackendUnreachableError';
+  constructor(reason: string) {
+    super(`Scanner backend unreachable: ${reason}`);
+  }
+}
+
+export class MalformedAnnouncementError extends ScanningError {
+  override readonly name: string = 'MalformedAnnouncementError';
+  constructor(reason: string) {
+    super(`Malformed announcement skipped: ${reason}`);
+  }
+}
+
+export class MissingPublicClientError extends ScanningError {
+  override readonly name: string = 'MissingPublicClientError';
+  constructor() {
+    super('Scanner transport has no publicClient');
+  }
+}
+
+export class InvalidFinalityLevelError extends ScanningError {
+  override readonly name: string = 'InvalidFinalityLevelError';
+  constructor(level: string) {
+    super(`Invalid finality level: ${level}`);
+  }
+}