@shroud-fi/agent-runtime 0.1.5 → 0.1.6

package/src/types.ts

@@ -0,0 +1,176 @@
+/**
+ * Public types for @shroud-fi/agent-runtime.
+ *
+ * The runtime composes @shroud-fi/core + @shroud-fi/payments + @shroud-fi/scanning
+ * + @shroud-fi/transport behind a single ShroudAgent class. Types stay narrow:
+ * no leaky internal shapes from scanner detector or payment receipt parsing.
+ */
+
+import type { Address, Hex } from 'viem';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { DetectedPayment, FinalityLevel } from '@shroud-fi/scanning';
+import type { SweepReceipt } from '@shroud-fi/payments';
+
+/**
+ * Configuration for createShroudAgent (Path 1 — server / AI agent).
+ *
+ * `masterSeed` is the deterministic 32-byte root. If omitted, the underlying
+ * createAgentIdentity generates a random seed — useful for ephemeral testing
+ * but not for production agents (they cannot recover funds after restart).
+ */
+export interface ShroudAgentConfig {
+  readonly masterSeed?: Uint8Array;
+  readonly transport: ShroudFiTransport;
+  /** Defaults to getShroudFiStealth(chainId) from @shroud-fi/transport. */
+  readonly stealthContract?: Address;
+  /**
+   * ERC-5564 announcer contract address. Defaults to the canonical singleton
+   * exported from @shroud-fi/transport. Override only for local Anvil testing
+   * where the canonical address is absent — production paths should never
+   * touch this.
+   */
+  readonly announcer?: Address;
+  readonly startBlock: bigint;
+  readonly finality?: FinalityLevel;
+  /**
+   * M3 — when `true`, `agent.sendToWallet` calls `ensureRegistered()` before
+   * dispatching the payment. The agent will publish its stealth meta-address
+   * into the canonical ERC-6538 registry the first time `sendToWallet` runs,
+   * making the agent itself reachable as a recipient by anyone who knows the
+   * registrant wallet address.
+   *
+   * Default `false` — preserves the existing send/sendERC20/sweep behavior
+   * for agents that never want to be a *recipient* of stealth payments.
+   *
+   * Auto-registration requires `transport.walletClient` with an account; if
+   * the walletClient is missing the registration step throws
+   * `RegistrationRequiresWalletError` wrapped in `AutoRegistrationFailedError`.
+   */
+  readonly autoRegister?: boolean;
+}
+
+/**
+ * Start-time options.
+ *
+ * `backfillFrom` opt-in switches start() to hybrid mode: first iterates
+ * scanRange(backfillFrom, latestSafe), then transitions to live watch().
+ * Useful for recovering payments missed while the agent was offline.
+ */
+export interface ShroudAgentStartOptions {
+  readonly backfillFrom?: bigint;
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * EIP-1193-compatible browser wallet adapter.
+ *
+ * Intentionally narrow: only the surface the browser factory actually uses.
+ * Callers wrap window.ethereum into this in the demo app. The runtime never
+ * touches window.ethereum directly to keep this package Node-safe.
+ */
+export interface BrowserWalletAdapter {
+  readonly address: Address;
+  signMessage(message: string): Promise<Hex>;
+}
+
+/**
+ * Result returned by agent.sweep(). Wraps the underlying SweepReceipt with
+ * the originating detection so callers can correlate sweeps to detections
+ * without keeping a separate map.
+ */
+export interface AgentSweepResult {
+  readonly swept: SweepReceipt;
+  readonly detection: DetectedPayment;
+}
+
+/**
+ * Subset of @shroud-fi/relayer's `RelayerSweepOptions` that the agent-runtime
+ * forwards verbatim. Re-typed locally so the agent-runtime type surface stays
+ * decoupled from the relayer package — callers that never touch the relayer
+ * still get a clean type tree without the optional peer dep being resolved.
+ */
+export interface AgentRelayerSweepOptions {
+  readonly deadlineSecs?: bigint;
+  readonly pollIntervalMs?: number;
+  readonly pollTimeoutMs?: number;
+  readonly gelatoApiKey?: string;
+  readonly signal?: AbortSignal;
+  /**
+   * If set, the agent dispatches the sweep to a self-hosted relayer service
+   * via HTTP POST instead of Gelato. The endpoint must implement the
+   * `/relay` contract from `@shroud-fi/self-host-relayer`.
+   *
+   * Self-host bypasses Gelato entirely — useful for anon-stack deployments
+   * or when Gelato Gas Tank is paywalled.
+   */
+  readonly selfHostEndpoint?: string;
+}
+
+/**
+ * Result returned by agent.sweepViaRelayer(). Mirrors AgentSweepResult shape
+ * but wraps the relayer's `RelayerSweepReceipt` instead of `SweepReceipt`.
+ *
+ * The relayer receipt has NO amount fields (privacy invariant); the demo and
+ * other consumers can re-query balance if a display number is required.
+ */
+export interface AgentRelayerSweepResult {
+  readonly swept: {
+    readonly taskId: string;
+    readonly txHash: Hex;
+    readonly status: 'submitted' | 'pending' | 'success' | 'failed' | 'cancelled';
+    readonly relayerContract: Address;
+    readonly token: Address;
+    readonly destination: Address;
+    readonly blockNumber?: bigint;
+  };
+  readonly detection: DetectedPayment;
+}
+
+/**
+ * P5.1 — options forwarded to relayedSweepETH. Locally typed so the
+ * agent-runtime type tree stays decoupled from @shroud-fi/relayer.
+ */
+export interface AgentRelayerEthSweepOptions {
+  readonly deadlineSecs?: bigint;
+  readonly pollTimeoutMs?: number;
+  readonly signal?: AbortSignal;
+  /**
+   * Self-host relayer service URL. Required — there's no third-party fallback
+   * for the EIP-7702 path. Endpoint must implement POST /relay-eth per
+   * @shroud-fi/self-host-relayer.
+   */
+  readonly selfHostEndpoint: string;
+}
+
+/**
+ * P5.1 — result of agent.sweepEthViaRelayer(). Mirrors AgentSweepResult shape
+ * with the relayer's ETH receipt. No amount fields.
+ */
+export interface AgentRelayerEthSweepResult {
+  readonly swept: {
+    readonly txHash: Hex;
+    readonly status: 'success';
+    readonly blockNumber: bigint;
+    readonly ethRelayerContract: Address;
+    readonly destination: Address;
+    readonly stealthAddress: Address;
+  };
+  readonly detection: DetectedPayment;
+}
+
+/**
+ * v0.1.1 — address-book contact kind. 'wallet' = 20-byte EVM address (used
+ * with sendToWallet); 'meta' = `st:base:0x…` stealth meta-address (used with
+ * send).
+ */
+export type ContactKind = 'wallet' | 'meta';
+
+/**
+ * v0.1.1 — a single address-book entry. Fully local, never on-chain.
+ */
+export interface Contact {
+  readonly label: string;
+  readonly kind: ContactKind;
+  readonly value: string;
+  readonly addedAt: string;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist/esm",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "test", "examples", "node_modules"]
+}