@shroud-fi/agent-runtime 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +71 -0
  3. package/dist/cjs/agent.d.ts +235 -0
  4. package/dist/cjs/agent.d.ts.map +1 -0
  5. package/dist/cjs/agent.js +594 -0
  6. package/dist/cjs/agent.js.map +1 -0
  7. package/dist/cjs/browser.d.ts +38 -0
  8. package/dist/cjs/browser.d.ts.map +1 -0
  9. package/dist/cjs/browser.js +94 -0
  10. package/dist/cjs/browser.js.map +1 -0
  11. package/dist/cjs/constants.d.ts +17 -0
  12. package/dist/cjs/constants.d.ts.map +1 -0
  13. package/dist/cjs/constants.js +20 -0
  14. package/dist/cjs/constants.js.map +1 -0
  15. package/dist/cjs/errors.d.ts +107 -0
  16. package/dist/cjs/errors.d.ts.map +1 -0
  17. package/dist/cjs/errors.js +152 -0
  18. package/dist/cjs/errors.js.map +1 -0
  19. package/dist/cjs/factory.d.ts +19 -0
  20. package/dist/cjs/factory.d.ts.map +1 -0
  21. package/dist/cjs/factory.js +46 -0
  22. package/dist/cjs/factory.js.map +1 -0
  23. package/dist/cjs/index.d.ts +6 -0
  24. package/dist/cjs/index.d.ts.map +1 -0
  25. package/dist/cjs/index.js +37 -0
  26. package/dist/cjs/index.js.map +1 -0
  27. package/dist/cjs/package.json +1 -0
  28. package/dist/cjs/types.d.ts +151 -0
  29. package/dist/cjs/types.d.ts.map +1 -0
  30. package/dist/cjs/types.js +10 -0
  31. package/dist/cjs/types.js.map +1 -0
  32. package/dist/esm/agent.d.ts +235 -0
  33. package/dist/esm/agent.d.ts.map +1 -0
  34. package/dist/esm/agent.js +557 -0
  35. package/dist/esm/agent.js.map +1 -0
  36. package/dist/esm/browser.d.ts +38 -0
  37. package/dist/esm/browser.d.ts.map +1 -0
  38. package/dist/esm/browser.js +87 -0
  39. package/dist/esm/browser.js.map +1 -0
  40. package/dist/esm/constants.d.ts +17 -0
  41. package/dist/esm/constants.d.ts.map +1 -0
  42. package/dist/esm/constants.js +17 -0
  43. package/dist/esm/constants.js.map +1 -0
  44. package/dist/esm/errors.d.ts +107 -0
  45. package/dist/esm/errors.d.ts.map +1 -0
  46. package/dist/esm/errors.js +137 -0
  47. package/dist/esm/errors.js.map +1 -0
  48. package/dist/esm/factory.d.ts +19 -0
  49. package/dist/esm/factory.d.ts.map +1 -0
  50. package/dist/esm/factory.js +43 -0
  51. package/dist/esm/factory.js.map +1 -0
  52. package/dist/esm/index.d.ts +6 -0
  53. package/dist/esm/index.d.ts.map +1 -0
  54. package/dist/esm/index.js +16 -0
  55. package/dist/esm/index.js.map +1 -0
  56. package/dist/esm/types.d.ts +151 -0
  57. package/dist/esm/types.d.ts.map +1 -0
  58. package/dist/esm/types.js +9 -0
  59. package/dist/esm/types.js.map +1 -0
  60. package/dist/tsconfig.cjs.tsbuildinfo +1 -0
  61. package/dist/tsconfig.esm.tsbuildinfo +1 -0
  62. package/dist/tsconfig.tsbuildinfo +1 -0
  63. package/package.json +72 -0
@@ -0,0 +1,151 @@
1
+ /**
2
+ * Public types for @shroud-fi/agent-runtime.
3
+ *
4
+ * The runtime composes @shroud-fi/core + @shroud-fi/payments + @shroud-fi/scanning
5
+ * + @shroud-fi/transport behind a single ShroudAgent class. Types stay narrow:
6
+ * no leaky internal shapes from scanner detector or payment receipt parsing.
7
+ */
8
+ import type { Address, Hex } from 'viem';
9
+ import type { ShroudFiTransport } from '@shroud-fi/transport';
10
+ import type { DetectedPayment, FinalityLevel } from '@shroud-fi/scanning';
11
+ import type { SweepReceipt } from '@shroud-fi/payments';
12
+ /**
13
+ * Configuration for createShroudAgent (Path 1 — server / AI agent).
14
+ *
15
+ * `masterSeed` is the deterministic 32-byte root. If omitted, the underlying
16
+ * createAgentIdentity generates a random seed — useful for ephemeral testing
17
+ * but not for production agents (they cannot recover funds after restart).
18
+ */
19
+ export interface ShroudAgentConfig {
20
+ readonly masterSeed?: Uint8Array;
21
+ readonly transport: ShroudFiTransport;
22
+ /** Defaults to getShroudFiStealth(chainId) from @shroud-fi/transport. */
23
+ readonly stealthContract?: Address;
24
+ /**
25
+ * ERC-5564 announcer contract address. Defaults to the canonical singleton
26
+ * exported from @shroud-fi/transport. Override only for local Anvil testing
27
+ * where the canonical address is absent — production paths should never
28
+ * touch this.
29
+ */
30
+ readonly announcer?: Address;
31
+ readonly startBlock: bigint;
32
+ readonly finality?: FinalityLevel;
33
+ /**
34
+ * M3 — when `true`, `agent.sendToWallet` calls `ensureRegistered()` before
35
+ * dispatching the payment. The agent will publish its stealth meta-address
36
+ * into the canonical ERC-6538 registry the first time `sendToWallet` runs,
37
+ * making the agent itself reachable as a recipient by anyone who knows the
38
+ * registrant wallet address.
39
+ *
40
+ * Default `false` — preserves the existing send/sendERC20/sweep behavior
41
+ * for agents that never want to be a *recipient* of stealth payments.
42
+ *
43
+ * Auto-registration requires `transport.walletClient` with an account; if
44
+ * the walletClient is missing the registration step throws
45
+ * `RegistrationRequiresWalletError` wrapped in `AutoRegistrationFailedError`.
46
+ */
47
+ readonly autoRegister?: boolean;
48
+ }
49
+ /**
50
+ * Start-time options.
51
+ *
52
+ * `backfillFrom` opt-in switches start() to hybrid mode: first iterates
53
+ * scanRange(backfillFrom, latestSafe), then transitions to live watch().
54
+ * Useful for recovering payments missed while the agent was offline.
55
+ */
56
+ export interface ShroudAgentStartOptions {
57
+ readonly backfillFrom?: bigint;
58
+ readonly signal?: AbortSignal;
59
+ }
60
+ /**
61
+ * EIP-1193-compatible browser wallet adapter.
62
+ *
63
+ * Intentionally narrow: only the surface the browser factory actually uses.
64
+ * Callers wrap window.ethereum into this in the demo app. The runtime never
65
+ * touches window.ethereum directly to keep this package Node-safe.
66
+ */
67
+ export interface BrowserWalletAdapter {
68
+ readonly address: Address;
69
+ signMessage(message: string): Promise<Hex>;
70
+ }
71
+ /**
72
+ * Result returned by agent.sweep(). Wraps the underlying SweepReceipt with
73
+ * the originating detection so callers can correlate sweeps to detections
74
+ * without keeping a separate map.
75
+ */
76
+ export interface AgentSweepResult {
77
+ readonly swept: SweepReceipt;
78
+ readonly detection: DetectedPayment;
79
+ }
80
+ /**
81
+ * Subset of @shroud-fi/relayer's `RelayerSweepOptions` that the agent-runtime
82
+ * forwards verbatim. Re-typed locally so the agent-runtime type surface stays
83
+ * decoupled from the relayer package — callers that never touch the relayer
84
+ * still get a clean type tree without the optional peer dep being resolved.
85
+ */
86
+ export interface AgentRelayerSweepOptions {
87
+ readonly deadlineSecs?: bigint;
88
+ readonly pollIntervalMs?: number;
89
+ readonly pollTimeoutMs?: number;
90
+ readonly gelatoApiKey?: string;
91
+ readonly signal?: AbortSignal;
92
+ /**
93
+ * If set, the agent dispatches the sweep to a self-hosted relayer service
94
+ * via HTTP POST instead of Gelato. The endpoint must implement the
95
+ * `/relay` contract from `@shroud-fi/self-host-relayer`.
96
+ *
97
+ * Self-host bypasses Gelato entirely — useful for anon-stack deployments
98
+ * or when Gelato Gas Tank is paywalled.
99
+ */
100
+ readonly selfHostEndpoint?: string;
101
+ }
102
+ /**
103
+ * Result returned by agent.sweepViaRelayer(). Mirrors AgentSweepResult shape
104
+ * but wraps the relayer's `RelayerSweepReceipt` instead of `SweepReceipt`.
105
+ *
106
+ * The relayer receipt has NO amount fields (privacy invariant); the demo and
107
+ * other consumers can re-query balance if a display number is required.
108
+ */
109
+ export interface AgentRelayerSweepResult {
110
+ readonly swept: {
111
+ readonly taskId: string;
112
+ readonly txHash: Hex;
113
+ readonly status: 'submitted' | 'pending' | 'success' | 'failed' | 'cancelled';
114
+ readonly relayerContract: Address;
115
+ readonly token: Address;
116
+ readonly destination: Address;
117
+ readonly blockNumber?: bigint;
118
+ };
119
+ readonly detection: DetectedPayment;
120
+ }
121
+ /**
122
+ * P5.1 — options forwarded to relayedSweepETH. Locally typed so the
123
+ * agent-runtime type tree stays decoupled from @shroud-fi/relayer.
124
+ */
125
+ export interface AgentRelayerEthSweepOptions {
126
+ readonly deadlineSecs?: bigint;
127
+ readonly pollTimeoutMs?: number;
128
+ readonly signal?: AbortSignal;
129
+ /**
130
+ * Self-host relayer service URL. Required — there's no third-party fallback
131
+ * for the EIP-7702 path. Endpoint must implement POST /relay-eth per
132
+ * @shroud-fi/self-host-relayer.
133
+ */
134
+ readonly selfHostEndpoint: string;
135
+ }
136
+ /**
137
+ * P5.1 — result of agent.sweepEthViaRelayer(). Mirrors AgentSweepResult shape
138
+ * with the relayer's ETH receipt. No amount fields.
139
+ */
140
+ export interface AgentRelayerEthSweepResult {
141
+ readonly swept: {
142
+ readonly txHash: Hex;
143
+ readonly status: 'success';
144
+ readonly blockNumber: bigint;
145
+ readonly ethRelayerContract: Address;
146
+ readonly destination: Address;
147
+ readonly stealthAddress: Address;
148
+ };
149
+ readonly detection: DetectedPayment;
150
+ }
151
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,10 @@
1
+ "use strict";
2
+ /**
3
+ * Public types for @shroud-fi/agent-runtime.
4
+ *
5
+ * The runtime composes @shroud-fi/core + @shroud-fi/payments + @shroud-fi/scanning
6
+ * + @shroud-fi/transport behind a single ShroudAgent class. Types stay narrow:
7
+ * no leaky internal shapes from scanner detector or payment receipt parsing.
8
+ */
9
+ Object.defineProperty(exports, "__esModule", { value: true });
10
+ //# sourceMappingURL=types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}
@@ -0,0 +1,235 @@
1
+ /**
2
+ * ShroudAgent — the ergonomic runtime that composes core + payments + scanning
3
+ * + transport into a single class.
4
+ *
5
+ * Privacy invariants (binding — code-reviewer will check):
6
+ * - No console.* anywhere in this file.
7
+ * - No JSON.stringify of keys, identity, detection, signature, or masterSeed.
8
+ * - No key bytes / signature bytes in error messages.
9
+ * - No amount values in error messages.
10
+ * - The spend key never leaves runtime; the scanning module needs it for
11
+ * ECDH derivation only.
12
+ */
13
+ import type { Address, Hash } from 'viem';
14
+ import type { AgentIdentity, StealthMetaAddress } from '@shroud-fi/core';
15
+ import type { PaymentReceipt, SendOptions, SendToWalletAsset } from '@shroud-fi/payments';
16
+ import type { DetectedPayment, FinalityLevel, ScannerBackend } from '@shroud-fi/scanning';
17
+ import type { ShroudFiTransport } from '@shroud-fi/transport';
18
+ import type { AgentRelayerEthSweepOptions, AgentRelayerEthSweepResult, AgentRelayerSweepOptions, AgentRelayerSweepResult, AgentSweepResult, ShroudAgentStartOptions } from './types.js';
19
+ /**
20
+ * Internal options that construct a ShroudAgent. The factory + browser factory
21
+ * funnel all configuration into this shape so the class itself stays simple.
22
+ *
23
+ * @internal — not exported via the public barrel. Use createShroudAgent.
24
+ */
25
+ export interface ShroudAgentInternalOptions {
26
+ readonly identity: AgentIdentity;
27
+ readonly transport: ShroudFiTransport;
28
+ readonly stealthContract: Address;
29
+ /** Override of the ERC-5564 announcer contract; defaults to canonical. */
30
+ readonly announcer?: Address;
31
+ readonly startBlock: bigint;
32
+ readonly finality?: FinalityLevel;
33
+ /** Test-only override of the scanner backend. Never set in production paths. */
34
+ readonly backend?: ScannerBackend;
35
+ /**
36
+ * M3 — when true, `sendToWallet` ensures the agent is registered in the
37
+ * canonical ERC-6538 registry before dispatching the payment.
38
+ */
39
+ readonly autoRegister?: boolean;
40
+ }
41
+ /**
42
+ * The ShroudAgent class. Wraps an EIP-5564 identity + the four ShroudFi
43
+ * packages behind a single ergonomic surface.
44
+ *
45
+ * Constructor is exported but typically reached through `createShroudAgent` or
46
+ * `createShroudAgentFromBrowserWallet`. Direct construction is supported for
47
+ * tests that need to inject a mock scanner backend.
48
+ */
49
+ export declare class ShroudAgent {
50
+ readonly identity: AgentIdentity;
51
+ readonly metaAddress: StealthMetaAddress;
52
+ readonly metaAddressEncoded: string;
53
+ readonly transport: ShroudFiTransport;
54
+ readonly stealthContract: Address;
55
+ private readonly finality;
56
+ private readonly startBlock;
57
+ private readonly announcer;
58
+ private readonly backendOverride;
59
+ private readonly autoRegister;
60
+ private scanner;
61
+ private isStarted;
62
+ private controller;
63
+ constructor(opts: ShroudAgentInternalOptions);
64
+ /**
65
+ * Build a fresh Scanner with this agent's config. Called from start() so
66
+ * each lifecycle gets its own scanner instance (a closed scanner can't be
67
+ * reopened — see H8).
68
+ */
69
+ private buildScanner;
70
+ /**
71
+ * Start receiving detected payments.
72
+ *
73
+ * Returns an AsyncIterable; consumer drives via `for await`. If
74
+ * `opts.backfillFrom` is set, the first phase yields scanRange results,
75
+ * then transitions to live watch().
76
+ *
77
+ * @throws AgentAlreadyStartedError if called twice without stop().
78
+ */
79
+ start(opts?: ShroudAgentStartOptions): AsyncIterable<DetectedPayment>;
80
+ /**
81
+ * Stop the agent. Aborts the internal signal, closes the current scanner,
82
+ * and clears the reference so the next start() builds a fresh one.
83
+ * Idempotent — safe to call multiple times or before start().
84
+ */
85
+ stop(): void;
86
+ /**
87
+ * Send native ETH to a recipient stealth meta-address.
88
+ *
89
+ * Accepts either a parsed StealthMetaAddress or the encoded string form
90
+ * (`st:base:0x...`). String form is decoded via decodeMetaAddress before use.
91
+ */
92
+ send(to: StealthMetaAddress | string, valueWei: bigint): Promise<PaymentReceipt>;
93
+ /**
94
+ * Send an ERC-20 token to a recipient stealth meta-address.
95
+ *
96
+ * Caller MUST have already approved the stealth contract to spend the token
97
+ * — v1 does not include an approve flow.
98
+ */
99
+ sendERC20(to: StealthMetaAddress | string, token: Address, amount: bigint): Promise<PaymentReceipt>;
100
+ /**
101
+ * M3 — read the canonical ERC-6538 registry and return whether the agent's
102
+ * registrant wallet has a non-empty stealth meta-address on file for
103
+ * scheme 1 (the ShroudFi default).
104
+ *
105
+ * The registrant is keyed by `transport.walletClient.account.address` —
106
+ * the EOA that would sign the `registerKeys` transaction. Read-only
107
+ * transports (no walletClient or no account) cannot be registered and
108
+ * therefore return `false`.
109
+ *
110
+ * No side effects, no gas. Safe to call before every send.
111
+ */
112
+ isRegistered(): Promise<boolean>;
113
+ /**
114
+ * M3 — publish the agent's stealth meta-address (33-byte spending pubkey
115
+ * concatenated with 33-byte viewing pubkey) into the canonical ERC-6538
116
+ * registry under scheme 1.
117
+ *
118
+ * Throws `AlreadyRegisteredError` if the registrant wallet already has a
119
+ * non-empty entry. Throws `RegistrationRequiresWalletError` if the
120
+ * transport has no walletClient with an account.
121
+ *
122
+ * Privacy: only the agent's PUBLIC keys cross the wire (these are the
123
+ * same bytes that already live in `metaAddressEncoded`). The spending
124
+ * private key is never touched by this path.
125
+ *
126
+ * @returns the transaction hash of the `registerKeys` call.
127
+ */
128
+ register(): Promise<Hash>;
129
+ /**
130
+ * M3 — composite, idempotent registration helper.
131
+ *
132
+ * Returns `{ registered: false }` if the agent is already registered
133
+ * (no tx broadcast). Otherwise returns `{ registered: true, txHash }`
134
+ * with the registration tx hash.
135
+ *
136
+ * Safe to call before every send — the check is a single eth_call.
137
+ */
138
+ ensureRegistered(): Promise<{
139
+ registered: boolean;
140
+ txHash?: Hash;
141
+ }>;
142
+ /**
143
+ * M4 — ergonomic helper: pay an EVM wallet by its plain address, no
144
+ * meta-address handling on the caller side.
145
+ *
146
+ * Delegates to `sendToWallet` from `@shroud-fi/payments` which does the
147
+ * ERC-6538 registry lookup, decodes the recipient's stealth meta-address,
148
+ * and dispatches `sendETHPayment` or `sendERC20Payment` as appropriate.
149
+ *
150
+ * If the agent was constructed with `autoRegister: true`, this method
151
+ * calls `ensureRegistered` BEFORE dispatching the payment so the agent
152
+ * itself becomes reachable as a stealth-payment recipient the first time
153
+ * it pays someone. A failure inside `ensureRegistered` is wrapped in
154
+ * `AutoRegistrationFailedError` so callers can distinguish setup failures
155
+ * from payment failures via the `cause` chain.
156
+ *
157
+ * Privacy: the recipient wallet address never appears in error messages
158
+ * — `RecipientNotOnboardedError.wallet` exposes it on a structured field
159
+ * for callers that need to show a UI hint.
160
+ */
161
+ sendToWallet(recipientWallet: Address, asset: SendToWalletAsset, amount: bigint, options?: SendOptions): Promise<PaymentReceipt>;
162
+ /**
163
+ * Sweep funds from a detected stealth address to a destination.
164
+ *
165
+ * If `opts.token` is undefined or matches the ETH sentinel (or zero address)
166
+ * the agent dispatches to sweepETH; otherwise it dispatches to sweepERC20
167
+ * with the given token.
168
+ *
169
+ * Direct sweep (the default path) requires the stealth address to hold
170
+ * enough ETH to pay its own gas. When the stealth holds zero ETH set
171
+ * `opts.viaRelayer = true`:
172
+ * - ERC-20 → routed to {@link sweepViaRelayer} (Gelato or self-host).
173
+ * - ETH → routed to {@link sweepEthViaRelayer} via EIP-7702 (P5.1).
174
+ * Requires `opts.ethRelayerOptions.selfHostEndpoint` since there's no
175
+ * third-party fallback for the 7702 path.
176
+ */
177
+ sweep(detection: DetectedPayment, destination: Address, opts?: {
178
+ token?: Address;
179
+ viaRelayer?: boolean;
180
+ relayerContract?: Address;
181
+ relayerOptions?: AgentRelayerSweepOptions;
182
+ ethRelayerContract?: Address;
183
+ ethRelayerOptions?: AgentRelayerEthSweepOptions;
184
+ }): Promise<AgentSweepResult | AgentRelayerSweepResult | AgentRelayerEthSweepResult>;
185
+ /**
186
+ * Gasless ERC-20 sweep via the ShroudFiRelayer + Gelato 1Balance.
187
+ *
188
+ * Lazy-imports `@shroud-fi/relayer` so the agent-runtime bundle stays small
189
+ * for callers that never use the relayer path. The Gelato SDK + axios + ws
190
+ * deps only land in the bundle when this method is actually called.
191
+ *
192
+ * Relayer contract resolution order:
193
+ * 1. `opts.relayerContract` if provided
194
+ * 2. `getRelayer(transport.chain.id)` lookup from `@shroud-fi/transport`
195
+ * 3. Throw `RelayerContractNotConfiguredError`
196
+ *
197
+ * @throws RelayerContractNotConfiguredError if no relayer is resolvable.
198
+ * @throws RelayerNotAvailableForETHError if the agent itself ever invokes
199
+ * this with an ETH-like token (the dispatch in `sweep()` already
200
+ * guards, this guards direct callers too).
201
+ */
202
+ sweepViaRelayer(detection: DetectedPayment, destination: Address, opts: {
203
+ token: Address;
204
+ relayerContract?: Address;
205
+ relayerOptions?: AgentRelayerSweepOptions;
206
+ }): Promise<AgentRelayerSweepResult>;
207
+ /**
208
+ * Self-host dispatch: sign the EIP-2612 permit, POST to the operator's
209
+ * service, return a Gelato-shaped receipt.
210
+ *
211
+ * Privacy: only the (public) permit signature + stealth address + token
212
+ * + destination cross the wire. The stealth private key never leaves the
213
+ * client.
214
+ */
215
+ private sweepViaSelfHost;
216
+ /**
217
+ * P5.1 — gasless ETH sweep via EIP-7702 + self-host relayer service.
218
+ *
219
+ * Dispatch order for the ShroudFiEthRelayer contract address:
220
+ * 1. `opts.ethRelayerContract` if provided
221
+ * 2. `getEthRelayer(transport.chain.id)` lookup
222
+ * 3. Throw EthRelayerContractNotConfiguredError
223
+ *
224
+ * Lazy-imports @shroud-fi/relayer so the agent-runtime bundle stays small
225
+ * for callers that never touch the gasless path.
226
+ *
227
+ * @throws EthRelayerContractNotConfiguredError if no contract is resolvable.
228
+ * @throws EthRelayerEndpointRequiredError if no self-host endpoint is provided.
229
+ */
230
+ sweepEthViaRelayer(detection: DetectedPayment, destination: Address, opts: {
231
+ ethRelayerContract?: Address;
232
+ relayerOptions: AgentRelayerEthSweepOptions;
233
+ }): Promise<AgentRelayerEthSweepResult>;
234
+ }
235
+ //# sourceMappingURL=agent.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/agent.ts"],"names":[],"mappings":"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"}