@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.
- package/LICENSE +21 -0
- package/README.md +71 -0
- package/dist/cjs/agent.d.ts +235 -0
- package/dist/cjs/agent.d.ts.map +1 -0
- package/dist/cjs/agent.js +594 -0
- package/dist/cjs/agent.js.map +1 -0
- package/dist/cjs/browser.d.ts +38 -0
- package/dist/cjs/browser.d.ts.map +1 -0
- package/dist/cjs/browser.js +94 -0
- package/dist/cjs/browser.js.map +1 -0
- package/dist/cjs/constants.d.ts +17 -0
- package/dist/cjs/constants.d.ts.map +1 -0
- package/dist/cjs/constants.js +20 -0
- package/dist/cjs/constants.js.map +1 -0
- package/dist/cjs/errors.d.ts +107 -0
- package/dist/cjs/errors.d.ts.map +1 -0
- package/dist/cjs/errors.js +152 -0
- package/dist/cjs/errors.js.map +1 -0
- package/dist/cjs/factory.d.ts +19 -0
- package/dist/cjs/factory.d.ts.map +1 -0
- package/dist/cjs/factory.js +46 -0
- package/dist/cjs/factory.js.map +1 -0
- package/dist/cjs/index.d.ts +6 -0
- package/dist/cjs/index.d.ts.map +1 -0
- package/dist/cjs/index.js +37 -0
- package/dist/cjs/index.js.map +1 -0
- package/dist/cjs/package.json +1 -0
- package/dist/cjs/types.d.ts +151 -0
- package/dist/cjs/types.d.ts.map +1 -0
- package/dist/cjs/types.js +10 -0
- package/dist/cjs/types.js.map +1 -0
- package/dist/esm/agent.d.ts +235 -0
- package/dist/esm/agent.d.ts.map +1 -0
- package/dist/esm/agent.js +557 -0
- package/dist/esm/agent.js.map +1 -0
- package/dist/esm/browser.d.ts +38 -0
- package/dist/esm/browser.d.ts.map +1 -0
- package/dist/esm/browser.js +87 -0
- package/dist/esm/browser.js.map +1 -0
- package/dist/esm/constants.d.ts +17 -0
- package/dist/esm/constants.d.ts.map +1 -0
- package/dist/esm/constants.js +17 -0
- package/dist/esm/constants.js.map +1 -0
- package/dist/esm/errors.d.ts +107 -0
- package/dist/esm/errors.d.ts.map +1 -0
- package/dist/esm/errors.js +137 -0
- package/dist/esm/errors.js.map +1 -0
- package/dist/esm/factory.d.ts +19 -0
- package/dist/esm/factory.d.ts.map +1 -0
- package/dist/esm/factory.js +43 -0
- package/dist/esm/factory.js.map +1 -0
- package/dist/esm/index.d.ts +6 -0
- package/dist/esm/index.d.ts.map +1 -0
- package/dist/esm/index.js +16 -0
- package/dist/esm/index.js.map +1 -0
- package/dist/esm/types.d.ts +151 -0
- package/dist/esm/types.d.ts.map +1 -0
- package/dist/esm/types.js +9 -0
- package/dist/esm/types.js.map +1 -0
- package/dist/tsconfig.cjs.tsbuildinfo +1 -0
- package/dist/tsconfig.esm.tsbuildinfo +1 -0
- package/dist/tsconfig.tsbuildinfo +1 -0
- 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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"}
|