@shroud-fi/scanning 0.1.0

package/dist/esm/types.js

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

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

@@ -0,0 +1,162 @@
+// 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 } from 'viem';
+import { ERC5564AnnouncerAbi } from '@shroud-fi/transport';
+import { DEFAULT_GETLOGS_CHUNK_SIZE } from './constants.js';
+import { BackendUnreachableError, InvalidFinalityLevelError, } from './errors.js';
+const ANNOUNCEMENT_EVENT = getAbiItem({
+    abi: ERC5564AnnouncerAbi,
+    name: 'Announcement',
+});
+export class ViemScannerBackend {
+    #publicClient;
+    #chunkSize;
+    constructor(publicClient, options) {
+        this.#publicClient = publicClient;
+        this.#chunkSize = options?.getLogsChunkSize ?? DEFAULT_GETLOGS_CHUNK_SIZE;
+    }
+    watchAnnouncements(handler, options) {
+        const watchArgs = {
+            address: options.contractAddress,
+            abi: 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 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 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 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) {
+    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,
+    };
+}
+//# sourceMappingURL=viem-backend.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"viem-backend.js","sourceRoot":"","sources":["../../src/viem-backend.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,EAAE;AACF,8BAA8B;AAC9B,0CAA0C;AAC1C,gFAAgF;AAChF,0EAA0E;AAC1E,gCAAgC;AAChC,yCAAyC;AACzC,iFAAiF;AACjF,+EAA+E;AAC/E,mEAAmE;AAEnE,OAAO,EAAE,UAAU,EAAE,UAAU,EAA+B,MAAM,MAAM,CAAC;AAC3E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AAUrB,MAAM,kBAAkB,GAAG,UAAU,CAAC;IACpC,GAAG,EAAE,mBAAmB;IACxB,IAAI,EAAE,cAAc;CACrB,CAAC,CAAC;AAsBH,MAAM,OAAO,kBAAkB;IACpB,aAAa,CAAe;IAC5B,UAAU,CAAS;IAE5B,YAAY,YAA0B,EAAE,OAA4B;QAClE,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;QAClC,IAAI,CAAC,UAAU,GAAG,OAAO,EAAE,gBAAgB,IAAI,0BAA0B,CAAC;IAC5E,CAAC;IAED,kBAAkB,CAChB,OAA4B,EAC5B,OAA4B;QAE5B,MAAM,SAAS,GAAG;YAChB,OAAO,EAAE,OAAO,CAAC,eAAe;YAChC,GAAG,EAAE,mBAAmB;YACxB,SAAS,EAAE,cAAuB;YAClC,MAAM,EAAE,CAAC,IAAwB,EAAE,EAAE;gBACnC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;oBACvB,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAsB,CAAC,CAAC;oBAC9D,IAAI,OAAO,KAAK,IAAI;wBAAE,SAAS;oBAC/B,qEAAqE;oBACrE,2DAA2D;oBAC3D,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;gBACxB,CAAC;YACH,CAAC;YACD,OAAO,EAAE,CAAC,IAAa,EAAE,EAAE;gBACzB,sEAAsE;gBACtE,MAAM,IAAI,uBAAuB,CAAC,cAAc,CAAC,CAAC;YACpD,CAAC;SACF,CAAC;QAEF,MAAM,WAAW,GACf,OAAO,CAAC,QAAQ,KAAK,SAAS;YAC5B,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC;gBACpC,GAAG,SAAS;gBACZ,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE;aACrC,CAAC;YACJ,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,kBAAkB,CAAC,SAAS,CAAC,CAAC;QAEvD,OAAO,WAAW,CAAC;IACrB,CAAC;IAED,KAAK,CAAC,uBAAuB,CAC3B,SAAiB,EACjB,OAAe,EACf,OAA4B;QAE5B,IAAI,OAAO,GAAG,SAAS;YAAE,OAAO,EAAE,CAAC;QAEnC,MAAM,SAAS,GAAsB,EAAE,CAAC;QACxC,IAAI,MAAM,GAAG,SAAS,CAAC;QACvB,OAAO,MAAM,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,QAAQ,GACZ,MAAM,GAAG,IAAI,CAAC,UAAU,GAAG,EAAE,GAAG,OAAO;gBACrC,CAAC,CAAC,OAAO;gBACT,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;YAEpC,IAAI,IAAwB,CAAC;YAC7B,IAAI,CAAC;gBACH,MAAM,WAAW,GACf,OAAO,CAAC,QAAQ,KAAK,SAAS;oBAC5B,CAAC,CAAC;wBACE,OAAO,EAAE,OAAO,CAAC,eAAe;wBAChC,KAAK,EAAE,kBAAkB;wBACzB,IAAI,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE;wBACpC,SAAS,EAAE,MAAM;wBACjB,OAAO,EAAE,QAAQ;qBAClB;oBACH,CAAC,CAAC;wBACE,OAAO,EAAE,OAAO,CAAC,eAAe;wBAChC,KAAK,EAAE,kBAAkB;wBACzB,SAAS,EAAE,MAAM;wBACjB,OAAO,EAAE,QAAQ;qBAClB,CAAC;gBACR,IAAI,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,CAAC,WAAoB,CAAC,CAAC;YAChE,CAAC;YAAC,MAAM,CAAC;gBACP,sDAAsD;gBACtD,MAAM,IAAI,uBAAuB,CAAC,gBAAgB,CAAC,CAAC;YACtD,CAAC;YAED,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;gBACvB,MAAM,OAAO,GAAG,qBAAqB,CAAC,GAAsB,CAAC,CAAC;gBAC9D,IAAI,OAAO,KAAK,IAAI;oBAAE,SAAS;gBAC/B,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC1B,CAAC;YAED,MAAM,GAAG,QAAQ,GAAG,EAAE,CAAC;QACzB,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,cAAc,CAAC,KAAoB;QACvC,yEAAyE;QACzE,6EAA6E;QAC7E,IAAI,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvB,IAAI,CAAC;gBACH,OAAO,MAAM,IAAI,CAAC,aAAa,CAAC,cAAc,EAAE,CAAC;YACnD,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,IAAI,uBAAuB,CAAC,uBAAuB,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QAED,IAAI,KAAK,KAAK,MAAM,IAAI,KAAK,KAAK,WAAW,EAAE,CAAC;YAC9C,MAAM,IAAI,yBAAyB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACrD,CAAC;QAED,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;YACrE,MAAM,GAAG,GAAG,KAAK,CAAC,MAAM,CAAC;YACzB,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;gBACjB,MAAM,IAAI,uBAAuB,CAAC,uBAAuB,CAAC,CAAC;YAC7D,CAAC;YACD,OAAO,GAAG,CAAC;QACb,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,uBAAuB;gBAAE,MAAM,GAAG,CAAC;YACtD,MAAM,IAAI,uBAAuB,CAAC,uBAAuB,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC;CACF;AAED;;;GAGG;AACH,SAAS,qBAAqB,CAAC,GAAoB;IACjD,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,CAAC;IACtB,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACpC,IACE,IAAI,CAAC,QAAQ,KAAK,SAAS;QAC3B,IAAI,CAAC,cAAc,KAAK,SAAS;QACjC,IAAI,CAAC,MAAM,KAAK,SAAS;QACzB,IAAI,CAAC,eAAe,KAAK,SAAS;QAClC,IAAI,CAAC,QAAQ,KAAK,SAAS,EAC3B,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IACE,GAAG,CAAC,WAAW,KAAK,SAAS;QAC7B,GAAG,CAAC,WAAW,KAAK,IAAI;QACxB,GAAG,CAAC,SAAS,KAAK,SAAS;QAC3B,GAAG,CAAC,SAAS,KAAK,IAAI;QACtB,GAAG,CAAC,eAAe,KAAK,SAAS;QACjC,GAAG,CAAC,eAAe,KAAK,IAAI;QAC5B,GAAG,CAAC,QAAQ,KAAK,SAAS;QAC1B,GAAG,CAAC,QAAQ,KAAK,IAAI,EACrB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,cAAc,EAAE,IAAI,CAAC,cAAc;QACnC,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,eAAe,EAAE,UAAU,CAAC,IAAI,CAAC,eAAe,CAAC;QACjD,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC;QACnC,WAAW,EAAE,GAAG,CAAC,WAAW;QAC5B,SAAS,EAAE,GAAG,CAAC,SAAS;QACxB,MAAM,EAAE,GAAG,CAAC,eAAe;QAC3B,QAAQ,EAAE,GAAG,CAAC,QAAQ;KACvB,CAAC;AACJ,CAAC"}