@shroud-fi/scanning 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ShroudFi contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,57 @@
+# @shroud-fi/scanning
+
+> Receiver-side stealth payment detection for ShroudFi.
+
+[![npm](https://img.shields.io/npm/v/@shroud-fi/scanning.svg)](https://www.npmjs.com/package/@shroud-fi/scanning)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+```bash
+npm i @shroud-fi/scanning viem
+```
+
+## What it does
+
+`@shroud-fi/scanning` is the receiver side of a ShroudFi payment. It:
+
+1. Scans a block range on Base for EIP-5564 `Announcement` events.
+2. Filters by **one-byte view tag** — eliminates ~99.6% of irrelevant announcements without doing the heavy elliptic-curve math.
+3. For each surviving candidate, performs an ECDH-style derivation to check whether the payment is for you, and if so, derives the stealth private key needed to spend it.
+
+The scan key is **separable** — you can delegate scanning to a service while keeping the spending key in agent runtime.
+
+## Quick start
+
+```ts
+import { createScanner } from '@shroud-fi/scanning';
+import { deriveAgentIdentity } from '@shroud-fi/core';
+import { createTransport } from '@shroud-fi/transport';
+
+const transport = createTransport({ chain: 'base', rpcUrl });
+const identity = deriveAgentIdentity(masterSeed);
+const scanner = createScanner(transport, identity);
+
+const payments = await scanner.scan({ fromBlock: 46_800_000n, toBlock: 'latest' });
+// → [{ stealthAddress, stealthPrivateKey, ephemeralPubKey, viewTag, blockNumber, logIndex }, ...]
+```
+
+## Exports
+
+| Symbol | Purpose |
+|---|---|
+| `createScanner(transport, identity)` | Scanner bound to an agent identity + transport. |
+| `scanner.scan(range)` | Detect inbound payments in a block range; returns the stealth private key per hit. |
+| `DetectedPayment` | `{ stealthAddress, stealthPrivateKey, ephemeralPubKey, viewTag, blockNumber, logIndex }` |
+
+Full API reference: [shroudfi.live/sdk#scanning](https://shroudfi.live/sdk#scanning)
+
+## Operational notes
+
+- **Long ranges:** the scanner batches log requests. For an agent that's been offline > 24h, scanning is bounded by RPC log-query limits — chunk the range.
+- **Real-time:** for low-latency detection, run `scanner.scan` from `latestBlock - confirmationDepth` on a tight cron, or use a webhook delivery primitive (planned for a future release).
+- **Privacy invariant:** the scanner never logs the spending key it derives. Caller is responsible for handling `stealthPrivateKey` securely.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Part of the [ShroudFi](https://shroudfi.live) privacy SDK for AI agents on Base.

package/dist/cjs/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/cjs/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/cjs/backend.js

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

package/dist/cjs/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/cjs/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/cjs/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/cjs/constants.js

@@ -0,0 +1,17 @@
+"use strict";
+// Defaults for @shroud-fi/scanning. All values are tunable via ScannerConfig.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_METADATA_LENGTH = exports.DEFAULT_FINALITY = exports.DEFAULT_GETLOGS_CHUNK_SIZE = exports.DEFAULT_DEDUP_CAPACITY = exports.DEFAULT_RECONCILE_INTERVAL_MS = exports.DEFAULT_SCHEME_ID = void 0;
+/** Default ERC-5564 SCHEME_ID — secp256k1 with view tags. */
+exports.DEFAULT_SCHEME_ID = 1n;
+/** Reconciliation tick interval — 5 minutes. */
+exports.DEFAULT_RECONCILE_INTERVAL_MS = 300_000;
+/** LRU dedup capacity — chosen to fit ~30 minutes of Base block production. */
+exports.DEFAULT_DEDUP_CAPACITY = 10_000;
+/** Max blocks per getLogs call — Alchemy/QuickNode default-safe. */
+exports.DEFAULT_GETLOGS_CHUNK_SIZE = 10000n;
+/** Default finality threshold an event must satisfy before yielding. */
+exports.DEFAULT_FINALITY = 'safe';
+/** Minimum metadata length before a view tag can even be read (byte 0). */
+exports.MIN_METADATA_LENGTH = 1;
+//# sourceMappingURL=constants.js.map

package/dist/cjs/constants.js.map

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

package/dist/cjs/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/cjs/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/cjs/cursor.js

@@ -0,0 +1,28 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cursor = void 0;
+const errors_js_1 = require("./errors.js");
+class Cursor {
+    #last;
+    constructor(startBlock) {
+        if (startBlock < 0n) {
+            throw new errors_js_1.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;
+        }
+    }
+}
+exports.Cursor = Cursor;
+//# sourceMappingURL=cursor.js.map

package/dist/cjs/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,2CAA4C;AAE5C,MAAa,MAAM;IACjB,KAAK,CAAS;IAEd,YAAY,UAAkB;QAC5B,IAAI,UAAU,GAAG,EAAE,EAAE,CAAC;YACpB,MAAM,IAAI,yBAAa,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;AApBD,wBAoBC"}

package/dist/cjs/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/cjs/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/cjs/dedup.js

@@ -0,0 +1,48 @@
+"use strict";
+// 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.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LRUDeduper = void 0;
+const errors_js_1 = require("./errors.js");
+class LRUDeduper {
+    #capacity;
+    #map;
+    constructor(capacity) {
+        if (!Number.isInteger(capacity) || capacity < 1) {
+            throw new errors_js_1.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;
+    }
+}
+exports.LRUDeduper = LRUDeduper;
+//# sourceMappingURL=dedup.js.map

package/dist/cjs/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,2CAA4C;AAE5C,MAAa,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,yBAAa,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;AArCD,gCAqCC"}

package/dist/cjs/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/cjs/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"}