@shroud-fi/relayer 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/relayer",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Gasless sweep client for ShroudFi. ERC-20 via Gelato 1Balance + EIP-2612 permit, native ETH via EIP-7702 delegated relayer.",
   "keywords": [
     "shroudfi",
@@ -27,11 +27,14 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
     "@gelatonetwork/relay-sdk-viem": "^1.4.0",
-    "@shroud-fi/transport": "0.1.3"
+    "@shroud-fi/transport": "0.1.4"
   },
   "peerDependencies": {
     "viem": "^2.21.0"
@@ -40,8 +43,8 @@
     "viem": "^2.21.0",
     "vitest": "^2.0.0",
     "typescript": "^5.6.0",
-    "@shroud-fi/self-host-relayer": "0.1.2",
-    "@shroud-fi/payments": "0.1.2"
+    "@shroud-fi/payments": "0.1.3",
+    "@shroud-fi/self-host-relayer": "0.1.3"
   },
   "publishConfig": {
     "access": "public"

package/src/constants.ts

@@ -0,0 +1,56 @@
+import type { Address } from 'viem';
+
+/**
+ * Default EIP-2612 permit deadline lifetime (in seconds).
+ *
+ * 30 minutes balances:
+ *   - long enough for Gelato task scheduling + L2 inclusion under congestion
+ *   - short enough to keep the signed permit window tight (smaller front-run /
+ *     replay attack window if a permit signature leaks)
+ */
+export const DEFAULT_PERMIT_DEADLINE_SECS: bigint = 1800n;
+
+/** Poll Gelato task status every 2s by default. */
+export const DEFAULT_POLL_INTERVAL_MS: number = 2000;
+
+/** Abort polling after 90s by default — well past Base L2 inclusion p99. */
+export const DEFAULT_POLL_TIMEOUT_MS: number = 90_000;
+
+/**
+ * Gelato Trusted Forwarder addresses ("Group A") for ShroudFi-supported chains.
+ *
+ * Both Base Sepolia (84532) and Base Mainnet (8453) share the same
+ * forwarder address per Gelato's Group A deployment.
+ *
+ * Defense-in-depth: at runtime the SDK reads `ShroudFiRelayer.trustedForwarder()`
+ * and asserts equality against this table before submitting any metaTx.
+ */
+export const GELATO_FORWARDER_BY_CHAIN: Readonly<Record<number, Address>> =
+  Object.freeze({
+    8453: '0xd8253782c45a12053594b9deB72d8e8aB2Fca54c' as Address,
+    84532: '0xd8253782c45a12053594b9deB72d8e8aB2Fca54c' as Address,
+  });
+
+/**
+ * Gelato public task-status endpoint. No auth required.
+ * Used as a fallback if the SDK's `getTaskStatus` is unavailable.
+ */
+export const GELATO_TASK_STATUS_URL: string =
+  'https://api.gelato.digital/tasks/status/';
+
+// ─── ETH sweep (P5.1) ─────────────────────────────────────────────────────
+
+/**
+ * Default EIP-712 EthSweep deadline lifetime (seconds). Matches the ERC-20
+ * permit deadline — 30 minutes balances inclusion headroom against a tight
+ * replay window if the signature leaks.
+ */
+export const DEFAULT_ETH_SWEEP_DEADLINE_SECS: bigint = 1800n;
+
+/**
+ * Chains where the ShroudFiEthRelayer is deployed AND EIP-7702 is active.
+ * Base Sepolia (84532) + Base mainnet (8453). Pectra activated on both.
+ */
+export const ETH_RELAYER_SUPPORTED_CHAINS: ReadonlySet<number> = new Set([
+  8453, 84532,
+]);

package/src/errors.ts

@@ -0,0 +1,82 @@
+/**
+ * Base class for all relayer-layer failures. Carries no key or amount
+ * material. Mirrors the shape of `@shroud-fi/payments` errors.
+ */
+export class RelayerError extends Error {
+  override readonly name: string = 'RelayerError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/** EIP-2612 permit could not be signed (typed-data path failed). */
+export class RelayerSignatureError extends RelayerError {
+  override readonly name: string = 'RelayerSignatureError';
+  constructor() {
+    super('Failed to sign EIP-2612 permit');
+  }
+}
+
+/** Gelato accepted/rejected the metaTx submission — no taskId obtained. */
+export class RelayerSubmissionError extends RelayerError {
+  override readonly name: string = 'RelayerSubmissionError';
+  constructor(tag?: string) {
+    super(
+      tag === undefined
+        ? 'Failed to submit sponsored call to relayer network'
+        : `Failed to submit sponsored call to relayer network (${tag})`,
+    );
+  }
+}
+
+/**
+ * Gelato accepted the task but on-chain execution reverted (or was blacklisted).
+ * Carries the lifecycle state but no signature / amount / address bytes.
+ */
+export class RelayerExecutionFailedError extends RelayerError {
+  override readonly name: string = 'RelayerExecutionFailedError';
+  constructor(state: string) {
+    super(`Relayed sweep execution did not succeed (state=${state})`);
+  }
+}
+
+/** Polling exceeded the configured timeout. */
+export class RelayerTimeoutError extends RelayerError {
+  override readonly name: string = 'RelayerTimeoutError';
+  constructor() {
+    super('Timed out waiting for relayer task to reach a terminal state');
+  }
+}
+
+/**
+ * On-chain `ShroudFiRelayer.trustedForwarder()` did not match the Gelato
+ * forwarder we expected for this chain. Defense-in-depth against deploying
+ * against the wrong forwarder.
+ */
+export class RelayerForwarderMismatchError extends RelayerError {
+  override readonly name: string = 'RelayerForwarderMismatchError';
+  constructor() {
+    super('Relayer contract trustedForwarder does not match expected Gelato forwarder');
+  }
+}
+
+/**
+ * Stealth address held zero balance of the target token at the time the
+ * relayer was asked to sweep it. Distinct from a wallet "insufficient funds"
+ * condition — this means the inbound stealth has already been swept (or never
+ * funded), so there's nothing left to relay.
+ */
+export class StealthAddressEmptyError extends RelayerError {
+  override readonly name: string = 'StealthAddressEmptyError';
+  constructor() {
+    super('Stealth address has zero balance of the target token');
+  }
+}
+
+/** Transport chain is not in the supported Gelato forwarder table. */
+export class RelayerInvalidChainError extends RelayerError {
+  override readonly name: string = 'RelayerInvalidChainError';
+  constructor() {
+    super('Transport chain is not supported by the Gelato relayer');
+  }
+}

package/src/eth-sweep.ts

@@ -0,0 +1,233 @@
+/**
+ * relayedSweepETH — gasless ETH sweep via EIP-7702 + self-host relayer service.
+ *
+ * Flow:
+ *   1. Validate chain is in the supported ETH-relayer table.
+ *   2. Read stealth EOA balance; refuse if zero.
+ *   3. Read stealth EOA nonce (required for the EIP-7702 auth tuple).
+ *   4. Sign an EIP-7702 SET_CODE authorization delegating the stealth EOA to
+ *      `ethRelayerContract`.
+ *   5. Sign an EIP-712 `EthSweep(destination, deadline)` message — the
+ *      contract verifies this binds the specific destination + deadline so a
+ *      compromised relayer cannot redirect funds.
+ *   6. POST both signatures to the self-host relayer's /relay-eth endpoint.
+ *   7. Wait for the on-chain receipt and return.
+ *
+ * Privacy invariants:
+ *   - `stealthPrivateKey` never logged, never serialized to any persistent
+ *     surface. Held in a closure during this call only.
+ *   - No amount fields in the returned receipt. Callers wanting amount can
+ *     compare pre/post balances themselves.
+ *   - Error messages contain no addresses, signature bytes, or chain ids.
+ *   - The fetch request body is constructed once and discarded. No fetch
+ *     library that caches request bodies is used (native `fetch` only).
+ *
+ * Why self-host instead of Gelato:
+ *   Gelato's 7702 path is bundled into their Smart Wallets product (passkeys,
+ *   wallet abstraction). It doesn't expose a "submit my pre-signed 7702 auth"
+ *   endpoint that fits our threat model. Our self-host relayer at
+ *   api.shroudfi.live already controls its own EOA and can build arbitrary
+ *   tx types — fewer vendor dependencies, full control of the broadcast path.
+ */
+
+import { type Address, type Hex } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import {
+  DEFAULT_ETH_SWEEP_DEADLINE_SECS,
+  DEFAULT_POLL_TIMEOUT_MS,
+  ETH_RELAYER_SUPPORTED_CHAINS,
+} from './constants.js';
+import type {
+  RelayedEthSweepOptions,
+  RelayedEthSweepReceipt,
+} from './types.js';
+import {
+  RelayerExecutionFailedError,
+  StealthAddressEmptyError,
+  RelayerInvalidChainError,
+  RelayerSignatureError,
+  RelayerSubmissionError,
+  RelayerTimeoutError,
+} from './errors.js';
+
+/**
+ * EIP-712 typed-data spec for the EthSweep struct. Matches
+ * `bytes32 SWEEP_TYPEHASH = keccak256("EthSweep(address destination,uint256 deadline)")`
+ * in ShroudFiEthRelayer.sol.
+ */
+const ETH_SWEEP_TYPES = {
+  EthSweep: [
+    { name: 'destination', type: 'address' },
+    { name: 'deadline', type: 'uint256' },
+  ],
+} as const;
+
+const ETH_SWEEP_DOMAIN_NAME = 'ShroudFiEthRelayer';
+const ETH_SWEEP_DOMAIN_VERSION = '1';
+
+interface RelayServiceResponse {
+  readonly ok?: boolean;
+  readonly txHash?: string;
+  readonly blockNumber?: string;
+  readonly error?: string;
+}
+
+function isHex(s: unknown): s is Hex {
+  return typeof s === 'string' && /^0x[0-9a-fA-F]+$/.test(s);
+}
+
+export async function relayedSweepETH(
+  transport: ShroudFiTransport,
+  stealthPrivateKey: Hex,
+  destination: Address,
+  ethRelayerContract: Address,
+  relayerServiceUrl: string,
+  options?: RelayedEthSweepOptions,
+): Promise<RelayedEthSweepReceipt> {
+  const chainId = transport.chain.id;
+
+  // 1. Chain support gate.
+  if (!ETH_RELAYER_SUPPORTED_CHAINS.has(chainId)) {
+    throw new RelayerInvalidChainError();
+  }
+
+  const account = privateKeyToAccount(stealthPrivateKey);
+  const stealthAddress = account.address;
+
+  // 2. Balance pre-flight.
+  const balance = await transport.publicClient.getBalance({
+    address: stealthAddress,
+  });
+  if (balance === 0n) {
+    throw new StealthAddressEmptyError();
+  }
+
+  // 3. Read stealth EOA's nonce. EIP-7702 auth tuples include the EOA's
+  // nonce; mismatches at submission time cause invalid_auth_signature reverts.
+  const nonce = await transport.publicClient.getTransactionCount({
+    address: stealthAddress,
+  });
+
+  // 4. Compute deadline against on-chain block timestamp.
+  const lifetime = options?.deadlineSecs ?? DEFAULT_ETH_SWEEP_DEADLINE_SECS;
+  const block = await transport.publicClient.getBlock();
+  const deadline = block.timestamp + lifetime;
+
+  // 5a. Sign EIP-7702 SET_CODE authorization.
+  let authorization;
+  try {
+    authorization = await account.signAuthorization({
+      contractAddress: ethRelayerContract,
+      chainId,
+      nonce,
+    });
+  } catch {
+    throw new RelayerSignatureError();
+  }
+
+  // 5b. Sign EIP-712 EthSweep. verifyingContract = stealthAddress because the
+  // contract runs as delegated code at the stealth EOA's address. OZ EIP712
+  // rebuilds the domain at runtime when address(this) != _cachedThis.
+  let signature: Hex;
+  try {
+    signature = await account.signTypedData({
+      domain: {
+        name: ETH_SWEEP_DOMAIN_NAME,
+        version: ETH_SWEEP_DOMAIN_VERSION,
+        chainId,
+        verifyingContract: stealthAddress,
+      },
+      types: ETH_SWEEP_TYPES,
+      primaryType: 'EthSweep',
+      message: { destination, deadline },
+    });
+  } catch {
+    throw new RelayerSignatureError();
+  }
+
+  // 6. POST to self-host relayer. The relayer reconstructs the 7702
+  // SignedAuthorization, builds a type-0x04 transaction, and broadcasts.
+  const url = `${relayerServiceUrl.replace(/\/$/, '')}/relay-eth`;
+  const body = {
+    stealthAddress,
+    destination,
+    chainId,
+    deadline: deadline.toString(),
+    signature,
+    authorization: {
+      address: authorization.address,
+      chainId: authorization.chainId,
+      nonce: authorization.nonce,
+      r: authorization.r,
+      s: authorization.s,
+      yParity: authorization.yParity,
+    },
+  };
+
+  let response: Response;
+  try {
+    const init: RequestInit = {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    };
+    if (options?.signal !== undefined) {
+      init.signal = options.signal;
+    }
+    response = await fetch(url, init);
+  } catch {
+    throw new RelayerSubmissionError();
+  }
+
+  if (!response.ok) {
+    let tag: string | undefined;
+    try {
+      const parsed = (await response.json()) as RelayServiceResponse;
+      if (typeof parsed.error === 'string') tag = parsed.error;
+    } catch {
+      // body wasn't JSON — fall through with no tag.
+    }
+    throw new RelayerSubmissionError(tag);
+  }
+
+  let parsed: RelayServiceResponse;
+  try {
+    parsed = (await response.json()) as RelayServiceResponse;
+  } catch {
+    throw new RelayerSubmissionError();
+  }
+
+  if (parsed.ok !== true || !isHex(parsed.txHash)) {
+    const tag = typeof parsed.error === 'string' ? parsed.error : 'unknown';
+    throw new RelayerExecutionFailedError(tag);
+  }
+  const txHash = parsed.txHash;
+
+  // 7. Wait for on-chain confirmation. Relayer responded with a tx hash; the
+  // tx is broadcasting but not necessarily mined. Use viem's standard
+  // wait-for-receipt with the configured timeout.
+  const timeoutMs = options?.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS;
+  let receipt;
+  try {
+    receipt = await transport.publicClient.waitForTransactionReceipt({
+      hash: txHash,
+      timeout: timeoutMs,
+    });
+  } catch {
+    throw new RelayerTimeoutError();
+  }
+
+  if (receipt.status !== 'success') {
+    throw new RelayerExecutionFailedError('reverted');
+  }
+
+  return {
+    txHash,
+    status: 'success',
+    blockNumber: receipt.blockNumber,
+    ethRelayerContract,
+    destination,
+    stealthAddress,
+  };
+}

package/src/gelato-adapter.ts

@@ -0,0 +1,295 @@
+import type { Address, Hex, Chain } from 'viem';
+import { createWalletClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { GelatoRelay, TaskState } from '@gelatonetwork/relay-sdk-viem';
+import {
+  GELATO_TASK_STATUS_URL,
+} from './constants.js';
+import type { GelatoTaskId, RelayerSweepStatus } from './types.js';
+import {
+  RelayerExecutionFailedError,
+  RelayerSubmissionError,
+  RelayerTimeoutError,
+} from './errors.js';
+
+/**
+ * Parameters for submitting a sponsored (1Balance) ERC-2771 metaTx.
+ *
+ * `data` must already be ABI-encoded for the target function on `target`.
+ * The Gelato relay layer appends the `user` address to the calldata so the
+ * `_msgSender()` inside the target contract returns the stealth address.
+ *
+ * Privacy: `userPrivateKey` is consumed once to construct an ephemeral
+ * `walletClient`, which is then handed to the Gelato SDK. It is never logged,
+ * stored on `this`, or attached to thrown errors.
+ */
+export interface SubmitMetaTxParams {
+  readonly chainId: number;
+  readonly target: Address;
+  readonly data: Hex;
+  readonly user: Address;
+  readonly userPrivateKey: Hex;
+  /**
+   * Optional Gelato 1Balance sponsor API key.
+   * The SDK requires a string; if absent we forward an empty string and let
+   * Gelato reject with a structured error.
+   */
+  readonly apiKey?: string;
+  readonly signal?: AbortSignal;
+  /**
+   * viem `Chain` to attach to the ephemeral walletClient. Required so viem
+   * has a chainId/rpc context for typed-data signing.
+   */
+  readonly chain: Chain;
+  /** RPC URL forwarded to the ephemeral walletClient. */
+  readonly rpcUrl?: string;
+}
+
+/**
+ * Normalized Gelato task status surfaced to the SDK caller. Strips PII /
+ * un-needed metadata (creation date, gas used, etc.) from the upstream type.
+ */
+export interface GelatoTaskStatus {
+  readonly taskId: GelatoTaskId;
+  readonly state: RelayerSweepStatus;
+  readonly txHash?: Hex;
+  readonly blockNumber?: bigint;
+  readonly lastErrorMsg?: string;
+}
+
+// Lazily instantiate a single relay client per process. Stateless wrt
+// chain/key so safe to share.
+let _relay: GelatoRelay | undefined;
+function relay(): GelatoRelay {
+  if (_relay === undefined) {
+    _relay = new GelatoRelay();
+  }
+  return _relay;
+}
+
+/**
+ * Submit a sponsored ERC-2771 metaTx via Gelato 1Balance.
+ *
+ * Returns the Gelato `taskId`. Caller is responsible for polling.
+ */
+export async function submitSponsoredCallErc2771(
+  p: SubmitMetaTxParams,
+): Promise<GelatoTaskId> {
+  const account = privateKeyToAccount(p.userPrivateKey);
+
+  // Build an ephemeral walletClient. The Gelato SDK uses it to sign the
+  // ERC-2771 typed data. We deliberately avoid persisting it.
+  const wallet = createWalletClient({
+    account,
+    chain: p.chain,
+    transport: p.rpcUrl !== undefined ? http(p.rpcUrl) : http(),
+  });
+
+  const request = {
+    chainId: BigInt(p.chainId),
+    target: p.target,
+    data: p.data,
+    user: p.user,
+    isConcurrent: false as const,
+  };
+
+  try {
+    const response = await relay().sponsoredCallERC2771(
+      request,
+      wallet,
+      p.apiKey ?? '',
+    );
+    return response.taskId;
+  } catch (err) {
+    // Surface only the upstream error class name; never the message
+    // (may contain calldata bytes, addresses, or RPC quoting).
+    const tag = err instanceof Error ? err.name : 'unknown';
+    throw new RelayerSubmissionError(tag);
+  }
+}
+
+function mapTaskState(state: TaskState | string): RelayerSweepStatus {
+  switch (state) {
+    case TaskState.ExecSuccess:
+    case 'ExecSuccess':
+      return 'success';
+    case TaskState.ExecReverted:
+    case 'ExecReverted':
+      return 'failed';
+    case TaskState.Cancelled:
+    case 'Cancelled':
+      return 'cancelled';
+    case TaskState.CheckPending:
+    case TaskState.ExecPending:
+    case TaskState.WaitingForConfirmation:
+    case 'CheckPending':
+    case 'ExecPending':
+    case 'WaitingForConfirmation':
+      return 'pending';
+    default:
+      // Treat unknown lifecycle states (e.g. "Blacklisted") as failure.
+      return 'failed';
+  }
+}
+
+/**
+ * Fetch a single task-status snapshot via the public Gelato HTTP endpoint.
+ * Used as fallback if the SDK's getTaskStatus returns undefined.
+ */
+async function fetchTaskStatusFallback(
+  taskId: GelatoTaskId,
+  signal?: AbortSignal,
+): Promise<GelatoTaskStatus | undefined> {
+  // `fetch` is globally available in Node 18+.
+  let resp: Response;
+  try {
+    const init: RequestInit = signal !== undefined ? { signal } : {};
+    resp = await fetch(`${GELATO_TASK_STATUS_URL}${taskId}`, init);
+  } catch {
+    return undefined;
+  }
+  if (!resp.ok) return undefined;
+
+  let body: unknown;
+  try {
+    body = await resp.json();
+  } catch {
+    return undefined;
+  }
+
+  // Endpoint returns either { task: {...} } or the bare task object.
+  const taskUnknown =
+    body !== null && typeof body === 'object' && 'task' in body
+      ? (body as { task: unknown }).task
+      : body;
+
+  if (taskUnknown === null || typeof taskUnknown !== 'object')
+    return undefined;
+  const task = taskUnknown as Record<string, unknown>;
+
+  const rawState = task['taskState'];
+  if (typeof rawState !== 'string') return undefined;
+
+  const state = mapTaskState(rawState);
+
+  const result: { -readonly [K in keyof GelatoTaskStatus]: GelatoTaskStatus[K] } = {
+    taskId,
+    state,
+  };
+
+  const txHash = task['transactionHash'];
+  if (typeof txHash === 'string' && txHash.startsWith('0x')) {
+    result.txHash = txHash as Hex;
+  }
+
+  const blockNumber = task['blockNumber'];
+  if (typeof blockNumber === 'number') {
+    result.blockNumber = BigInt(blockNumber);
+  } else if (typeof blockNumber === 'string' && /^\d+$/.test(blockNumber)) {
+    result.blockNumber = BigInt(blockNumber);
+  }
+
+  const lastErr = task['lastCheckMessage'];
+  if (typeof lastErr === 'string' && lastErr.length > 0) {
+    result.lastErrorMsg = lastErr;
+  }
+
+  return result;
+}
+
+/**
+ * Poll Gelato task status until terminal (success / failed / cancelled) or
+ * until the timeout expires / the abort signal fires.
+ *
+ * Strategy:
+ *   1. Try the SDK's `getTaskStatus` first (it shares websocket cache).
+ *   2. Fall back to direct HTTP if the SDK returns undefined.
+ *
+ * Errors:
+ *   - RelayerTimeoutError on timeout / abort
+ *   - RelayerExecutionFailedError on `failed`/`cancelled` terminal state
+ */
+export async function pollGelatoTaskUntilTerminal(
+  taskId: GelatoTaskId,
+  opts: {
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    signal?: AbortSignal;
+  },
+): Promise<GelatoTaskStatus> {
+  const deadline = Date.now() + opts.pollTimeoutMs;
+  const r = relay();
+
+  while (Date.now() < deadline) {
+    if (opts.signal?.aborted === true) {
+      throw new RelayerTimeoutError();
+    }
+
+    let status: GelatoTaskStatus | undefined;
+    try {
+      const upstream = await r.getTaskStatus(taskId);
+      if (upstream !== undefined) {
+        const built: { -readonly [K in keyof GelatoTaskStatus]: GelatoTaskStatus[K] } = {
+          taskId,
+          state: mapTaskState(upstream.taskState),
+        };
+        if (
+          typeof upstream.transactionHash === 'string' &&
+          upstream.transactionHash.startsWith('0x')
+        ) {
+          built.txHash = upstream.transactionHash as Hex;
+        }
+        if (typeof upstream.blockNumber === 'number') {
+          built.blockNumber = BigInt(upstream.blockNumber);
+        }
+        if (
+          typeof upstream.lastCheckMessage === 'string' &&
+          upstream.lastCheckMessage.length > 0
+        ) {
+          built.lastErrorMsg = upstream.lastCheckMessage;
+        }
+        status = built;
+      }
+    } catch {
+      // swallow; we'll try the HTTP fallback or retry next tick
+    }
+
+    if (status === undefined) {
+      status = await fetchTaskStatusFallback(taskId, opts.signal);
+    }
+
+    if (status !== undefined) {
+      if (status.state === 'success') return status;
+      if (status.state === 'failed' || status.state === 'cancelled') {
+        throw new RelayerExecutionFailedError(status.state);
+      }
+      // pending / submitted: keep polling
+    }
+
+    await sleep(opts.pollIntervalMs, opts.signal);
+  }
+
+  throw new RelayerTimeoutError();
+}
+
+async function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted === true) {
+      reject(new RelayerTimeoutError());
+      return;
+    }
+    const t = setTimeout(() => {
+      if (signal !== undefined) {
+        signal.removeEventListener('abort', onAbort);
+      }
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(t);
+      reject(new RelayerTimeoutError());
+    };
+    if (signal !== undefined) {
+      signal.addEventListener('abort', onAbort, { once: true });
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+export { relayedSweepERC20 } from './relayer.js';
+export { relayedSweepETH } from './eth-sweep.js';
+export { signEip2612Permit } from './signing.js';
+
+export type {
+  RelayerSweepOptions,
+  RelayerSweepReceipt,
+  RelayerSweepStatus,
+  GelatoTaskId,
+  Eip2612PermitSignature,
+  RelayedEthSweepOptions,
+  RelayedEthSweepReceipt,
+} from './types.js';
+
+export {
+  RelayerError,
+  RelayerSignatureError,
+  RelayerSubmissionError,
+  RelayerExecutionFailedError,
+  RelayerTimeoutError,
+  RelayerForwarderMismatchError,
+  StealthAddressEmptyError,
+  RelayerInvalidChainError,
+} from './errors.js';
+
+export {
+  DEFAULT_PERMIT_DEADLINE_SECS,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_POLL_TIMEOUT_MS,
+  GELATO_FORWARDER_BY_CHAIN,
+  DEFAULT_ETH_SWEEP_DEADLINE_SECS,
+  ETH_RELAYER_SUPPORTED_CHAINS,
+} from './constants.js';

package/src/relayer.ts

@@ -0,0 +1,211 @@
+import type { Address, Hex } from 'viem';
+import { encodeFunctionData, getAddress } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import {
+  DEFAULT_PERMIT_DEADLINE_SECS,
+  DEFAULT_POLL_INTERVAL_MS,
+  DEFAULT_POLL_TIMEOUT_MS,
+  GELATO_FORWARDER_BY_CHAIN,
+} from './constants.js';
+import type {
+  RelayerSweepOptions,
+  RelayerSweepReceipt,
+} from './types.js';
+import {
+  RelayerForwarderMismatchError,
+  StealthAddressEmptyError,
+  RelayerInvalidChainError,
+} from './errors.js';
+import { signEip2612Permit } from './signing.js';
+import {
+  submitSponsoredCallErc2771,
+  pollGelatoTaskUntilTerminal,
+} from './gelato-adapter.js';
+
+/**
+ * Minimal inline ABI for `ShroudFiRelayer` — only the surface we call from
+ * the SDK. Kept here (not in a shared `abi.ts`) because no other module needs
+ * these entries today.
+ */
+const SHROUDFI_RELAYER_ABI = [
+  {
+    type: 'function',
+    name: 'sweepERC20WithPermit',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'token', type: 'address' },
+      { name: 'destination', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+      { name: 'v', type: 'uint8' },
+      { name: 'r', type: 'bytes32' },
+      { name: 's', type: 'bytes32' },
+    ],
+    outputs: [],
+  },
+  {
+    type: 'function',
+    name: 'trustedForwarder',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'address' }],
+  },
+] as const;
+
+/**
+ * Minimal balanceOf ABI for the pre-flight balance read. Inlined so this file
+ * has no dependency on `@shroud-fi/transport`'s ERC20Abi shape.
+ */
+const ERC20_BALANCE_OF_ABI = [
+  {
+    type: 'function',
+    name: 'balanceOf',
+    stateMutability: 'view',
+    inputs: [{ name: 'account', type: 'address' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+] as const;
+
+/**
+ * Gasless ERC-20 sweep via the deployed `ShroudFiRelayer` + Gelato.
+ *
+ * Flow:
+ *   1. Validate chain is in the supported Gelato forwarder table.
+ *   2. Read the relayer's on-chain trustedForwarder and assert match.
+ *   3. Read the stealth address ERC-20 balance (= permit `value`).
+ *   4. Sign an EIP-2612 permit { owner=stealth, spender=relayer, value, deadline }.
+ *   5. Encode `sweepERC20WithPermit(token, destination, deadline, v, r, s)`.
+ *   6. Submit via `sponsoredCallERC2771` (1Balance sponsored).
+ *   7. Poll until terminal — return receipt with txHash + blockNumber.
+ *
+ * Privacy invariants enforced here:
+ *   - `stealthPrivateKey` is never logged, serialized, or attached to errors.
+ *   - The receipt contains NO amount fields (balance is read but discarded
+ *     after permit signing).
+ *   - Error messages contain no addresses, amounts, signature bytes, or chain ids.
+ */
+export async function relayedSweepERC20(
+  transport: ShroudFiTransport,
+  stealthPrivateKey: Hex,
+  token: Address,
+  destination: Address,
+  relayerContract: Address,
+  options?: RelayerSweepOptions,
+): Promise<RelayerSweepReceipt> {
+  const chainId = transport.chain.id;
+
+  // 1. Chain support check.
+  const expectedForwarder = GELATO_FORWARDER_BY_CHAIN[chainId];
+  if (expectedForwarder === undefined) {
+    throw new RelayerInvalidChainError();
+  }
+
+  // 2. Forwarder match check (defense-in-depth).
+  const onChainForwarder = (await transport.publicClient.readContract({
+    address: relayerContract,
+    abi: SHROUDFI_RELAYER_ABI,
+    functionName: 'trustedForwarder',
+  })) as Address;
+  if (
+    getAddress(onChainForwarder) !== getAddress(expectedForwarder)
+  ) {
+    throw new RelayerForwarderMismatchError();
+  }
+
+  // 3. Balance read. Note: `account` is derived inside a tight scope; we
+  // never persist or log the privateKey-derived account beyond this.
+  const stealthAddress = privateKeyToAccount(stealthPrivateKey).address;
+
+  const balance = (await transport.publicClient.readContract({
+    address: token,
+    abi: ERC20_BALANCE_OF_ABI,
+    functionName: 'balanceOf',
+    args: [stealthAddress],
+  })) as bigint;
+
+  if (balance === 0n) {
+    throw new StealthAddressEmptyError();
+  }
+
+  // 4. Compute permit deadline. Use block.timestamp + lifetime so the
+  // deadline aligns with the chain's clock rather than the host's.
+  const lifetime = options?.deadlineSecs ?? DEFAULT_PERMIT_DEADLINE_SECS;
+  const latestBlock = await transport.publicClient.getBlock();
+  const deadline = latestBlock.timestamp + lifetime;
+
+  // 5. Sign the EIP-2612 permit.
+  const permit = await signEip2612Permit(
+    transport,
+    stealthPrivateKey,
+    token,
+    relayerContract,
+    balance,
+    deadline,
+  );
+
+  // 6. Encode sweepERC20WithPermit calldata.
+  const calldata = encodeFunctionData({
+    abi: SHROUDFI_RELAYER_ABI,
+    functionName: 'sweepERC20WithPermit',
+    args: [token, destination, permit.deadline, permit.v, permit.r, permit.s],
+  });
+
+  // 7. Submit via Gelato 1Balance sponsored call.
+  const submitParams: {
+    chainId: number;
+    target: Address;
+    data: Hex;
+    user: Address;
+    userPrivateKey: Hex;
+    chain: ShroudFiTransport['chain'];
+    apiKey?: string;
+    rpcUrl?: string;
+    signal?: AbortSignal;
+  } = {
+    chainId,
+    target: relayerContract,
+    data: calldata,
+    user: stealthAddress,
+    userPrivateKey: stealthPrivateKey,
+    chain: transport.chain,
+  };
+  if (options?.gelatoApiKey !== undefined) {
+    submitParams.apiKey = options.gelatoApiKey;
+  }
+  if (options?.signal !== undefined) {
+    submitParams.signal = options.signal;
+  }
+
+  const taskId = await submitSponsoredCallErc2771(submitParams);
+
+  // 8. Poll until terminal.
+  const pollOpts: {
+    pollIntervalMs: number;
+    pollTimeoutMs: number;
+    signal?: AbortSignal;
+  } = {
+    pollIntervalMs: options?.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS,
+    pollTimeoutMs: options?.pollTimeoutMs ?? DEFAULT_POLL_TIMEOUT_MS,
+  };
+  if (options?.signal !== undefined) {
+    pollOpts.signal = options.signal;
+  }
+
+  const status = await pollGelatoTaskUntilTerminal(taskId, pollOpts);
+
+  // Build the receipt. NOTE: no amount fields by design.
+  const receipt: {
+    -readonly [K in keyof RelayerSweepReceipt]: RelayerSweepReceipt[K];
+  } = {
+    taskId,
+    txHash: status.txHash ?? ('0x' as Hex),
+    status: status.state,
+    relayerContract,
+    token,
+    destination,
+  };
+  if (status.blockNumber !== undefined) {
+    receipt.blockNumber = status.blockNumber;
+  }
+  return receipt;
+}

package/src/signing.ts

@@ -0,0 +1,165 @@
+import type { Address, Hex } from 'viem';
+import { parseSignature } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import type { ShroudFiTransport } from '@shroud-fi/transport';
+import type { Eip2612PermitSignature } from './types.js';
+import { RelayerSignatureError } from './errors.js';
+
+/**
+ * Minimal ABI for the read paths we use. Inlined rather than imported from
+ * `@shroud-fi/transport`'s ERC20Abi so this file has zero coupling to
+ * non-permit fields. Direct two-call reads (no multicall3 dependency) so the
+ * SDK runs against forks/local Anvils where multicall may not be configured.
+ */
+const PERMIT_READ_ABI = [
+  {
+    type: 'function',
+    name: 'name',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'string' }],
+  },
+  {
+    type: 'function',
+    name: 'version',
+    stateMutability: 'view',
+    inputs: [],
+    outputs: [{ name: '', type: 'string' }],
+  },
+  {
+    type: 'function',
+    name: 'nonces',
+    stateMutability: 'view',
+    inputs: [{ name: 'owner', type: 'address' }],
+    outputs: [{ name: '', type: 'uint256' }],
+  },
+] as const;
+
+const PERMIT_TYPES = {
+  Permit: [
+    { name: 'owner', type: 'address' },
+    { name: 'spender', type: 'address' },
+    { name: 'value', type: 'uint256' },
+    { name: 'nonce', type: 'uint256' },
+    { name: 'deadline', type: 'uint256' },
+  ],
+} as const;
+
+/**
+ * Sign an EIP-2612 permit for {token, spender, value, deadline} from the
+ * stealth address keyed by `stealthPrivateKey`.
+ *
+ * Privacy:
+ *   - The privateKey is consumed once to derive a viem `account` and is not
+ *     stored, logged, serialized, or attached to thrown errors.
+ *   - On failure we throw a structured `RelayerSignatureError` with no key
+ *     material, no signature bytes, no nonce.
+ *   - Token `version()` is probed with a try/catch fallback to "1" — the
+ *     dominant default across permit-compatible ERC-20s.
+ *
+ * @param transport - ShroudFi transport (publicClient for reads)
+ * @param stealthPrivateKey - 0x-prefixed 32-byte private key (treated as secret)
+ * @param token - ERC-20 contract
+ * @param spender - relayer contract address (= `ShroudFiRelayer`)
+ * @param value - permit value (= full balance at time of sign)
+ * @param deadline - unix-seconds deadline (caller computes from `block.timestamp + lifetime`)
+ */
+export async function signEip2612Permit(
+  transport: ShroudFiTransport,
+  stealthPrivateKey: Hex,
+  token: Address,
+  spender: Address,
+  value: bigint,
+  deadline: bigint,
+): Promise<Eip2612PermitSignature> {
+  const account = privateKeyToAccount(stealthPrivateKey);
+  const owner = account.address;
+  const chainId = transport.chain.id;
+
+  // Read token name (required for the domain separator). If a token doesn't
+  // expose `name()` it isn't ERC-2612 compatible — propagate as signature error.
+  let tokenName: string;
+  try {
+    tokenName = (await transport.publicClient.readContract({
+      address: token,
+      abi: PERMIT_READ_ABI,
+      functionName: 'name',
+    })) as string;
+  } catch {
+    throw new RelayerSignatureError();
+  }
+
+  // Token version: most permit ERC-20s use "1". Probe with a try/catch.
+  let tokenVersion = '1';
+  try {
+    const v = (await transport.publicClient.readContract({
+      address: token,
+      abi: PERMIT_READ_ABI,
+      functionName: 'version',
+    })) as string;
+    if (typeof v === 'string' && v.length > 0) {
+      tokenVersion = v;
+    }
+  } catch {
+    // intentional: fall back to "1"
+  }
+
+  // Read the current permit nonce for `owner`.
+  let nonce: bigint;
+  try {
+    nonce = (await transport.publicClient.readContract({
+      address: token,
+      abi: PERMIT_READ_ABI,
+      functionName: 'nonces',
+      args: [owner],
+    })) as bigint;
+  } catch {
+    throw new RelayerSignatureError();
+  }
+
+  const domain = {
+    name: tokenName,
+    version: tokenVersion,
+    chainId,
+    verifyingContract: token,
+  } as const;
+
+  let signatureHex: Hex;
+  try {
+    signatureHex = await account.signTypedData({
+      domain,
+      types: PERMIT_TYPES,
+      primaryType: 'Permit',
+      message: {
+        owner,
+        spender,
+        value,
+        nonce,
+        deadline,
+      },
+    });
+  } catch {
+    throw new RelayerSignatureError();
+  }
+
+  // viem returns the 65-byte signature; split into v/r/s.
+  // `parseSignature` returns either {r,s,v,yParity} or {r,s,yParity} (v?: never).
+  // Standard EIP-2612 needs `v ∈ {27, 28}`: derive from yParity if v is absent.
+  let v: number;
+  let r: Hex;
+  let s: Hex;
+  try {
+    const split = parseSignature(signatureHex);
+    r = split.r;
+    s = split.s;
+    if (split.v !== undefined) {
+      v = Number(split.v);
+    } else {
+      v = split.yParity === 0 ? 27 : 28;
+    }
+  } catch {
+    throw new RelayerSignatureError();
+  }
+
+  return { v, r, s, deadline };
+}

package/src/types.ts

@@ -0,0 +1,101 @@
+import type { Address, Hex } from 'viem';
+
+/**
+ * Gelato task identifier returned by `sponsoredCallERC2771`.
+ * Opaque string the SDK uses to poll status.
+ */
+export type GelatoTaskId = string;
+
+/**
+ * Terminal + in-flight states the SDK surfaces to the caller.
+ * Mapped from Gelato's `TaskState` plus our own `'submitted'` initial state.
+ */
+export type RelayerSweepStatus =
+  | 'submitted'
+  | 'pending'
+  | 'success'
+  | 'failed'
+  | 'cancelled';
+
+/**
+ * EIP-2612 permit signature components plus deadline.
+ * `v / r / s` are passed verbatim to `sweepERC20WithPermit`.
+ *
+ * Privacy: never log or serialize this struct — the signature is a
+ * spending-authorization credential equivalent to a one-time approval.
+ */
+export interface Eip2612PermitSignature {
+  readonly v: number;
+  readonly r: Hex;
+  readonly s: Hex;
+  readonly deadline: bigint;
+}
+
+/**
+ * Optional runtime overrides for {@link relayedSweepERC20}.
+ *
+ * All fields are optional; omitted fields use defaults from `constants.ts`.
+ *
+ * Privacy: `gelatoApiKey` is forwarded only to the Gelato adapter and never
+ * logged. The caller is responsible for sourcing it securely.
+ */
+export interface RelayerSweepOptions {
+  /** Override the EIP-2612 permit deadline lifetime in seconds. */
+  readonly deadlineSecs?: bigint;
+  /** Override poll interval (ms) for Gelato task status. */
+  readonly pollIntervalMs?: number;
+  /** Override hard timeout (ms) for the polling loop. */
+  readonly pollTimeoutMs?: number;
+  /**
+   * Optional Gelato 1Balance sponsor API key. The Gelato SDK requires a
+   * non-empty string for sponsored calls; pass it here for production.
+   */
+  readonly gelatoApiKey?: string;
+  /** Cancellation token. Aborts polling early. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Receipt for a completed relayed sweep.
+ *
+ * Privacy invariant: NO `amount` / `feeAmount` / `netAmount` fields.
+ * The caller can read pre-/post-sweep balances independently if it needs
+ * those values; the SDK never returns plaintext amounts.
+ */
+export interface RelayerSweepReceipt {
+  readonly taskId: GelatoTaskId;
+  readonly txHash: Hex;
+  readonly status: RelayerSweepStatus;
+  readonly relayerContract: Address;
+  readonly token: Address;
+  readonly destination: Address;
+  readonly blockNumber?: bigint;
+}
+
+// ─── ETH sweep (P5.1, EIP-7702 via self-host relayer) ─────────────────────
+
+/**
+ * Optional runtime overrides for {@link relayedSweepETH}.
+ */
+export interface RelayedEthSweepOptions {
+  /** Override the EIP-712 EthSweep deadline lifetime in seconds. */
+  readonly deadlineSecs?: bigint;
+  /** Override hard timeout (ms) for waitForTransactionReceipt. */
+  readonly pollTimeoutMs?: number;
+  /** Cancellation token. Forwarded to fetch + receipt polling. */
+  readonly signal?: AbortSignal;
+}
+
+/**
+ * Receipt for a completed ETH gasless sweep.
+ *
+ * Same privacy invariant as {@link RelayerSweepReceipt}: NO amount fields.
+ */
+export interface RelayedEthSweepReceipt {
+  readonly txHash: Hex;
+  readonly status: 'success';
+  readonly blockNumber: bigint;
+  readonly ethRelayerContract: Address;
+  readonly destination: Address;
+  readonly stealthAddress: Address;
+}

package/tsconfig.json

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