@shroud-fi/scanning 0.1.0

package/dist/cjs/types.d.ts

@@ -0,0 +1,90 @@
+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;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}

package/dist/cjs/types.js

@@ -0,0 +1,17 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA,2EAA2E;AAC3E,EAAE;AACF,oBAAoB;AACpB,8EAA8E;AAC9E,0EAA0E;AAC1E,gFAAgF;AAChF,2EAA2E;AAC3E,6EAA6E;AAC7E,6EAA6E;AAC7E,4EAA4E;AAC5E,sCAAsC;AACtC,sEAAsE;AACtE,4EAA4E;AAC5E,+BAA+B"}

package/dist/cjs/viem-backend.d.ts

@@ -0,0 +1,14 @@
+import { type PublicClient } from 'viem';
+import type { AnnouncementHandler, BackendWatchOptions, FinalityLevel, RawAnnouncement, ScannerBackend, UnsubscribeFn } from './types.js';
+interface ViemBackendOptions {
+    readonly getLogsChunkSize?: bigint;
+}
+export declare class ViemScannerBackend implements ScannerBackend {
+    #private;
+    constructor(publicClient: PublicClient, options?: ViemBackendOptions);
+    watchAnnouncements(handler: AnnouncementHandler, options: BackendWatchOptions): UnsubscribeFn;
+    getAnnouncementsInRange(fromBlock: bigint, toBlock: bigint, options: BackendWatchOptions): Promise<readonly RawAnnouncement[]>;
+    getLatestBlock(level: FinalityLevel): Promise<bigint>;
+}
+export {};
+//# sourceMappingURL=viem-backend.d.ts.map

package/dist/cjs/viem-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viem-backend.d.ts","sourceRoot":"","sources":["../../src/viem-backend.ts"],"names":[],"mappings":"AAYA,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAO3E,OAAO,KAAK,EACV,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,YAAY,CAAC;AAOpB,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAkBD,qBAAa,kBAAmB,YAAW,cAAc;;gBAI3C,YAAY,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,kBAAkB;IAKpE,kBAAkB,CAChB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,EAAE,mBAAmB,GAC3B,aAAa;IA+BV,uBAAuB,CAC3B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,SAAS,eAAe,EAAE,CAAC;IA8ChC,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;CA2B5D"}

package/dist/cjs/viem-backend.js

@@ -0,0 +1,166 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ViemScannerBackend = void 0;
+const viem_1 = require("viem");
+const transport_1 = require("@shroud-fi/transport");
+const constants_js_1 = require("./constants.js");
+const errors_js_1 = require("./errors.js");
+const ANNOUNCEMENT_EVENT = (0, viem_1.getAbiItem)({
+    abi: transport_1.ERC5564AnnouncerAbi,
+    name: 'Announcement',
+});
+class ViemScannerBackend {
+    #publicClient;
+    #chunkSize;
+    constructor(publicClient, options) {
+        this.#publicClient = publicClient;
+        this.#chunkSize = options?.getLogsChunkSize ?? constants_js_1.DEFAULT_GETLOGS_CHUNK_SIZE;
+    }
+    watchAnnouncements(handler, options) {
+        const watchArgs = {
+            address: options.contractAddress,
+            abi: transport_1.ERC5564AnnouncerAbi,
+            eventName: 'Announcement',
+            onLogs: (logs) => {
+                for (const log of logs) {
+                    const decoded = decodeAnnouncementLog(log);
+                    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) => {
+                // Privacy: do not surface the underlying RPC error payload. Tag only.
+                throw new errors_js_1.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, toBlock, options) {
+        if (toBlock < fromBlock)
+            return [];
+        const collected = [];
+        let cursor = fromBlock;
+        while (cursor <= toBlock) {
+            const chunkEnd = cursor + this.#chunkSize - 1n > toBlock
+                ? toBlock
+                : cursor + this.#chunkSize - 1n;
+            let logs;
+            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);
+            }
+            catch {
+                // Privacy: short tag only. No original error payload.
+                throw new errors_js_1.BackendUnreachableError('getLogs failed');
+            }
+            for (const log of logs) {
+                const decoded = decodeAnnouncementLog(log);
+                if (decoded === null)
+                    continue;
+                collected.push(decoded);
+            }
+            cursor = chunkEnd + 1n;
+        }
+        return collected;
+    }
+    async getLatestBlock(level) {
+        // 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 errors_js_1.BackendUnreachableError('getBlockNumber failed');
+            }
+        }
+        if (level !== 'safe' && level !== 'finalized') {
+            throw new errors_js_1.InvalidFinalityLevelError(String(level));
+        }
+        try {
+            const block = await this.#publicClient.getBlock({ blockTag: level });
+            const num = block.number;
+            if (num === null) {
+                throw new errors_js_1.BackendUnreachableError('getBlockNumber failed');
+            }
+            return num;
+        }
+        catch (err) {
+            if (err instanceof errors_js_1.BackendUnreachableError)
+                throw err;
+            throw new errors_js_1.BackendUnreachableError('getBlockNumber failed');
+        }
+    }
+}
+exports.ViemScannerBackend = ViemScannerBackend;
+/**
+ * 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) {
+    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: (0, viem_1.hexToBytes)(args.ephemeralPubKey),
+        metadata: (0, viem_1.hexToBytes)(args.metadata),
+        blockNumber: log.blockNumber,
+        blockHash: log.blockHash,
+        txHash: log.transactionHash,
+        logIndex: log.logIndex,
+    };
+}
+//# sourceMappingURL=viem-backend.js.map

package/dist/cjs/viem-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"viem-backend.js","sourceRoot":"","sources":["../../src/viem-backend.ts"],"names":[],"mappings":"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"}

package/dist/esm/backend.d.ts

@@ -0,0 +1,2 @@
+export type { ScannerBackend, RawAnnouncement, AnnouncementHandler, UnsubscribeFn, BackendWatchOptions, FinalityLevel, } from './types.js';
+//# sourceMappingURL=backend.d.ts.map

package/dist/esm/backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAIA,YAAY,EACV,cAAc,EACd,eAAe,EACf,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/esm/backend.js

@@ -0,0 +1,5 @@
+// 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 {};
+//# sourceMappingURL=backend.js.map

package/dist/esm/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,6BAA6B"}

package/dist/esm/constants.d.ts

@@ -0,0 +1,14 @@
+import type { FinalityLevel } from './types.js';
+/** Default ERC-5564 SCHEME_ID — secp256k1 with view tags. */
+export declare const DEFAULT_SCHEME_ID = 1n;
+/** Reconciliation tick interval — 5 minutes. */
+export declare const DEFAULT_RECONCILE_INTERVAL_MS = 300000;
+/** LRU dedup capacity — chosen to fit ~30 minutes of Base block production. */
+export declare const DEFAULT_DEDUP_CAPACITY = 10000;
+/** Max blocks per getLogs call — Alchemy/QuickNode default-safe. */
+export declare const DEFAULT_GETLOGS_CHUNK_SIZE = 10000n;
+/** Default finality threshold an event must satisfy before yielding. */
+export declare const DEFAULT_FINALITY: FinalityLevel;
+/** Minimum metadata length before a view tag can even be read (byte 0). */
+export declare const MIN_METADATA_LENGTH = 1;
+//# sourceMappingURL=constants.d.ts.map

package/dist/esm/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAEpC,gDAAgD;AAChD,eAAO,MAAM,6BAA6B,SAAU,CAAC;AAErD,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,oEAAoE;AACpE,eAAO,MAAM,0BAA0B,SAAU,CAAC;AAElD,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,EAAE,aAAsB,CAAC;AAEtD,2EAA2E;AAC3E,eAAO,MAAM,mBAAmB,IAAI,CAAC"}

package/dist/esm/constants.js

@@ -0,0 +1,14 @@
+// Defaults for @shroud-fi/scanning. All values are tunable via ScannerConfig.
+/** 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 = 10000n;
+/** Default finality threshold an event must satisfy before yielding. */
+export const DEFAULT_FINALITY = 'safe';
+/** Minimum metadata length before a view tag can even be read (byte 0). */
+export const MIN_METADATA_LENGTH = 1;
+//# sourceMappingURL=constants.js.map

package/dist/esm/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAI9E,6DAA6D;AAC7D,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,gDAAgD;AAChD,MAAM,CAAC,MAAM,6BAA6B,GAAG,OAAO,CAAC;AAErD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C,oEAAoE;AACpE,MAAM,CAAC,MAAM,0BAA0B,GAAG,MAAO,CAAC;AAElD,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAkB,MAAM,CAAC;AAEtD,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC"}

package/dist/esm/cursor.d.ts

@@ -0,0 +1,8 @@
+export declare class Cursor {
+    #private;
+    constructor(startBlock: bigint);
+    get last(): bigint;
+    /** Advance to `block` if it is strictly greater than the current last. */
+    advanceTo(block: bigint): void;
+}
+//# sourceMappingURL=cursor.d.ts.map

package/dist/esm/cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/cursor.ts"],"names":[],"mappings":"AAOA,qBAAa,MAAM;;gBAGL,UAAU,EAAE,MAAM;IAO9B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,0EAA0E;IAC1E,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;CAK/B"}

package/dist/esm/cursor.js

@@ -0,0 +1,24 @@
+// 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;
+    constructor(startBlock) {
+        if (startBlock < 0n) {
+            throw new ScanningError('startBlock must be non-negative');
+        }
+        this.#last = startBlock;
+    }
+    get last() {
+        return this.#last;
+    }
+    /** Advance to `block` if it is strictly greater than the current last. */
+    advanceTo(block) {
+        if (block > this.#last) {
+            this.#last = block;
+        }
+    }
+}
+//# sourceMappingURL=cursor.js.map

package/dist/esm/cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/cursor.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,EAAE;AACF,6EAA6E;AAC7E,0EAA0E;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,MAAM;IACjB,KAAK,CAAS;IAEd,YAAY,UAAkB;QAC5B,IAAI,UAAU,GAAG,EAAE,EAAE,CAAC;YACpB,MAAM,IAAI,aAAa,CAAC,iCAAiC,CAAC,CAAC;QAC7D,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC;IAC1B,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC;IACpB,CAAC;IAED,0EAA0E;IAC1E,SAAS,CAAC,KAAa;QACrB,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;YACvB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACrB,CAAC;IACH,CAAC;CACF"}

package/dist/esm/dedup.d.ts

@@ -0,0 +1,10 @@
+export declare class LRUDeduper {
+    #private;
+    constructor(capacity: number);
+    has(key: string): boolean;
+    /** Add a key. Returns true if newly added, false if already present. */
+    add(key: string): boolean;
+    clear(): void;
+    get size(): number;
+}
+//# sourceMappingURL=dedup.d.ts.map

package/dist/esm/dedup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.d.ts","sourceRoot":"","sources":["../../src/dedup.ts"],"names":[],"mappings":"AAWA,qBAAa,UAAU;;gBAIT,QAAQ,EAAE,MAAM;IAQ5B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,wEAAwE;IACxE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAazB,KAAK,IAAI,IAAI;IAIb,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/esm/dedup.js

@@ -0,0 +1,44 @@
+// 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 {
+    #capacity;
+    #map;
+    constructor(capacity) {
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new ScanningError('LRU capacity must be a positive integer');
+        }
+        this.#capacity = capacity;
+        this.#map = new Map();
+    }
+    has(key) {
+        return this.#map.has(key);
+    }
+    /** Add a key. Returns true if newly added, false if already present. */
+    add(key) {
+        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() {
+        this.#map.clear();
+    }
+    get size() {
+        return this.#map.size;
+    }
+}
+//# sourceMappingURL=dedup.js.map

package/dist/esm/dedup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dedup.js","sourceRoot":"","sources":["../../src/dedup.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,EAAE;AACF,oBAAoB;AACpB,8EAA8E;AAC9E,gFAAgF;AAChF,kDAAkD;AAClD,8EAA8E;AAC9E,uDAAuD;AAEvD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,UAAU;IACZ,SAAS,CAAS;IAClB,IAAI,CAAoB;IAEjC,YAAY,QAAgB;QAC1B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,aAAa,CAAC,yCAAyC,CAAC,CAAC;QACrE,CAAC;QACD,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,IAAI,GAAG,EAAgB,CAAC;IACtC,CAAC;IAED,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5B,CAAC;IAED,wEAAwE;IACxE,GAAG,CAAC,GAAW;QACb,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;QACrC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;YACpC,mEAAmE;YACnE,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;gBACtC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACzB,MAAM;YACR,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK;QACH,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;IACpB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;IACxB,CAAC;CACF"}

package/dist/esm/detector.d.ts

@@ -0,0 +1,9 @@
+import type { Scanner, ScannerConfig } 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 declare function createScanner(config: ScannerConfig): Scanner;
+//# sourceMappingURL=detector.d.ts.map

package/dist/esm/detector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detector.d.ts","sourceRoot":"","sources":["../../src/detector.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAGV,OAAO,EAEP,aAAa,EAEd,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CA0b5D"}