@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,87 @@
1
+ /**
2
+ * createShroudAgentFromBrowserWallet — browser / EIP-1193 wallet entry point.
3
+ *
4
+ * Flow:
5
+ * 1. Ask the wallet to sign BROWSER_KEY_MESSAGE via personal_sign.
6
+ * 2. HKDF the signature bytes to a deterministic 32-byte master seed.
7
+ * 3. Delegate to createShroudAgent.
8
+ *
9
+ * The same wallet always produces the same agent identity — no localStorage,
10
+ * no persistence. Bumping BROWSER_KEY_MESSAGE forks the identity space.
11
+ *
12
+ * Privacy invariants:
13
+ * - No console.* anywhere.
14
+ * - The signature bytes never appear in error messages or stack frames.
15
+ * - The derived master seed is passed to createShroudAgent and immediately
16
+ * consumed by createAgentIdentity; no caller-visible reference is retained.
17
+ */
18
+ import { hkdf } from '@noble/hashes/hkdf';
19
+ import { sha256 } from '@noble/hashes/sha256';
20
+ import { createShroudAgent } from './factory.js';
21
+ import { BROWSER_KEY_MESSAGE, BROWSER_MASTER_SEED_LENGTH, HKDF_BROWSER_INFO, HKDF_BROWSER_SALT, } from './constants.js';
22
+ import { BrowserWalletSignatureRejectedError, MissingBrowserWalletError, } from './errors.js';
23
+ export { BROWSER_KEY_MESSAGE, HKDF_BROWSER_SALT, HKDF_BROWSER_INFO, } from './constants.js';
24
+ /**
25
+ * Decode a 0x-prefixed hex string (e.g. an EIP-191 signature) into bytes.
26
+ * Returns null on malformed input — callers map this to a privacy-safe error
27
+ * rather than surfacing the raw value.
28
+ */
29
+ function hexToBytesSafe(hex) {
30
+ if (typeof hex !== 'string')
31
+ return null;
32
+ const stripped = hex.startsWith('0x') ? hex.slice(2) : hex;
33
+ if (stripped.length === 0 || stripped.length % 2 !== 0)
34
+ return null;
35
+ const out = new Uint8Array(stripped.length / 2);
36
+ for (let i = 0; i < out.length; i++) {
37
+ const byte = parseInt(stripped.slice(i * 2, i * 2 + 2), 16);
38
+ if (Number.isNaN(byte))
39
+ return null;
40
+ out[i] = byte;
41
+ }
42
+ return out;
43
+ }
44
+ /**
45
+ * Build a ShroudAgent from a browser wallet adapter (e.g. MetaMask).
46
+ *
47
+ * @throws MissingBrowserWalletError if the adapter is missing required fields.
48
+ * @throws BrowserWalletSignatureRejectedError if the signature request is rejected.
49
+ */
50
+ export async function createShroudAgentFromBrowserWallet(args) {
51
+ const wallet = args.wallet;
52
+ if (wallet === undefined ||
53
+ wallet === null ||
54
+ typeof wallet.signMessage !== 'function' ||
55
+ typeof wallet.address !== 'string' ||
56
+ !wallet.address.startsWith('0x')) {
57
+ throw new MissingBrowserWalletError();
58
+ }
59
+ let signature;
60
+ try {
61
+ signature = await wallet.signMessage(BROWSER_KEY_MESSAGE);
62
+ }
63
+ catch {
64
+ // Never surface the underlying rejection reason — could embed wallet
65
+ // metadata or user prompt text.
66
+ throw new BrowserWalletSignatureRejectedError();
67
+ }
68
+ const sigBytes = hexToBytesSafe(signature);
69
+ if (sigBytes === null || sigBytes.length === 0) {
70
+ throw new BrowserWalletSignatureRejectedError();
71
+ }
72
+ // HKDF-SHA256: extract + expand the signature into a deterministic 32-byte
73
+ // master seed. The signature is the IKM, not the salt — salt and info are
74
+ // constant version tags.
75
+ const masterSeed = hkdf(sha256, sigBytes, HKDF_BROWSER_SALT, HKDF_BROWSER_INFO, BROWSER_MASTER_SEED_LENGTH);
76
+ const config = {
77
+ masterSeed,
78
+ transport: args.transport,
79
+ startBlock: args.startBlock,
80
+ ...(args.stealthContract !== undefined
81
+ ? { stealthContract: args.stealthContract }
82
+ : {}),
83
+ ...(args.finality !== undefined ? { finality: args.finality } : {}),
84
+ };
85
+ return createShroudAgent(config);
86
+ }
87
+ //# sourceMappingURL=browser.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Agent runtime constants.
3
+ *
4
+ * BROWSER_KEY_MESSAGE is the personal-sign payload the browser factory asks
5
+ * MetaMask (or any EIP-1193 wallet) to sign. It is HKDF'd into a deterministic
6
+ * 32-byte master seed so the same wallet always produces the same agent
7
+ * identity — no localStorage, no key persistence.
8
+ *
9
+ * Versioning the message string is load-bearing: bumping `-v1` to `-v2` will
10
+ * derive a different identity even for the same wallet. Treat as a one-way
11
+ * cryptographic input; never rename without a migration story.
12
+ */
13
+ export declare const BROWSER_KEY_MESSAGE = "ShroudFi-Demo-Key-Derivation-v1";
14
+ export declare const HKDF_BROWSER_SALT: Uint8Array<ArrayBuffer>;
15
+ export declare const HKDF_BROWSER_INFO: Uint8Array<ArrayBuffer>;
16
+ export declare const BROWSER_MASTER_SEED_LENGTH = 32;
17
+ //# sourceMappingURL=constants.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,mBAAmB,oCACG,CAAC;AAEpC,eAAO,MAAM,iBAAiB,yBAA+C,CAAC;AAC9E,eAAO,MAAM,iBAAiB,yBAAgD,CAAC;AAE/E,eAAO,MAAM,0BAA0B,KAAK,CAAC"}
@@ -0,0 +1,17 @@
1
+ /**
2
+ * Agent runtime constants.
3
+ *
4
+ * BROWSER_KEY_MESSAGE is the personal-sign payload the browser factory asks
5
+ * MetaMask (or any EIP-1193 wallet) to sign. It is HKDF'd into a deterministic
6
+ * 32-byte master seed so the same wallet always produces the same agent
7
+ * identity — no localStorage, no key persistence.
8
+ *
9
+ * Versioning the message string is load-bearing: bumping `-v1` to `-v2` will
10
+ * derive a different identity even for the same wallet. Treat as a one-way
11
+ * cryptographic input; never rename without a migration story.
12
+ */
13
+ export const BROWSER_KEY_MESSAGE = 'ShroudFi-Demo-Key-Derivation-v1';
14
+ export const HKDF_BROWSER_SALT = new TextEncoder().encode('ShroudFi-Demo-v1');
15
+ export const HKDF_BROWSER_INFO = new TextEncoder().encode('agent-master-seed');
16
+ export const BROWSER_MASTER_SEED_LENGTH = 32;
17
+ //# sourceMappingURL=constants.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,iCAAiC,CAAC;AAEpC,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,CAAC;AAE/E,MAAM,CAAC,MAAM,0BAA0B,GAAG,EAAE,CAAC"}
@@ -0,0 +1,107 @@
1
+ /**
2
+ * Privacy-safe error classes for @shroud-fi/agent-runtime.
3
+ *
4
+ * Invariants (mirrored from @shroud-fi/scanning + @shroud-fi/payments):
5
+ * - No 32-byte hex (key material) in any message.
6
+ * - No ephemeral pubkey bytes in any message.
7
+ * - No raw signature bytes in any message.
8
+ * - No transfer amounts in any message.
9
+ * - Messages carry short, structured reasons only.
10
+ */
11
+ export declare class AgentRuntimeError extends Error {
12
+ readonly name: string;
13
+ constructor(message: string);
14
+ }
15
+ export declare class AgentNotStartedError extends AgentRuntimeError {
16
+ readonly name: string;
17
+ constructor();
18
+ }
19
+ export declare class AgentAlreadyStartedError extends AgentRuntimeError {
20
+ readonly name: string;
21
+ constructor();
22
+ }
23
+ export declare class MissingBrowserWalletError extends AgentRuntimeError {
24
+ readonly name: string;
25
+ constructor();
26
+ }
27
+ export declare class BrowserWalletSignatureRejectedError extends AgentRuntimeError {
28
+ readonly name: string;
29
+ constructor();
30
+ }
31
+ /**
32
+ * Thrown when `sweepViaRelayer` is called but no relayer contract has been
33
+ * registered for the agent's chain. Callers can pass an explicit
34
+ * `relayerContract` to override the lookup.
35
+ */
36
+ export declare class RelayerContractNotConfiguredError extends AgentRuntimeError {
37
+ readonly name: string;
38
+ constructor();
39
+ }
40
+ /**
41
+ * P5.1 — thrown when the caller tries to use the ETH gasless sweep path but
42
+ * has not provided a `selfHostEndpoint`. ETH gasless requires a self-host
43
+ * relayer service that builds + broadcasts the EIP-7702 type-0x04 tx; there
44
+ * is no third-party fallback (Gelato's 7702 surface is wallet-shaped, not
45
+ * relayer-shaped).
46
+ */
47
+ export declare class EthRelayerEndpointRequiredError extends AgentRuntimeError {
48
+ readonly name: string;
49
+ constructor();
50
+ }
51
+ /**
52
+ * P5.1 — thrown when no ShroudFiEthRelayer contract has been registered for
53
+ * the agent's chain and the caller did not pass `ethRelayerContract` to
54
+ * override the manifest lookup.
55
+ */
56
+ export declare class EthRelayerContractNotConfiguredError extends AgentRuntimeError {
57
+ readonly name: string;
58
+ constructor();
59
+ }
60
+ /**
61
+ * @deprecated Retained as a soft-removed export — callers updated to use
62
+ * EthRelayerEndpointRequiredError or the gasless ETH path directly. P5.1
63
+ * activated the previously-stubbed ETH-via-relayer path.
64
+ */
65
+ export declare class RelayerNotAvailableForETHError extends AgentRuntimeError {
66
+ readonly name: string;
67
+ constructor();
68
+ }
69
+ /**
70
+ * M3 — thrown when `register()` is called but the agent's registrant wallet
71
+ * already has a non-empty stealth meta-address on file in the canonical
72
+ * ERC-6538 registry for scheme 1. Callers should treat this as benign and
73
+ * skip the registration tx; `ensureRegistered` does this automatically.
74
+ *
75
+ * Privacy: the registrant wallet address is NOT placed in `.message` — it
76
+ * would link the agent's runtime wallet to the error log. Callers who need
77
+ * to display the wallet must source it from `transport.walletClient.account`
78
+ * themselves.
79
+ */
80
+ export declare class AlreadyRegisteredError extends AgentRuntimeError {
81
+ readonly name: string;
82
+ constructor();
83
+ }
84
+ /**
85
+ * M3 — wraps an underlying error thrown while `ensureRegistered` runs inside
86
+ * `agent.sendToWallet` with `autoRegister: true`. Preserves the original via
87
+ * the standard `cause` chain so callers can introspect without parsing
88
+ * strings.
89
+ *
90
+ * Privacy: the inner error MUST itself comply with the runtime's no-amount /
91
+ * no-wallet / no-key rule. This wrapper never inlines key, signature, or
92
+ * amount material into its own message.
93
+ */
94
+ export declare class AutoRegistrationFailedError extends AgentRuntimeError {
95
+ readonly name: string;
96
+ constructor(cause?: unknown);
97
+ }
98
+ /**
99
+ * M3 — thrown when `register()` is invoked on a transport that has no
100
+ * `walletClient` (or no account on the walletClient). Registration is a state
101
+ * change tx that needs a signer; read-only transports cannot register.
102
+ */
103
+ export declare class RegistrationRequiresWalletError extends AgentRuntimeError {
104
+ readonly name: string;
105
+ constructor();
106
+ }
107
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAkB,IAAI,EAAE,MAAM,CAAuB;gBACzC,OAAO,EAAE,MAAM;CAG5B;AAED,qBAAa,oBAAqB,SAAQ,iBAAiB;IACzD,SAAkB,IAAI,EAAE,MAAM,CAA0B;;CAIzD;AAED,qBAAa,wBAAyB,SAAQ,iBAAiB;IAC7D,SAAkB,IAAI,EAAE,MAAM,CAA8B;;CAI7D;AAED,qBAAa,yBAA0B,SAAQ,iBAAiB;IAC9D,SAAkB,IAAI,EAAE,MAAM,CAA+B;;CAI9D;AAED,qBAAa,mCAAoC,SAAQ,iBAAiB;IACxE,SAAkB,IAAI,EAAE,MAAM,CAAyC;;CAIxE;AAED;;;;GAIG;AACH,qBAAa,iCAAkC,SAAQ,iBAAiB;IACtE,SAAkB,IAAI,EAAE,MAAM,CAAuC;;CAItE;AAED;;;;;;GAMG;AACH,qBAAa,+BAAgC,SAAQ,iBAAiB;IACpE,SAAkB,IAAI,EAAE,MAAM,CAAqC;;CAMpE;AAED;;;;GAIG;AACH,qBAAa,oCAAqC,SAAQ,iBAAiB;IACzE,SAAkB,IAAI,EAAE,MAAM,CAA0C;;CAIzE;AAED;;;;GAIG;AACH,qBAAa,8BAA+B,SAAQ,iBAAiB;IACnE,SAAkB,IAAI,EAAE,MAAM,CAAoC;;CAInE;AAED;;;;;;;;;;GAUG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,SAAkB,IAAI,EAAE,MAAM,CAA4B;;CAI3D;AAED;;;;;;;;;GASG;AACH,qBAAa,2BAA4B,SAAQ,iBAAiB;IAChE,SAAkB,IAAI,EAAE,MAAM,CAAiC;gBACnD,KAAK,CAAC,EAAE,OAAO;CAS5B;AAED;;;;GAIG;AACH,qBAAa,+BAAgC,SAAQ,iBAAiB;IACpE,SAAkB,IAAI,EAAE,MAAM,CAAqC;;CAIpE"}
@@ -0,0 +1,137 @@
1
+ /**
2
+ * Privacy-safe error classes for @shroud-fi/agent-runtime.
3
+ *
4
+ * Invariants (mirrored from @shroud-fi/scanning + @shroud-fi/payments):
5
+ * - No 32-byte hex (key material) in any message.
6
+ * - No ephemeral pubkey bytes in any message.
7
+ * - No raw signature bytes in any message.
8
+ * - No transfer amounts in any message.
9
+ * - Messages carry short, structured reasons only.
10
+ */
11
+ export class AgentRuntimeError extends Error {
12
+ name = 'AgentRuntimeError';
13
+ constructor(message) {
14
+ super(message);
15
+ }
16
+ }
17
+ export class AgentNotStartedError extends AgentRuntimeError {
18
+ name = 'AgentNotStartedError';
19
+ constructor() {
20
+ super('Agent has not been started — call start() first');
21
+ }
22
+ }
23
+ export class AgentAlreadyStartedError extends AgentRuntimeError {
24
+ name = 'AgentAlreadyStartedError';
25
+ constructor() {
26
+ super('Agent already started — call stop() before start() again');
27
+ }
28
+ }
29
+ export class MissingBrowserWalletError extends AgentRuntimeError {
30
+ name = 'MissingBrowserWalletError';
31
+ constructor() {
32
+ super('Browser wallet adapter missing required signMessage or address');
33
+ }
34
+ }
35
+ export class BrowserWalletSignatureRejectedError extends AgentRuntimeError {
36
+ name = 'BrowserWalletSignatureRejectedError';
37
+ constructor() {
38
+ super('Browser wallet rejected signature request');
39
+ }
40
+ }
41
+ /**
42
+ * Thrown when `sweepViaRelayer` is called but no relayer contract has been
43
+ * registered for the agent's chain. Callers can pass an explicit
44
+ * `relayerContract` to override the lookup.
45
+ */
46
+ export class RelayerContractNotConfiguredError extends AgentRuntimeError {
47
+ name = 'RelayerContractNotConfiguredError';
48
+ constructor() {
49
+ super('Relayer contract not configured for this chain');
50
+ }
51
+ }
52
+ /**
53
+ * P5.1 — thrown when the caller tries to use the ETH gasless sweep path but
54
+ * has not provided a `selfHostEndpoint`. ETH gasless requires a self-host
55
+ * relayer service that builds + broadcasts the EIP-7702 type-0x04 tx; there
56
+ * is no third-party fallback (Gelato's 7702 surface is wallet-shaped, not
57
+ * relayer-shaped).
58
+ */
59
+ export class EthRelayerEndpointRequiredError extends AgentRuntimeError {
60
+ name = 'EthRelayerEndpointRequiredError';
61
+ constructor() {
62
+ super('ETH gasless sweep requires a self-host relayer endpoint — pass relayerOptions.selfHostEndpoint');
63
+ }
64
+ }
65
+ /**
66
+ * P5.1 — thrown when no ShroudFiEthRelayer contract has been registered for
67
+ * the agent's chain and the caller did not pass `ethRelayerContract` to
68
+ * override the manifest lookup.
69
+ */
70
+ export class EthRelayerContractNotConfiguredError extends AgentRuntimeError {
71
+ name = 'EthRelayerContractNotConfiguredError';
72
+ constructor() {
73
+ super('ShroudFiEthRelayer contract not configured for this chain');
74
+ }
75
+ }
76
+ /**
77
+ * @deprecated Retained as a soft-removed export — callers updated to use
78
+ * EthRelayerEndpointRequiredError or the gasless ETH path directly. P5.1
79
+ * activated the previously-stubbed ETH-via-relayer path.
80
+ */
81
+ export class RelayerNotAvailableForETHError extends AgentRuntimeError {
82
+ name = 'RelayerNotAvailableForETHError';
83
+ constructor() {
84
+ super('Relayer sweep does not support ETH — use direct sweep or ERC-20');
85
+ }
86
+ }
87
+ /**
88
+ * M3 — thrown when `register()` is called but the agent's registrant wallet
89
+ * already has a non-empty stealth meta-address on file in the canonical
90
+ * ERC-6538 registry for scheme 1. Callers should treat this as benign and
91
+ * skip the registration tx; `ensureRegistered` does this automatically.
92
+ *
93
+ * Privacy: the registrant wallet address is NOT placed in `.message` — it
94
+ * would link the agent's runtime wallet to the error log. Callers who need
95
+ * to display the wallet must source it from `transport.walletClient.account`
96
+ * themselves.
97
+ */
98
+ export class AlreadyRegisteredError extends AgentRuntimeError {
99
+ name = 'AlreadyRegisteredError';
100
+ constructor() {
101
+ super('Agent is already registered in the ERC-6538 registry');
102
+ }
103
+ }
104
+ /**
105
+ * M3 — wraps an underlying error thrown while `ensureRegistered` runs inside
106
+ * `agent.sendToWallet` with `autoRegister: true`. Preserves the original via
107
+ * the standard `cause` chain so callers can introspect without parsing
108
+ * strings.
109
+ *
110
+ * Privacy: the inner error MUST itself comply with the runtime's no-amount /
111
+ * no-wallet / no-key rule. This wrapper never inlines key, signature, or
112
+ * amount material into its own message.
113
+ */
114
+ export class AutoRegistrationFailedError extends AgentRuntimeError {
115
+ name = 'AutoRegistrationFailedError';
116
+ constructor(cause) {
117
+ super('Auto-registration failed');
118
+ // Use the standard ES2022 `cause` slot. Avoid serializing the inner
119
+ // error into the message itself — the privacy invariant tests would
120
+ // catch a leak if the wrapped error embedded sensitive bytes.
121
+ if (cause !== undefined) {
122
+ this.cause = cause;
123
+ }
124
+ }
125
+ }
126
+ /**
127
+ * M3 — thrown when `register()` is invoked on a transport that has no
128
+ * `walletClient` (or no account on the walletClient). Registration is a state
129
+ * change tx that needs a signer; read-only transports cannot register.
130
+ */
131
+ export class RegistrationRequiresWalletError extends AgentRuntimeError {
132
+ name = 'RegistrationRequiresWalletError';
133
+ constructor() {
134
+ super('Registration requires a walletClient with an account');
135
+ }
136
+ }
137
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACxB,IAAI,GAAW,mBAAmB,CAAC;IACrD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;IACjB,CAAC;CACF;AAED,MAAM,OAAO,oBAAqB,SAAQ,iBAAiB;IACvC,IAAI,GAAW,sBAAsB,CAAC;IACxD;QACE,KAAK,CAAC,iDAAiD,CAAC,CAAC;IAC3D,CAAC;CACF;AAED,MAAM,OAAO,wBAAyB,SAAQ,iBAAiB;IAC3C,IAAI,GAAW,0BAA0B,CAAC;IAC5D;QACE,KAAK,CAAC,0DAA0D,CAAC,CAAC;IACpE,CAAC;CACF;AAED,MAAM,OAAO,yBAA0B,SAAQ,iBAAiB;IAC5C,IAAI,GAAW,2BAA2B,CAAC;IAC7D;QACE,KAAK,CAAC,gEAAgE,CAAC,CAAC;IAC1E,CAAC;CACF;AAED,MAAM,OAAO,mCAAoC,SAAQ,iBAAiB;IACtD,IAAI,GAAW,qCAAqC,CAAC;IACvE;QACE,KAAK,CAAC,2CAA2C,CAAC,CAAC;IACrD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iCAAkC,SAAQ,iBAAiB;IACpD,IAAI,GAAW,mCAAmC,CAAC;IACrE;QACE,KAAK,CAAC,gDAAgD,CAAC,CAAC;IAC1D,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,OAAO,+BAAgC,SAAQ,iBAAiB;IAClD,IAAI,GAAW,iCAAiC,CAAC;IACnE;QACE,KAAK,CACH,gGAAgG,CACjG,CAAC;IACJ,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,oCAAqC,SAAQ,iBAAiB;IACvD,IAAI,GAAW,sCAAsC,CAAC;IACxE;QACE,KAAK,CAAC,2DAA2D,CAAC,CAAC;IACrE,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,8BAA+B,SAAQ,iBAAiB;IACjD,IAAI,GAAW,gCAAgC,CAAC;IAClE;QACE,KAAK,CAAC,iEAAiE,CAAC,CAAC;IAC3E,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,sBAAuB,SAAQ,iBAAiB;IACzC,IAAI,GAAW,wBAAwB,CAAC;IAC1D;QACE,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAChE,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,2BAA4B,SAAQ,iBAAiB;IAC9C,IAAI,GAAW,6BAA6B,CAAC;IAC/D,YAAY,KAAe;QACzB,KAAK,CAAC,0BAA0B,CAAC,CAAC;QAClC,oEAAoE;QACpE,oEAAoE;QACpE,8DAA8D;QAC9D,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACvB,IAA4B,CAAC,KAAK,GAAG,KAAK,CAAC;QAC9C,CAAC;IACH,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,+BAAgC,SAAQ,iBAAiB;IAClD,IAAI,GAAW,iCAAiC,CAAC;IACnE;QACE,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAChE,CAAC;CACF"}
@@ -0,0 +1,19 @@
1
+ /**
2
+ * createShroudAgent — server / Node entry point.
3
+ *
4
+ * Validates configuration, resolves the stealth contract address from the
5
+ * transport's chain, builds an AgentIdentity from the optional master seed,
6
+ * and constructs a ShroudAgent.
7
+ *
8
+ * Privacy: no seed or key bytes ever appear in error messages. Validation
9
+ * errors are short structured reasons only.
10
+ */
11
+ import { ShroudAgent } from './agent.js';
12
+ import type { ShroudAgentConfig } from './types.js';
13
+ /**
14
+ * Build a fully-wired ShroudAgent from a config.
15
+ *
16
+ * @throws AgentRuntimeError on missing/invalid transport or negative startBlock.
17
+ */
18
+ export declare function createShroudAgent(config: ShroudAgentConfig): ShroudAgent;
19
+ //# sourceMappingURL=factory.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAGzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,WAAW,CA2BxE"}
@@ -0,0 +1,43 @@
1
+ /**
2
+ * createShroudAgent — server / Node entry point.
3
+ *
4
+ * Validates configuration, resolves the stealth contract address from the
5
+ * transport's chain, builds an AgentIdentity from the optional master seed,
6
+ * and constructs a ShroudAgent.
7
+ *
8
+ * Privacy: no seed or key bytes ever appear in error messages. Validation
9
+ * errors are short structured reasons only.
10
+ */
11
+ import { createAgentIdentity } from '@shroud-fi/core';
12
+ import { getShroudFiStealth } from '@shroud-fi/transport';
13
+ import { ShroudAgent } from './agent.js';
14
+ import { AgentRuntimeError } from './errors.js';
15
+ /**
16
+ * Build a fully-wired ShroudAgent from a config.
17
+ *
18
+ * @throws AgentRuntimeError on missing/invalid transport or negative startBlock.
19
+ */
20
+ export function createShroudAgent(config) {
21
+ if (config.transport === undefined || config.transport.publicClient === undefined) {
22
+ throw new AgentRuntimeError('transport.publicClient is required');
23
+ }
24
+ if (config.startBlock < 0n) {
25
+ throw new AgentRuntimeError('startBlock must be non-negative');
26
+ }
27
+ const chainId = config.transport.chain.id;
28
+ const stealthContract = config.stealthContract ?? getShroudFiStealth(chainId);
29
+ const identity = createAgentIdentity(config.masterSeed);
30
+ const opts = {
31
+ identity,
32
+ transport: config.transport,
33
+ stealthContract,
34
+ startBlock: config.startBlock,
35
+ ...(config.finality !== undefined ? { finality: config.finality } : {}),
36
+ ...(config.announcer !== undefined ? { announcer: config.announcer } : {}),
37
+ ...(config.autoRegister !== undefined
38
+ ? { autoRegister: config.autoRegister }
39
+ : {}),
40
+ };
41
+ return new ShroudAgent(opts);
42
+ }
43
+ //# sourceMappingURL=factory.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAGhD;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAyB;IACzD,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;QAClF,MAAM,IAAI,iBAAiB,CAAC,oCAAoC,CAAC,CAAC;IACpE,CAAC;IACD,IAAI,MAAM,CAAC,UAAU,GAAG,EAAE,EAAE,CAAC;QAC3B,MAAM,IAAI,iBAAiB,CAAC,iCAAiC,CAAC,CAAC;IACjE,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;IAC1C,MAAM,eAAe,GACnB,MAAM,CAAC,eAAe,IAAI,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAExD,MAAM,QAAQ,GAAG,mBAAmB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAExD,MAAM,IAAI,GAA+B;QACvC,QAAQ;QACR,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,eAAe;QACf,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvE,GAAG,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1E,GAAG,CAAC,MAAM,CAAC,YAAY,KAAK,SAAS;YACnC,CAAC,CAAC,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE;YACvC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IAEF,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC"}
@@ -0,0 +1,6 @@
1
+ export { ShroudAgent } from './agent.js';
2
+ export { createShroudAgent } from './factory.js';
3
+ export { createShroudAgentFromBrowserWallet, BROWSER_KEY_MESSAGE, HKDF_BROWSER_SALT, HKDF_BROWSER_INFO, } from './browser.js';
4
+ export type { ShroudAgentConfig, ShroudAgentStartOptions, BrowserWalletAdapter, AgentSweepResult, AgentRelayerSweepOptions, AgentRelayerSweepResult, AgentRelayerEthSweepOptions, AgentRelayerEthSweepResult, } from './types.js';
5
+ export { AgentRuntimeError, AgentNotStartedError, AgentAlreadyStartedError, MissingBrowserWalletError, BrowserWalletSignatureRejectedError, RelayerNotAvailableForETHError, RelayerContractNotConfiguredError, EthRelayerEndpointRequiredError, EthRelayerContractNotConfiguredError, AlreadyRegisteredError, AutoRegistrationFailedError, RegistrationRequiresWalletError, } from './errors.js';
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kCAAkC,EAClC,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,iBAAiB,EACjB,uBAAuB,EACvB,oBAAoB,EACpB,gBAAgB,EAChB,wBAAwB,EACxB,uBAAuB,EACvB,2BAA2B,EAC3B,0BAA0B,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,mCAAmC,EACnC,8BAA8B,EAC9B,iCAAiC,EACjC,+BAA+B,EAC/B,oCAAoC,EACpC,sBAAsB,EACtB,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,aAAa,CAAC"}
@@ -0,0 +1,16 @@
1
+ // Public surface — @shroud-fi/agent-runtime
2
+ //
3
+ // Phase 4: ergonomic wrapper around @shroud-fi/core + @shroud-fi/payments +
4
+ // @shroud-fi/scanning + @shroud-fi/transport. Two construction paths:
5
+ // - createShroudAgent(config) — server / Node / AI agent (deterministic seed)
6
+ // - createShroudAgentFromBrowserWallet(args) — browser (MetaMask-derived seed)
7
+ //
8
+ // Re-exports trimmed to what callers actually need; deeper helpers stay
9
+ // inside the upstream packages.
10
+ // Class + factories
11
+ export { ShroudAgent } from './agent.js';
12
+ export { createShroudAgent } from './factory.js';
13
+ export { createShroudAgentFromBrowserWallet, BROWSER_KEY_MESSAGE, HKDF_BROWSER_SALT, HKDF_BROWSER_INFO, } from './browser.js';
14
+ // Errors
15
+ export { AgentRuntimeError, AgentNotStartedError, AgentAlreadyStartedError, MissingBrowserWalletError, BrowserWalletSignatureRejectedError, RelayerNotAvailableForETHError, RelayerContractNotConfiguredError, EthRelayerEndpointRequiredError, EthRelayerContractNotConfiguredError, AlreadyRegisteredError, AutoRegistrationFailedError, RegistrationRequiresWalletError, } from './errors.js';
16
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,4CAA4C;AAC5C,EAAE;AACF,4EAA4E;AAC5E,sEAAsE;AACtE,gFAAgF;AAChF,iFAAiF;AACjF,EAAE;AACF,wEAAwE;AACxE,gCAAgC;AAEhC,oBAAoB;AACpB,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,EACL,kCAAkC,EAClC,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AActB,SAAS;AACT,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,wBAAwB,EACxB,yBAAyB,EACzB,mCAAmC,EACnC,8BAA8B,EAC9B,iCAAiC,EACjC,+BAA+B,EAC/B,oCAAoC,EACpC,sBAAsB,EACtB,2BAA2B,EAC3B,+BAA+B,GAChC,MAAM,aAAa,CAAC"}
@@ -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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"}