@shroud-fi/scanning

Receiver-side stealth payment detection for ShroudFi.

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

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

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.

Part of the ShroudFi privacy SDK for AI agents on Base.