@shroud-fi/agent-runtime 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,71 @@
+# @shroud-fi/agent-runtime
+
+> The high-level ShroudFi surface most projects integrate against.
+
+[![npm](https://img.shields.io/npm/v/@shroud-fi/agent-runtime.svg)](https://www.npmjs.com/package/@shroud-fi/agent-runtime)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+
+```bash
+npm i @shroud-fi/agent-runtime viem
+```
+
+## What it does
+
+`@shroud-fi/agent-runtime` composes `@shroud-fi/core` + `@shroud-fi/payments` + `@shroud-fi/scanning` + `@shroud-fi/relayer` into a single `ShroudAgent` surface. One `createShroudAgent` call wires deterministic identity, transport, scanner, and sweep paths.
+
+Most agents only need this package — the lower-level building blocks (`core`, `payments`, `scanning`) are available if you need finer control.
+
+## Quick start
+
+```ts
+import { createShroudAgent } from '@shroud-fi/agent-runtime';
+
+const agent = await createShroudAgent({
+  chain: 'base',
+  masterSeed: process.env.SHROUDFI_MASTER_SEED!,
+  rpcUrl: process.env.SHROUDFI_RPC_URL!,
+});
+
+// 1. Register your meta-address (idempotent — no-op on second call)
+await agent.register();
+
+// 2. Send to a peer agent (by wallet — SDK looks up the meta-address)
+const USDC = '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913';
+await agent.sendToWallet('0xPeerWallet', { token: USDC }, 25_000_000n); // 25 USDC
+
+// 3. Detect incoming payments
+const detections = await agent.receive({ fromBlock: 46_800_000n });
+
+// 4. Sweep to your real wallet (gasless via relayer if ERC-20)
+for (const d of detections) {
+  await agent.sweep(d, '0xYourMain', { viaRelayer: true });
+}
+```
+
+## The four operations
+
+Every agent does the same four things:
+
+| Method | Purpose |
+|---|---|
+| `agent.register()` | Publish meta-address into the ERC-6538 registry. Idempotent. |
+| `agent.send(to, asset, amount)` | Send to a stealth meta-address (privacy-native) or a wallet (with auto-lookup). |
+| `agent.sendToWallet(wallet, asset, amount)` | Convenience: send to a plain wallet via meta-address resolution. |
+| `agent.receive(range)` | Scan a block range for inbound payments. |
+| `agent.sweep(detection, destination, opts?)` | Direct or relayer-routed sweep. Auto-routes ERC-20 via Gelato, ETH via EIP-7702 when `viaRelayer: true`. |
+
+## Exports
+
+| Symbol | Purpose |
+|---|---|
+| `createShroudAgent(cfg)` | The one entry point. |
+| `ShroudAgent` | Type of the returned object. |
+| `RelayerNotAvailableForETHError` | Thrown for `sweep({ viaRelayer: true })` when the ETH relayer isn't wired and the asset is native ETH. |
+
+Full API reference: [shroudfi.live/sdk#agent-runtime](https://shroudfi.live/sdk#agent-runtime)
+
+## License
+
+MIT — see [LICENSE](./LICENSE).
+
+Part of the [ShroudFi](https://shroudfi.live) privacy SDK for AI agents on Base.

package/dist/cjs/agent.d.ts

@@ -0,0 +1,235 @@
+/**
+ * ShroudAgent — the ergonomic runtime that composes core + payments + scanning
+ * + transport into a single class.
+ *
+ * Privacy invariants (binding — code-reviewer will check):
+ *   - No console.* anywhere in this file.
+ *   - No JSON.stringify of keys, identity, detection, signature, or masterSeed.
+ *   - No key bytes / signature bytes in error messages.
+ *   - No amount values in error messages.
+ *   - The spend key never leaves runtime; the scanning module needs it for
+ *     ECDH derivation only.
+ */
+import type { Address, Hash } from 'viem';
+import type { AgentIdentity, StealthMetaAddress } from '@shroud-fi/core';
+import type { PaymentReceipt, SendOptions, SendToWalletAsset } from '@shroud-fi/payments';
+import type { DetectedPayment, FinalityLevel, ScannerBackend } from '@shroud-fi/scanning';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { AgentRelayerEthSweepOptions, AgentRelayerEthSweepResult, AgentRelayerSweepOptions, AgentRelayerSweepResult, AgentSweepResult, ShroudAgentStartOptions } from './types.js';
+/**
+ * Internal options that construct a ShroudAgent. The factory + browser factory
+ * funnel all configuration into this shape so the class itself stays simple.
+ *
+ * @internal — not exported via the public barrel. Use createShroudAgent.
+ */
+export interface ShroudAgentInternalOptions {
+    readonly identity: AgentIdentity;
+    readonly transport: ShroudFiTransport;
+    readonly stealthContract: Address;
+    /** Override of the ERC-5564 announcer contract; defaults to canonical. */
+    readonly announcer?: Address;
+    readonly startBlock: bigint;
+    readonly finality?: FinalityLevel;
+    /** Test-only override of the scanner backend. Never set in production paths. */
+    readonly backend?: ScannerBackend;
+    /**
+     * M3 — when true, `sendToWallet` ensures the agent is registered in the
+     * canonical ERC-6538 registry before dispatching the payment.
+     */
+    readonly autoRegister?: boolean;
+}
+/**
+ * The ShroudAgent class. Wraps an EIP-5564 identity + the four ShroudFi
+ * packages behind a single ergonomic surface.
+ *
+ * Constructor is exported but typically reached through `createShroudAgent` or
+ * `createShroudAgentFromBrowserWallet`. Direct construction is supported for
+ * tests that need to inject a mock scanner backend.
+ */
+export declare class ShroudAgent {
+    readonly identity: AgentIdentity;
+    readonly metaAddress: StealthMetaAddress;
+    readonly metaAddressEncoded: string;
+    readonly transport: ShroudFiTransport;
+    readonly stealthContract: Address;
+    private readonly finality;
+    private readonly startBlock;
+    private readonly announcer;
+    private readonly backendOverride;
+    private readonly autoRegister;
+    private scanner;
+    private isStarted;
+    private controller;
+    constructor(opts: ShroudAgentInternalOptions);
+    /**
+     * Build a fresh Scanner with this agent's config. Called from start() so
+     * each lifecycle gets its own scanner instance (a closed scanner can't be
+     * reopened — see H8).
+     */
+    private buildScanner;
+    /**
+     * Start receiving detected payments.
+     *
+     * Returns an AsyncIterable; consumer drives via `for await`. If
+     * `opts.backfillFrom` is set, the first phase yields scanRange results,
+     * then transitions to live watch().
+     *
+     * @throws AgentAlreadyStartedError if called twice without stop().
+     */
+    start(opts?: ShroudAgentStartOptions): AsyncIterable<DetectedPayment>;
+    /**
+     * Stop the agent. Aborts the internal signal, closes the current scanner,
+     * and clears the reference so the next start() builds a fresh one.
+     * Idempotent — safe to call multiple times or before start().
+     */
+    stop(): void;
+    /**
+     * Send native ETH to a recipient stealth meta-address.
+     *
+     * Accepts either a parsed StealthMetaAddress or the encoded string form
+     * (`st:base:0x...`). String form is decoded via decodeMetaAddress before use.
+     */
+    send(to: StealthMetaAddress | string, valueWei: bigint): Promise<PaymentReceipt>;
+    /**
+     * Send an ERC-20 token to a recipient stealth meta-address.
+     *
+     * Caller MUST have already approved the stealth contract to spend the token
+     * — v1 does not include an approve flow.
+     */
+    sendERC20(to: StealthMetaAddress | string, token: Address, amount: bigint): Promise<PaymentReceipt>;
+    /**
+     * M3 — read the canonical ERC-6538 registry and return whether the agent's
+     * registrant wallet has a non-empty stealth meta-address on file for
+     * scheme 1 (the ShroudFi default).
+     *
+     * The registrant is keyed by `transport.walletClient.account.address` —
+     * the EOA that would sign the `registerKeys` transaction. Read-only
+     * transports (no walletClient or no account) cannot be registered and
+     * therefore return `false`.
+     *
+     * No side effects, no gas. Safe to call before every send.
+     */
+    isRegistered(): Promise<boolean>;
+    /**
+     * M3 — publish the agent's stealth meta-address (33-byte spending pubkey
+     * concatenated with 33-byte viewing pubkey) into the canonical ERC-6538
+     * registry under scheme 1.
+     *
+     * Throws `AlreadyRegisteredError` if the registrant wallet already has a
+     * non-empty entry. Throws `RegistrationRequiresWalletError` if the
+     * transport has no walletClient with an account.
+     *
+     * Privacy: only the agent's PUBLIC keys cross the wire (these are the
+     * same bytes that already live in `metaAddressEncoded`). The spending
+     * private key is never touched by this path.
+     *
+     * @returns the transaction hash of the `registerKeys` call.
+     */
+    register(): Promise<Hash>;
+    /**
+     * M3 — composite, idempotent registration helper.
+     *
+     * Returns `{ registered: false }` if the agent is already registered
+     * (no tx broadcast). Otherwise returns `{ registered: true, txHash }`
+     * with the registration tx hash.
+     *
+     * Safe to call before every send — the check is a single eth_call.
+     */
+    ensureRegistered(): Promise<{
+        registered: boolean;
+        txHash?: Hash;
+    }>;
+    /**
+     * M4 — ergonomic helper: pay an EVM wallet by its plain address, no
+     * meta-address handling on the caller side.
+     *
+     * Delegates to `sendToWallet` from `@shroud-fi/payments` which does the
+     * ERC-6538 registry lookup, decodes the recipient's stealth meta-address,
+     * and dispatches `sendETHPayment` or `sendERC20Payment` as appropriate.
+     *
+     * If the agent was constructed with `autoRegister: true`, this method
+     * calls `ensureRegistered` BEFORE dispatching the payment so the agent
+     * itself becomes reachable as a stealth-payment recipient the first time
+     * it pays someone. A failure inside `ensureRegistered` is wrapped in
+     * `AutoRegistrationFailedError` so callers can distinguish setup failures
+     * from payment failures via the `cause` chain.
+     *
+     * Privacy: the recipient wallet address never appears in error messages
+     * — `RecipientNotOnboardedError.wallet` exposes it on a structured field
+     * for callers that need to show a UI hint.
+     */
+    sendToWallet(recipientWallet: Address, asset: SendToWalletAsset, amount: bigint, options?: SendOptions): Promise<PaymentReceipt>;
+    /**
+     * Sweep funds from a detected stealth address to a destination.
+     *
+     * If `opts.token` is undefined or matches the ETH sentinel (or zero address)
+     * the agent dispatches to sweepETH; otherwise it dispatches to sweepERC20
+     * with the given token.
+     *
+     * Direct sweep (the default path) requires the stealth address to hold
+     * enough ETH to pay its own gas. When the stealth holds zero ETH set
+     * `opts.viaRelayer = true`:
+     *   - ERC-20 → routed to {@link sweepViaRelayer} (Gelato or self-host).
+     *   - ETH    → routed to {@link sweepEthViaRelayer} via EIP-7702 (P5.1).
+     *     Requires `opts.ethRelayerOptions.selfHostEndpoint` since there's no
+     *     third-party fallback for the 7702 path.
+     */
+    sweep(detection: DetectedPayment, destination: Address, opts?: {
+        token?: Address;
+        viaRelayer?: boolean;
+        relayerContract?: Address;
+        relayerOptions?: AgentRelayerSweepOptions;
+        ethRelayerContract?: Address;
+        ethRelayerOptions?: AgentRelayerEthSweepOptions;
+    }): Promise<AgentSweepResult | AgentRelayerSweepResult | AgentRelayerEthSweepResult>;
+    /**
+     * Gasless ERC-20 sweep via the ShroudFiRelayer + Gelato 1Balance.
+     *
+     * Lazy-imports `@shroud-fi/relayer` so the agent-runtime bundle stays small
+     * for callers that never use the relayer path. The Gelato SDK + axios + ws
+     * deps only land in the bundle when this method is actually called.
+     *
+     * Relayer contract resolution order:
+     *   1. `opts.relayerContract` if provided
+     *   2. `getRelayer(transport.chain.id)` lookup from `@shroud-fi/transport`
+     *   3. Throw `RelayerContractNotConfiguredError`
+     *
+     * @throws RelayerContractNotConfiguredError if no relayer is resolvable.
+     * @throws RelayerNotAvailableForETHError if the agent itself ever invokes
+     *         this with an ETH-like token (the dispatch in `sweep()` already
+     *         guards, this guards direct callers too).
+     */
+    sweepViaRelayer(detection: DetectedPayment, destination: Address, opts: {
+        token: Address;
+        relayerContract?: Address;
+        relayerOptions?: AgentRelayerSweepOptions;
+    }): Promise<AgentRelayerSweepResult>;
+    /**
+     * Self-host dispatch: sign the EIP-2612 permit, POST to the operator's
+     * service, return a Gelato-shaped receipt.
+     *
+     * Privacy: only the (public) permit signature + stealth address + token
+     * + destination cross the wire. The stealth private key never leaves the
+     * client.
+     */
+    private sweepViaSelfHost;
+    /**
+     * P5.1 — gasless ETH sweep via EIP-7702 + self-host relayer service.
+     *
+     * Dispatch order for the ShroudFiEthRelayer contract address:
+     *   1. `opts.ethRelayerContract` if provided
+     *   2. `getEthRelayer(transport.chain.id)` lookup
+     *   3. Throw EthRelayerContractNotConfiguredError
+     *
+     * Lazy-imports @shroud-fi/relayer so the agent-runtime bundle stays small
+     * for callers that never touch the gasless path.
+     *
+     * @throws EthRelayerContractNotConfiguredError if no contract is resolvable.
+     * @throws EthRelayerEndpointRequiredError if no self-host endpoint is provided.
+     */
+    sweepEthViaRelayer(detection: DetectedPayment, destination: Address, opts: {
+        ethRelayerContract?: Address;
+        relayerOptions: AgentRelayerEthSweepOptions;
+    }): Promise<AgentRelayerEthSweepResult>;
+}
+//# sourceMappingURL=agent.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,IAAI,EAAO,MAAM,MAAM,CAAC;AAM/C,OAAO,KAAK,EACV,aAAa,EACb,kBAAkB,EACnB,MAAM,iBAAiB,CAAC;AASzB,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAEb,cAAc,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAgB9D,OAAO,KAAK,EACV,2BAA2B,EAC3B,0BAA0B,EAC1B,wBAAwB,EACxB,uBAAuB,EACvB,gBAAgB,EAChB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAC;IAClC,gFAAgF;IAChF,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AASD;;;;;;;GAOG;AACH,qBAAa,WAAW;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC;IACtC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAElC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA6B;IAC7D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IACvC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAA8B;gBAEpC,IAAI,EAAE,0BAA0B;IAgB5C;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAYpB;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,uBAAuB,GAAG,aAAa,CAAC,eAAe,CAAC;IAwGrE;;;;OAIG;IACH,IAAI,IAAI,IAAI;IAoBZ;;;;;OAKG;IACG,IAAI,CACR,EAAE,EAAE,kBAAkB,GAAG,MAAM,EAC/B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,cAAc,CAAC;IAK1B;;;;;OAKG;IACG,SAAS,CACb,EAAE,EAAE,kBAAkB,GAAG,MAAM,EAC/B,KAAK,EAAE,OAAO,EACd,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,cAAc,CAAC;IAW1B;;;;;;;;;;;OAWG;IACG,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBtC;;;;;;;;;;;;;;OAcG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IA8C/B;;;;;;;;OAQG;IACG,gBAAgB,IAAI,OAAO,CAAC;QAChC,UAAU,EAAE,OAAO,CAAC;QACpB,MAAM,CAAC,EAAE,IAAI,CAAC;KACf,CAAC;IAQF;;;;;;;;;;;;;;;;;;OAkBG;IACG,YAAY,CAChB,eAAe,EAAE,OAAO,EACxB,KAAK,EAAE,iBAAiB,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,cAAc,CAAC;IAc1B;;;;;;;;;;;;;;OAcG;IACG,KAAK,CACT,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,OAAO,EACpB,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,OAAO,CAAC;QAChB,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,wBAAwB,CAAC;QAC1C,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,iBAAiB,CAAC,EAAE,2BAA2B,CAAC;KACjD,GACA,OAAO,CACR,gBAAgB,GAAG,uBAAuB,GAAG,0BAA0B,CACxE;IA2CD;;;;;;;;;;;;;;;;OAgBG;IACG,eAAe,CACnB,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,OAAO,EACpB,IAAI,EAAE;QACJ,KAAK,EAAE,OAAO,CAAC;QACf,eAAe,CAAC,EAAE,OAAO,CAAC;QAC1B,cAAc,CAAC,EAAE,wBAAwB,CAAC;KAC3C,GACA,OAAO,CAAC,uBAAuB,CAAC;IAoDnC;;;;;;;OAOG;YACW,gBAAgB;IA4E9B;;;;;;;;;;;;;OAaG;IACG,kBAAkB,CACtB,SAAS,EAAE,eAAe,EAC1B,WAAW,EAAE,OAAO,EACpB,IAAI,EAAE;QACJ,kBAAkB,CAAC,EAAE,OAAO,CAAC;QAC7B,cAAc,EAAE,2BAA2B,CAAC;KAC7C,GACA,OAAO,CAAC,0BAA0B,CAAC;CA0CvC"}