@shroud-fi/scanning 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/scanning",
-  "version": "0.1.2",
+  "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.2",
-    "@shroud-fi/transport": "0.1.3"
+    "@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}`);
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+// Public surface — @shroud-fi/scanning
+// Phase 3: detection-only stealth payment scanner. Caller drives sweep.
+// Sweep queue / log-normal delay / destination rotation are deferred phases.
+
+// Factory
+export { createScanner } from './detector.js';
+
+// Backend interface + viem implementation
+export { ViemScannerBackend } from './viem-backend.js';
+export type {
+  ScannerBackend,
+  RawAnnouncement,
+  AnnouncementHandler,
+  UnsubscribeFn,
+  BackendWatchOptions,
+  FinalityLevel,
+} from './backend.js';
+
+// Public types
+export type {
+  Scanner,
+  ScannerConfig,
+  ScannerTransportLike,
+  DetectedPayment,
+} from './types.js';
+
+// Errors
+export {
+  ScanningError,
+  BackendUnreachableError,
+  MalformedAnnouncementError,
+  MissingPublicClientError,
+  InvalidFinalityLevelError,
+} from './errors.js';
+
+// Utilities (advanced consumers)
+export { LRUDeduper } from './dedup.js';
+export { Cursor } from './cursor.js';
+
+// Defaults
+export {
+  DEFAULT_SCHEME_ID,
+  DEFAULT_RECONCILE_INTERVAL_MS,
+  DEFAULT_DEDUP_CAPACITY,
+  DEFAULT_GETLOGS_CHUNK_SIZE,
+  DEFAULT_FINALITY,
+  MIN_METADATA_LENGTH,
+} from './constants.js';

package/src/types.ts

@@ -0,0 +1,127 @@
+// Public surface types for @shroud-fi/scanning (Phase 3 — detection only).
+//
+// Privacy contract:
+//   - ScannerConfig accepts branded ScanningKey + SpendingKey directly. These
+//     remain in-process; the scanner never logs them, serializes them, or
+//     surfaces them in errors. Spending key is required because ECDH derivation
+//     of the per-payment stealth private key needs it; see compute-key.ts.
+//   - DetectedPayment.stealthPrivateKey is the recovered private key for the
+//     one-time stealth address. It NEVER touches a relayer or logger. Caller
+//     drives the sweep (via @shroud-fi/payments sweepETH/sweepERC20) and is
+//     responsible for not leaking it.
+//   - Detection is idempotent. Cursor is in-memory only and resets to
+//     `startBlock` on restart. The dedup LRU prevents double-yield within a
+//     single Scanner lifetime.
+
+import type { Address, Hex, PublicClient, Chain, Transport } from 'viem';
+import type { ScanningKey, SpendingKey } from '@shroud-fi/core';
+
+/** Finality threshold an event must satisfy before it is yielded. */
+export type FinalityLevel = 'unsafe' | 'safe' | 'finalized';
+
+/** Optional handle for the caller-supplied viem PublicClient. */
+export interface ScannerTransportLike {
+  readonly publicClient: PublicClient<Transport, Chain>;
+}
+
+/** Stealth address detection configuration. */
+export interface ScannerConfig {
+  /** A ShroudFi transport (or any object exposing a viem PublicClient). */
+  readonly transport: ScannerTransportLike;
+  /** Recipient's scanning private key (branded). */
+  readonly scanningKey: ScanningKey;
+  /** Recipient's spending private key (branded). Required for ECDH derivation. */
+  readonly spendingKey: SpendingKey;
+  /** Scheme ID filter. Defaults to 1 (secp256k1 + view tag). */
+  readonly schemeId?: bigint;
+  /**
+   * ERC-5564 Announcer contract to watch. Defaults to the canonical address
+   * exported from @shroud-fi/transport (`ERC5564_ANNOUNCER`).
+   */
+  readonly contractAddress?: Address;
+  /** First block scanned. Detection state resets to this on restart. */
+  readonly startBlock: bigint;
+  /** Finality threshold for yielding. Defaults to `'safe'`. */
+  readonly finality?: FinalityLevel;
+  /** Reconciliation tick interval in ms. Defaults to 300_000 (5 minutes). */
+  readonly reconcileIntervalMs?: number;
+  /** LRU dedup capacity. Defaults to 10_000. */
+  readonly dedupCapacity?: number;
+  /** Max blocks per getLogs call (auto-chunking). Defaults to 10_000n. */
+  readonly getLogsChunkSize?: bigint;
+  /** Optional override of the backend implementation (for tests / Envio). */
+  readonly backend?: ScannerBackend;
+}
+
+/** Raw on-chain announcement before view-tag filtering or ECDH verification. */
+export interface RawAnnouncement {
+  readonly schemeId: bigint;
+  readonly stealthAddress: Address;
+  readonly caller: Address;
+  readonly ephemeralPubKey: Uint8Array;
+  readonly metadata: Uint8Array;
+  readonly blockNumber: bigint;
+  readonly blockHash: Hex;
+  readonly txHash: Hex;
+  readonly logIndex: number;
+}
+
+/** Successfully detected stealth payment destined for this recipient. */
+export interface DetectedPayment {
+  readonly stealthAddress: Address;
+  readonly ephemeralPubKey: Hex;
+  readonly stealthPrivateKey: Hex;
+  readonly blockNumber: bigint;
+  readonly blockHash: Hex;
+  readonly txHash: Hex;
+  readonly logIndex: number;
+  readonly finality: 'safe' | 'finalized';
+}
+
+/** Callback signature passed to backend.watchAnnouncements. */
+export type AnnouncementHandler = (
+  announcement: RawAnnouncement,
+) => void | Promise<void>;
+
+/** Unsubscribe handle returned by backend.watchAnnouncements. */
+export type UnsubscribeFn = () => void;
+
+/** Backend options shared between watch + getAnnouncementsInRange. */
+export interface BackendWatchOptions {
+  readonly contractAddress: Address;
+  readonly schemeId?: bigint;
+}
+
+/**
+ * Indexer-agnostic announcement source. ViemScannerBackend is the only impl
+ * shipping in P3. A future EnvioScannerBackend lands behind this interface.
+ */
+export interface ScannerBackend {
+  /** Subscribe to live announcements. Returns unsubscribe handle. */
+  watchAnnouncements(
+    handler: AnnouncementHandler,
+    options: BackendWatchOptions,
+  ): UnsubscribeFn;
+  /** Historical range query (auto-chunked). */
+  getAnnouncementsInRange(
+    fromBlock: bigint,
+    toBlock: bigint,
+    options: BackendWatchOptions,
+  ): Promise<readonly RawAnnouncement[]>;
+  /** Latest block number for a finality level. */
+  getLatestBlock(level: FinalityLevel): Promise<bigint>;
+}
+
+/** Scanner runtime returned by createScanner. */
+export interface Scanner {
+  /** Live async iterator over detected payments. Cancellable via AbortSignal. */
+  watch(signal?: AbortSignal): AsyncIterable<DetectedPayment>;
+  /** Backfill a historical block range, yielding any detected payments. */
+  scanRange(
+    fromBlock: bigint,
+    toBlock: bigint,
+    signal?: AbortSignal,
+  ): AsyncIterable<DetectedPayment>;
+  /** Stop watching, clear timers, release the backend subscription. */
+  close(): void;
+}

package/src/viem-backend.ts

@@ -0,0 +1,216 @@
+// viem-backed ScannerBackend. The only backend that ships in Phase 3.
+//
+// Privacy contract (binding):
+//   - No console.* anywhere in this file.
+//   - Error messages NEVER embed hex strings, key material, amounts, or raw RPC
+//     payloads. Short reason tags only ("getLogs failed", "watch failed",
+//     "getBlockNumber failed").
+//   - No JSON.stringify of args or logs.
+//   - Pending / malformed logs (missing blockNumber, blockHash, transactionHash,
+//     or logIndex) are silently skipped — they aren't actionable for detection
+//     and we don't want to leak their existence via thrown errors.
+
+import { getAbiItem, hexToBytes, type Hex, type PublicClient } from 'viem';
+import { ERC5564AnnouncerAbi } from '@shroud-fi/transport';
+import { DEFAULT_GETLOGS_CHUNK_SIZE } from './constants.js';
+import {
+  BackendUnreachableError,
+  InvalidFinalityLevelError,
+} from './errors.js';
+import type {
+  AnnouncementHandler,
+  BackendWatchOptions,
+  FinalityLevel,
+  RawAnnouncement,
+  ScannerBackend,
+  UnsubscribeFn,
+} from './types.js';
+
+const ANNOUNCEMENT_EVENT = getAbiItem({
+  abi: ERC5564AnnouncerAbi,
+  name: 'Announcement',
+});
+
+interface ViemBackendOptions {
+  readonly getLogsChunkSize?: bigint;
+}
+
+interface AnnouncementLogArgs {
+  readonly schemeId?: bigint;
+  readonly stealthAddress?: `0x${string}`;
+  readonly caller?: `0x${string}`;
+  readonly ephemeralPubKey?: Hex;
+  readonly metadata?: Hex;
+}
+
+interface AnnouncementLog {
+  readonly args?: AnnouncementLogArgs;
+  readonly blockNumber?: bigint | null;
+  readonly blockHash?: Hex | null;
+  readonly transactionHash?: Hex | null;
+  readonly logIndex?: number | null;
+}
+
+export class ViemScannerBackend implements ScannerBackend {
+  readonly #publicClient: PublicClient;
+  readonly #chunkSize: bigint;
+
+  constructor(publicClient: PublicClient, options?: ViemBackendOptions) {
+    this.#publicClient = publicClient;
+    this.#chunkSize = options?.getLogsChunkSize ?? DEFAULT_GETLOGS_CHUNK_SIZE;
+  }
+
+  watchAnnouncements(
+    handler: AnnouncementHandler,
+    options: BackendWatchOptions,
+  ): UnsubscribeFn {
+    const watchArgs = {
+      address: options.contractAddress,
+      abi: ERC5564AnnouncerAbi,
+      eventName: 'Announcement' as const,
+      onLogs: (logs: readonly unknown[]) => {
+        for (const log of logs) {
+          const decoded = decodeAnnouncementLog(log as AnnouncementLog);
+          if (decoded === null) continue;
+          // Fire-and-forget. Handler may return a promise; we intentionally do
+          // not await — backend semantics are "deliver, don't gate".
+          void handler(decoded);
+        }
+      },
+      onError: (_err: unknown) => {
+        // Privacy: do not surface the underlying RPC error payload. Tag only.
+        throw new BackendUnreachableError('watch failed');
+      },
+    };
+
+    const unsubscribe =
+      options.schemeId !== undefined
+        ? this.#publicClient.watchContractEvent({
+            ...watchArgs,
+            args: { schemeId: options.schemeId },
+          })
+        : this.#publicClient.watchContractEvent(watchArgs);
+
+    return unsubscribe;
+  }
+
+  async getAnnouncementsInRange(
+    fromBlock: bigint,
+    toBlock: bigint,
+    options: BackendWatchOptions,
+  ): Promise<readonly RawAnnouncement[]> {
+    if (toBlock < fromBlock) return [];
+
+    const collected: RawAnnouncement[] = [];
+    let cursor = fromBlock;
+    while (cursor <= toBlock) {
+      const chunkEnd =
+        cursor + this.#chunkSize - 1n > toBlock
+          ? toBlock
+          : cursor + this.#chunkSize - 1n;
+
+      let logs: readonly unknown[];
+      try {
+        const getLogsArgs =
+          options.schemeId !== undefined
+            ? {
+                address: options.contractAddress,
+                event: ANNOUNCEMENT_EVENT,
+                args: { schemeId: options.schemeId },
+                fromBlock: cursor,
+                toBlock: chunkEnd,
+              }
+            : {
+                address: options.contractAddress,
+                event: ANNOUNCEMENT_EVENT,
+                fromBlock: cursor,
+                toBlock: chunkEnd,
+              };
+        logs = await this.#publicClient.getLogs(getLogsArgs as never);
+      } catch {
+        // Privacy: short tag only. No original error payload.
+        throw new BackendUnreachableError('getLogs failed');
+      }
+
+      for (const log of logs) {
+        const decoded = decodeAnnouncementLog(log as AnnouncementLog);
+        if (decoded === null) continue;
+        collected.push(decoded);
+      }
+
+      cursor = chunkEnd + 1n;
+    }
+
+    return collected;
+  }
+
+  async getLatestBlock(level: FinalityLevel): Promise<bigint> {
+    // viem.getBlockNumber() always returns the *latest* head; for 'safe' and
+    // 'finalized' we must go through getBlock({ blockTag }) and extract .number.
+    if (level === 'unsafe') {
+      try {
+        return await this.#publicClient.getBlockNumber();
+      } catch {
+        throw new BackendUnreachableError('getBlockNumber failed');
+      }
+    }
+
+    if (level !== 'safe' && level !== 'finalized') {
+      throw new InvalidFinalityLevelError(String(level));
+    }
+
+    try {
+      const block = await this.#publicClient.getBlock({ blockTag: level });
+      const num = block.number;
+      if (num === null) {
+        throw new BackendUnreachableError('getBlockNumber failed');
+      }
+      return num;
+    } catch (err) {
+      if (err instanceof BackendUnreachableError) throw err;
+      throw new BackendUnreachableError('getBlockNumber failed');
+    }
+  }
+}
+
+/**
+ * Convert a viem decoded log into a RawAnnouncement. Returns null for any
+ * pending / malformed log (missing block fields, missing args). Never throws.
+ */
+function decodeAnnouncementLog(log: AnnouncementLog): RawAnnouncement | null {
+  const args = log.args;
+  if (args === undefined) return null;
+  if (
+    args.schemeId === undefined ||
+    args.stealthAddress === undefined ||
+    args.caller === undefined ||
+    args.ephemeralPubKey === undefined ||
+    args.metadata === undefined
+  ) {
+    return null;
+  }
+  if (
+    log.blockNumber === undefined ||
+    log.blockNumber === null ||
+    log.blockHash === undefined ||
+    log.blockHash === null ||
+    log.transactionHash === undefined ||
+    log.transactionHash === null ||
+    log.logIndex === undefined ||
+    log.logIndex === null
+  ) {
+    return null;
+  }
+
+  return {
+    schemeId: args.schemeId,
+    stealthAddress: args.stealthAddress,
+    caller: args.caller,
+    ephemeralPubKey: hexToBytes(args.ephemeralPubKey),
+    metadata: hexToBytes(args.metadata),
+    blockNumber: log.blockNumber,
+    blockHash: log.blockHash,
+    txHash: log.transactionHash,
+    logIndex: log.logIndex,
+  };
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "test", "node_modules"]
+}