@shroud-fi/agent-runtime 0.1.4 → 0.1.6

package/src/agent.ts

@@ -0,0 +1,829 @@
+/**
+ * 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, Hex } from 'viem';
+import { bytesToHex, concatBytes } from 'viem';
+import {
+  encodeMetaAddress,
+  decodeMetaAddress,
+} from '@shroud-fi/core';
+import type {
+  AgentIdentity,
+  StealthMetaAddress,
+} from '@shroud-fi/core';
+import {
+  sendETHPayment,
+  sendERC20Payment,
+  sendToWallet,
+  sweepETH,
+  sweepERC20,
+  ETH_SENTINEL,
+} from '@shroud-fi/payments';
+import type {
+  PaymentReceipt,
+  SendOptions,
+  SendToWalletAsset,
+} from '@shroud-fi/payments';
+import { createScanner } from '@shroud-fi/scanning';
+import type {
+  DetectedPayment,
+  FinalityLevel,
+  Scanner,
+  ScannerBackend,
+} from '@shroud-fi/scanning';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import {
+  ERC6538_REGISTRY,
+  ERC6538RegistryAbi,
+  getRelayer,
+  getEthRelayer,
+} from '@shroud-fi/transport';
+import {
+  AgentAlreadyStartedError,
+  AlreadyRegisteredError,
+  AutoRegistrationFailedError,
+  EthRelayerContractNotConfiguredError,
+  EthRelayerEndpointRequiredError,
+  RegistrationRequiresWalletError,
+  RelayerContractNotConfiguredError,
+} from './errors.js';
+import { ContactBook } from './contacts.js';
+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;
+  /**
+   * v0.1.1 — optional override of the address-book JSON path. Defaults to
+   * `~/.shroudfi/contacts.json`. Tests / sandboxed agents may want a tmpdir.
+   */
+  readonly contactsFilePath?: string;
+}
+
+/**
+ * ETH zero-address sentinel — some callers may pass this to indicate "ETH" on
+ * the sweep dispatch. Kept beside the canonical ETH_SENTINEL constant.
+ */
+const ZERO_ADDRESS_ETH: Address =
+  '0x0000000000000000000000000000000000000000';
+
+/**
+ * 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 class ShroudAgent {
+  readonly identity: AgentIdentity;
+  readonly metaAddress: StealthMetaAddress;
+  readonly metaAddressEncoded: string;
+  readonly transport: ShroudFiTransport;
+  readonly stealthContract: Address;
+  /**
+   * v0.1.1 — local-only address book. Pure persistence layer. ShroudFi never
+   * uses contact data on the network; resolving a label to an address is the
+   * caller's job. See `ContactBook` in @shroud-fi/agent-runtime.
+   *
+   * Built LAZILY on first access (see the getter below). ContactBook's
+   * constructor touches os.homedir()/fs to resolve + read its JSON file; doing
+   * that eagerly in the ShroudAgent constructor crashed browser bundles where
+   * webpack stubs fs/os/path to {} → "Connection failed (TypeError)" the moment
+   * a wallet connected. Browser agents that never call `.contacts` now never
+   * reach the filesystem. See test/browser-contacts-lazy.test.ts.
+   */
+  private _contacts: ContactBook | undefined;
+  private readonly contactsFilePath: string | undefined;
+
+  private readonly finality: FinalityLevel;
+  private readonly startBlock: bigint;
+  private readonly announcer: Address | undefined;
+  private readonly backendOverride: ScannerBackend | undefined;
+  private readonly autoRegister: boolean;
+  private scanner: Scanner | undefined;
+  private isStarted = false;
+  private controller: AbortController | undefined;
+
+  constructor(opts: ShroudAgentInternalOptions) {
+    this.identity = opts.identity;
+    this.metaAddress = opts.identity.metaAddress;
+    this.metaAddressEncoded = encodeMetaAddress(opts.identity.metaAddress);
+    this.transport = opts.transport;
+    this.stealthContract = opts.stealthContract;
+    this.startBlock = opts.startBlock;
+    this.finality = opts.finality ?? 'safe';
+    this.announcer = opts.announcer;
+    this.backendOverride = opts.backend;
+    this.autoRegister = opts.autoRegister ?? false;
+    // Stash the path only — the ContactBook (and its os/fs access) is deferred
+    // to the `contacts` getter so plain connect/scan flows never touch disk.
+    this.contactsFilePath = opts.contactsFilePath;
+    // Scanner is built lazily in start() — see H8 in docs/debug/P4-STEP3-STALL.md.
+    // Reusing one Scanner across start/stop/start cycles silently dropped events
+    // because Scanner.close() permanently sets its `closed` flag.
+  }
+
+  /**
+   * Local-only address book, constructed on first access. Node consumers use
+   * `agent.contacts.add(...)` exactly as before; browser consumers that never
+   * touch it never construct a ContactBook and so never reach os/fs.
+   */
+  get contacts(): ContactBook {
+    if (this._contacts === undefined) {
+      this._contacts =
+        this.contactsFilePath !== undefined
+          ? new ContactBook({ filePath: this.contactsFilePath })
+          : new ContactBook();
+    }
+    return this._contacts;
+  }
+
+  /**
+   * 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(): Scanner {
+    return createScanner({
+      transport: this.transport,
+      scanningKey: this.identity.keys.scanningKey,
+      spendingKey: this.identity.keys.spendingKey,
+      startBlock: this.startBlock,
+      finality: this.finality,
+      ...(this.announcer !== undefined ? { contractAddress: this.announcer } : {}),
+      ...(this.backendOverride !== undefined ? { backend: this.backendOverride } : {}),
+    });
+  }
+
+  /**
+   * 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> {
+    if (this.isStarted) {
+      throw new AgentAlreadyStartedError();
+    }
+    this.isStarted = true;
+
+    const controller = new AbortController();
+    this.controller = controller;
+
+    // Forward external signal to internal controller.
+    const externalSignal = opts?.signal;
+    if (externalSignal !== undefined) {
+      if (externalSignal.aborted) {
+        controller.abort();
+      } else {
+        externalSignal.addEventListener(
+          'abort',
+          () => controller.abort(),
+          { once: true },
+        );
+      }
+    }
+
+    // Build a fresh scanner for THIS start() cycle. Reusing the same scanner
+    // across start/stop/start would silently drop events because Scanner.close()
+    // sets a permanent `closed` flag inside detector.ts. See H8.
+    const scanner = this.buildScanner();
+    this.scanner = scanner;
+
+    const finality = this.finality;
+    const transport = this.transport;
+    const backfillFrom = opts?.backfillFrom;
+    const resetStarted = (): void => {
+      this.isStarted = false;
+    };
+
+    // EAGERLY open the live watch subscription before this method returns.
+    // `scanner.watch()` is lazy — the backend.watchAnnouncements registration
+    // only fires when [Symbol.asyncIterator]() is called. If we left this to
+    // the generator body below (which runs on first iter.next()), a caller
+    // pattern like:
+    //   const iter = agent.start();
+    //   await agent.send(...)           // tx mines before we subscribe
+    //   for await (const d of iter) ... // never sees the event
+    // would race and miss the announcement. Subscribing here closes the gap.
+    const watchIterator: AsyncIterator<DetectedPayment> =
+      scanner.watch(controller.signal)[Symbol.asyncIterator]();
+
+    return {
+      [Symbol.asyncIterator]: async function* () {
+        try {
+          if (backfillFrom !== undefined) {
+            // Determine the latest block we can backfill to. The tag mirrors
+            // the configured finality so unfinalized history is not yielded
+            // for 'safe' / 'finalized' callers. 'unsafe' callers (and chains
+            // that don't track 'safe'/'finalized' — e.g. Anvil) use 'latest'
+            // so the backfill reaches the actual head.
+            const tag: 'finalized' | 'safe' | 'latest' =
+              finality === 'finalized'
+                ? 'finalized'
+                : finality === 'safe'
+                  ? 'safe'
+                  : 'latest';
+            const latestBlock = await transport.publicClient.getBlock({
+              blockTag: tag,
+            });
+            const latestSafe = latestBlock.number ?? backfillFrom;
+
+            if (latestSafe >= backfillFrom) {
+              for await (const detection of scanner.scanRange(
+                backfillFrom,
+                latestSafe,
+                controller.signal,
+              )) {
+                if (controller.signal.aborted) return;
+                yield detection;
+              }
+            }
+          }
+
+          // Drain the live watch iterator we eagerly opened above.
+          while (true) {
+            if (controller.signal.aborted) return;
+            const r = await watchIterator.next();
+            if (r.done) return;
+            yield r.value;
+          }
+        } finally {
+          // Tear down the eagerly-opened watch iterator so scanner.watchActive
+          // resets and a follow-up start() can resubscribe.
+          try {
+            await watchIterator.return?.({
+              value: undefined,
+              done: true,
+            } as IteratorResult<DetectedPayment>);
+          } catch {
+            // close path must never throw out of finally.
+          }
+          resetStarted();
+        }
+      },
+    };
+  }
+
+  /**
+   * 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 {
+    if (this.controller !== undefined) {
+      try {
+        this.controller.abort();
+      } catch {
+        // Swallow — stop must not throw.
+      }
+      this.controller = undefined;
+    }
+    if (this.scanner !== undefined) {
+      try {
+        this.scanner.close();
+      } catch {
+        // Swallow — stop must not throw.
+      }
+      this.scanner = undefined;
+    }
+    this.isStarted = false;
+  }
+
+  /**
+   * 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.
+   */
+  async send(
+    to: StealthMetaAddress | string,
+    valueWei: bigint,
+  ): Promise<PaymentReceipt> {
+    const meta = typeof to === 'string' ? decodeMetaAddress(to) : to;
+    return sendETHPayment(this.transport, this.stealthContract, meta, valueWei);
+  }
+
+  /**
+   * 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.
+   */
+  async sendERC20(
+    to: StealthMetaAddress | string,
+    token: Address,
+    amount: bigint,
+  ): Promise<PaymentReceipt> {
+    const meta = typeof to === 'string' ? decodeMetaAddress(to) : to;
+    return sendERC20Payment(
+      this.transport,
+      this.stealthContract,
+      meta,
+      token,
+      amount,
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async isRegistered(): Promise<boolean> {
+    const walletClient = this.transport.walletClient;
+    if (walletClient === undefined) return false;
+    const account = walletClient.account;
+    if (account === undefined) return false;
+    const registrant = account.address;
+
+    const raw = (await this.transport.publicClient.readContract({
+      address: ERC6538_REGISTRY,
+      abi: ERC6538RegistryAbi,
+      functionName: 'stealthMetaAddressOf',
+      args: [registrant, REGISTRY_SCHEME_ID],
+    })) as Hex;
+
+    // viem returns '0x' for empty bytes. Anything longer is a registration.
+    return raw !== '0x' && raw.length > 2;
+  }
+
+  /**
+   * 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.
+   */
+  async register(): Promise<Hash> {
+    const walletClient = this.transport.walletClient;
+    if (walletClient === undefined) {
+      throw new RegistrationRequiresWalletError();
+    }
+    const account = walletClient.account;
+    if (account === undefined) {
+      throw new RegistrationRequiresWalletError();
+    }
+
+    // Fail fast if already registered. This both saves the operator a gas
+    // payment and keeps `register()` honest: the only way to overwrite an
+    // existing entry on the canonical registry is to bump the per-scheme
+    // nonce, which is out of scope for v1.
+    if (await this.isRegistered()) {
+      throw new AlreadyRegisteredError();
+    }
+
+    // Build the 66-byte payload: 33 spending pubkey || 33 viewing pubkey.
+    // The registrar contract layout is confirmed by
+    // contracts/src/ShroudFiRegistrar.sol (each pubkey is a compressed
+    // secp256k1 point — 33 bytes, prefix 0x02 / 0x03).
+    const payload = concatBytes([
+      this.metaAddress.spendingPubKey,
+      this.metaAddress.viewingPubKey,
+    ]);
+    const stealthMetaAddress = bytesToHex(payload);
+
+    const writeArgs: Record<string, unknown> = {
+      address: ERC6538_REGISTRY,
+      abi: ERC6538RegistryAbi,
+      functionName: 'registerKeys',
+      args: [REGISTRY_SCHEME_ID, stealthMetaAddress],
+      account,
+      chain: this.transport.chain,
+    };
+
+    // viem's writeContract has a complex union signature — cast at the
+    // boundary, mirroring the pattern used in @shroud-fi/payments.
+    const txHash = (await (
+      walletClient.writeContract as (a: unknown) => Promise<Hash>
+    )(writeArgs)) as Hash;
+
+    return txHash;
+  }
+
+  /**
+   * 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.
+   */
+  async ensureRegistered(): Promise<{
+    registered: boolean;
+    txHash?: Hash;
+  }> {
+    if (await this.isRegistered()) {
+      return { registered: false };
+    }
+    const txHash = await this.register();
+    return { registered: true, txHash };
+  }
+
+  /**
+   * 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.
+   */
+  async sendToWallet(
+    recipientWallet: Address,
+    asset: SendToWalletAsset,
+    amount: bigint,
+    options?: SendOptions,
+  ): Promise<PaymentReceipt> {
+    if (this.autoRegister) {
+      try {
+        await this.ensureRegistered();
+      } catch (err) {
+        // Preserve the underlying cause so callers can introspect (e.g.,
+        // tell apart a missing walletClient from an RPC error). The wrapper
+        // message itself is privacy-safe — see AutoRegistrationFailedError.
+        throw new AutoRegistrationFailedError(err);
+      }
+    }
+    return sendToWallet(this.transport, recipientWallet, asset, amount, options);
+  }
+
+  /**
+   * 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.
+   */
+  async sweep(
+    detection: DetectedPayment,
+    destination: Address,
+    opts?: {
+      token?: Address;
+      viaRelayer?: boolean;
+      relayerContract?: Address;
+      relayerOptions?: AgentRelayerSweepOptions;
+      ethRelayerContract?: Address;
+      ethRelayerOptions?: AgentRelayerEthSweepOptions;
+    },
+  ): Promise<
+    AgentSweepResult | AgentRelayerSweepResult | AgentRelayerEthSweepResult
+  > {
+    const token = opts?.token;
+    const isEth =
+      token === undefined ||
+      token === ZERO_ADDRESS_ETH ||
+      token.toLowerCase() === ETH_SENTINEL.toLowerCase();
+
+    if (opts?.viaRelayer === true) {
+      if (isEth) {
+        if (opts.ethRelayerOptions === undefined) {
+          throw new EthRelayerEndpointRequiredError();
+        }
+        return this.sweepEthViaRelayer(detection, destination, {
+          ...(opts.ethRelayerContract !== undefined
+            ? { ethRelayerContract: opts.ethRelayerContract }
+            : {}),
+          relayerOptions: opts.ethRelayerOptions,
+        });
+      }
+      return this.sweepViaRelayer(detection, destination, {
+        token,
+        ...(opts.relayerContract !== undefined ? { relayerContract: opts.relayerContract } : {}),
+        ...(opts.relayerOptions !== undefined ? { relayerOptions: opts.relayerOptions } : {}),
+      });
+    }
+
+    if (isEth) {
+      const swept = await sweepETH(
+        this.transport,
+        detection.stealthPrivateKey,
+        destination,
+      );
+      return { swept, detection };
+    }
+    const swept = await sweepERC20(
+      this.transport,
+      detection.stealthPrivateKey,
+      token,
+      destination,
+    );
+    return { swept, detection };
+  }
+
+  /**
+   * 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).
+   */
+  async sweepViaRelayer(
+    detection: DetectedPayment,
+    destination: Address,
+    opts: {
+      token: Address;
+      relayerContract?: Address;
+      relayerOptions?: AgentRelayerSweepOptions;
+    },
+  ): Promise<AgentRelayerSweepResult> {
+    const { token } = opts;
+    const isEth =
+      token === ZERO_ADDRESS_ETH ||
+      token.toLowerCase() === ETH_SENTINEL.toLowerCase();
+    if (isEth) {
+      // Direct callers asking for ERC-20 relayer with the ETH sentinel need
+      // to use sweepEthViaRelayer instead.
+      throw new EthRelayerEndpointRequiredError();
+    }
+
+    const chainId = this.transport.chain.id;
+    const relayerContract =
+      opts.relayerContract ?? getRelayer(chainId);
+    if (relayerContract === undefined) {
+      throw new RelayerContractNotConfiguredError();
+    }
+
+    // Lazy dynamic import — keeps the agent-runtime ESM bundle small for
+    // consumers that never call sweepViaRelayer. The Gelato SDK + transitive
+    // deps (axios, ws, isomorphic-ws) only enter the bundle on demand.
+    const relayerMod = await import('@shroud-fi/relayer');
+
+    // Self-host path: skip Gelato. Sign the permit locally, POST the request
+    // to the operator-controlled relayer service, return a receipt shaped
+    // like the Gelato one.
+    const selfHostEndpoint = opts.relayerOptions?.selfHostEndpoint;
+    if (typeof selfHostEndpoint === 'string' && selfHostEndpoint.length > 0) {
+      const swept = await this.sweepViaSelfHost(
+        relayerMod.signEip2612Permit,
+        detection,
+        destination,
+        token,
+        relayerContract,
+        selfHostEndpoint,
+        opts.relayerOptions,
+      );
+      return { swept, detection };
+    }
+
+    const swept = await relayerMod.relayedSweepERC20(
+      this.transport,
+      detection.stealthPrivateKey,
+      token,
+      destination,
+      relayerContract,
+      opts.relayerOptions,
+    );
+
+    return { swept, detection };
+  }
+
+  /**
+   * 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 async sweepViaSelfHost(
+    signEip2612Permit: typeof import('@shroud-fi/relayer').signEip2612Permit,
+    detection: DetectedPayment,
+    destination: Address,
+    token: Address,
+    relayerContract: Address,
+    endpoint: string,
+    options: AgentRelayerSweepOptions | undefined,
+  ): Promise<AgentRelayerSweepResult['swept']> {
+    // 1. Read the stealth balance.
+    const stealthAddress = detection.stealthAddress;
+    const balance = (await this.transport.publicClient.readContract({
+      address: token,
+      abi: BALANCE_OF_ABI,
+      functionName: 'balanceOf',
+      args: [stealthAddress],
+    })) as bigint;
+
+    // 2. Compute the permit deadline.
+    const lifetime = options?.deadlineSecs ?? 1800n;
+    const latestBlock = await this.transport.publicClient.getBlock();
+    const deadline = latestBlock.timestamp + lifetime;
+
+    // 3. Sign the permit (the only place the stealth private key is consumed).
+    const permit = await signEip2612Permit(
+      this.transport,
+      detection.stealthPrivateKey,
+      token,
+      relayerContract,
+      balance,
+      deadline,
+    );
+
+    // 4. POST to the self-host service.
+    const body = {
+      token,
+      destination,
+      stealthAddress,
+      deadline: permit.deadline.toString(),
+      v: permit.v,
+      r: permit.r,
+      s: permit.s,
+    };
+
+    const fetchInit: RequestInit = {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    };
+    if (options?.signal !== undefined) {
+      fetchInit.signal = options.signal;
+    }
+    const response = await fetch(
+      `${endpoint.replace(/\/$/, '')}/relay`,
+      fetchInit,
+    );
+
+    const json = (await response.json()) as
+      | { ok: true; txHash: Hex; blockNumber: string }
+      | { ok: false; error: string };
+
+    if (!json.ok) {
+      throw new Error(json.error);
+    }
+
+    return {
+      taskId: `self-host:${json.txHash}`,
+      txHash: json.txHash,
+      status: 'success' as const,
+      relayerContract,
+      token,
+      destination,
+      blockNumber: BigInt(json.blockNumber),
+    };
+  }
+
+  /**
+   * 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.
+   */
+  async sweepEthViaRelayer(
+    detection: DetectedPayment,
+    destination: Address,
+    opts: {
+      ethRelayerContract?: Address;
+      relayerOptions: AgentRelayerEthSweepOptions;
+    },
+  ): Promise<AgentRelayerEthSweepResult> {
+    const chainId = this.transport.chain.id;
+    const ethRelayerContract =
+      opts.ethRelayerContract ?? getEthRelayer(chainId);
+    if (ethRelayerContract === undefined) {
+      throw new EthRelayerContractNotConfiguredError();
+    }
+
+    const endpoint = opts.relayerOptions.selfHostEndpoint;
+    if (typeof endpoint !== 'string' || endpoint.length === 0) {
+      throw new EthRelayerEndpointRequiredError();
+    }
+
+    // Lazy dynamic import keeps the agent-runtime ESM bundle small.
+    const relayerMod = await import('@shroud-fi/relayer');
+
+    const passOptions: {
+      deadlineSecs?: bigint;
+      pollTimeoutMs?: number;
+      signal?: AbortSignal;
+    } = {};
+    if (opts.relayerOptions.deadlineSecs !== undefined) {
+      passOptions.deadlineSecs = opts.relayerOptions.deadlineSecs;
+    }
+    if (opts.relayerOptions.pollTimeoutMs !== undefined) {
+      passOptions.pollTimeoutMs = opts.relayerOptions.pollTimeoutMs;
+    }
+    if (opts.relayerOptions.signal !== undefined) {
+      passOptions.signal = opts.relayerOptions.signal;
+    }
+
+    const swept = await relayerMod.relayedSweepETH(
+      this.transport,
+      detection.stealthPrivateKey,
+      destination,
+      ethRelayerContract,
+      endpoint,
+      passOptions,
+    );
+
+    return { swept, detection };
+  }
+}
+
+// Minimal balanceOf ABI for the self-host pre-flight balance read.
+const BALANCE_OF_ABI = [
+  {
+    type: 'function',
+    name: 'balanceOf',
+    stateMutability: 'view',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+] as const;
+
+/**
+ * ERC-6538 scheme identifier for secp256k1 stealth addresses with view-tag
+ * filtering (per EIP-5564). Kept as a `bigint` because the registry signature
+ * is `uint256 schemeId`. Mirrors `SCHEME_ID` in @shroud-fi/payments.
+ */
+const REGISTRY_SCHEME_ID = 1n;