@shroud-fi/self-host-relayer 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/self-host-relayer",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Self-hosted gasless sweep relayer service for ShroudFi — Fastify server that broadcasts EIP-7702 / ERC-2771 sweep transactions.",
   "keywords": [
     "shroudfi",
@@ -26,13 +26,16 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md"
   ],
   "dependencies": {
     "fastify": "^5.0.0",
     "@fastify/cors": "^10.0.0",
     "@fastify/rate-limit": "^10.0.0",
-    "@shroud-fi/transport": "0.1.3"
+    "@shroud-fi/transport": "0.1.4"
   },
   "peerDependencies": {
     "viem": "^2.21.0"

package/src/dev-entry.ts

@@ -0,0 +1,91 @@
+/**
+ * Dev entry: reads config from env vars and starts the server.
+ *
+ * Required env:
+ *   SHROUDFI_RELAYER_CONTRACT       - deployed ShroudFiRelayer address
+ *   SHROUDFI_RELAYER_FORWARDER_KEY  - 0x-prefixed 32-byte forwarder EOA key
+ *   SHROUDFI_RELAYER_RPC_URL        - chain RPC URL
+ *
+ * Optional env:
+ *   SHROUDFI_RELAYER_CHAIN_ID       - default 84532
+ *   SHROUDFI_RELAYER_PORT           - default 8787
+ *   SHROUDFI_RELAYER_ORIGINS        - comma-sep allowed origins (default localhost demo)
+ *   SHROUDFI_RELAYER_RATE_LIMIT     - per-IP requests per minute (default 30)
+ *   SHROUDFI_ETH_RELAYER_CONTRACT   - deployed ShroudFiEthRelayer address.
+ *                                     When set, /relay-eth becomes active for
+ *                                     gasless ETH sweeps via EIP-7702. When
+ *                                     unset, /relay-eth returns 501.
+ *
+ * Privacy: this file is the ONLY place that touches process.env for the
+ * forwarder key. Once read, the key flows into a viem account closure inside
+ * the server and never resurfaces.
+ */
+
+import { startServer } from './server.js';
+import { RelayConfigError } from './errors.js';
+import type { Address, Hex } from 'viem';
+import type { ServiceConfig } from './types.js';
+
+function envOrThrow(name: string): string {
+  const v = process.env[name];
+  if (v === undefined || v.trim().length === 0) {
+    throw new RelayConfigError(name);
+  }
+  return v.trim();
+}
+
+function loadConfig(): ServiceConfig {
+  const chainId = Number(
+    process.env.SHROUDFI_RELAYER_CHAIN_ID?.trim() ?? '84532',
+  );
+  const port = Number(process.env.SHROUDFI_RELAYER_PORT?.trim() ?? '8787');
+  const rateLimitPerMinute = Number(
+    process.env.SHROUDFI_RELAYER_RATE_LIMIT?.trim() ?? '30',
+  );
+  const originsCsv =
+    process.env.SHROUDFI_RELAYER_ORIGINS?.trim() ??
+    'http://localhost:3000,http://localhost:3001,http://localhost:3002,http://localhost:3003,http://localhost:3005,http://localhost:3006,http://localhost:3008,http://localhost:3009,http://127.0.0.1:3005,http://127.0.0.1:3009';
+  const allowedOrigins = originsCsv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  const ethRelayerRaw = process.env.SHROUDFI_ETH_RELAYER_CONTRACT?.trim();
+  const ethRelayerContract: Address | undefined =
+    ethRelayerRaw !== undefined && ethRelayerRaw.length > 0
+      ? (ethRelayerRaw as Address)
+      : undefined;
+
+  const base = {
+    chainId,
+    port,
+    rateLimitPerMinute,
+    allowedOrigins,
+    relayerContract: envOrThrow('SHROUDFI_RELAYER_CONTRACT') as Address,
+    rpcUrl: envOrThrow('SHROUDFI_RELAYER_RPC_URL'),
+    forwarderPrivateKey: envOrThrow(
+      'SHROUDFI_RELAYER_FORWARDER_KEY',
+    ) as Hex,
+  };
+  return ethRelayerContract === undefined
+    ? base
+    : { ...base, ethRelayerContract };
+}
+
+async function main(): Promise<void> {
+  const cfg = loadConfig();
+  await startServer(cfg);
+  // Print a single line so the operator knows the service is up. NO key,
+  // NO RPC URL, NO contract address (those are public but we keep the
+  // surface minimal — they can be queried via /health).
+  // eslint-disable-next-line no-console
+  console.log(
+    `self-host-relayer listening on http://127.0.0.1:${cfg.port} (chain ${cfg.chainId})`,
+  );
+}
+
+void main().catch((err: unknown) => {
+  // eslint-disable-next-line no-console
+  console.error(err instanceof Error ? err.name : 'StartupError');
+  process.exit(1);
+});

package/src/errors.ts

@@ -0,0 +1,62 @@
+/**
+ * Privacy-safe errors for @shroud-fi/self-host-relayer.
+ *
+ * Invariants mirrored from other packages:
+ *   - No key bytes in messages
+ *   - No amount values in messages
+ *   - No private signature bytes in messages
+ */
+
+export class SelfHostRelayerError extends Error {
+  override readonly name: string = 'SelfHostRelayerError';
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+  }
+}
+
+export class InvalidRelayRequestError extends SelfHostRelayerError {
+  override readonly name: string = 'InvalidRelayRequestError';
+  constructor() {
+    super('Relay request body failed validation');
+  }
+}
+
+export class RelayBroadcastError extends SelfHostRelayerError {
+  override readonly name: string = 'RelayBroadcastError';
+  constructor(underlyingName?: string, options?: { cause?: unknown }) {
+    super(
+      underlyingName !== undefined
+        ? `Broadcast failed (${underlyingName})`
+        : 'Broadcast failed',
+      options,
+    );
+  }
+}
+
+export class RelayConfigError extends SelfHostRelayerError {
+  override readonly name: string = 'RelayConfigError';
+  constructor(field: string) {
+    super(`Relayer config missing required field: ${field}`);
+  }
+}
+
+export class InvalidRelayEthRequestError extends SelfHostRelayerError {
+  override readonly name: string = 'InvalidRelayEthRequestError';
+  constructor() {
+    super('Relay ETH request body failed validation');
+  }
+}
+
+export class EthRelayerNotConfiguredError extends SelfHostRelayerError {
+  override readonly name: string = 'EthRelayerNotConfiguredError';
+  constructor() {
+    super('ETH relayer contract address not configured');
+  }
+}
+
+export class AuthorizationContractMismatchError extends SelfHostRelayerError {
+  override readonly name: string = 'AuthorizationContractMismatchError';
+  constructor() {
+    super('EIP-7702 authorization address does not match configured ETH relayer');
+  }
+}

package/src/index.ts

@@ -0,0 +1,31 @@
+// Public surface — @shroud-fi/self-host-relayer
+//
+// Exports the server builder + the pure relay-logic helpers so the same
+// package can be embedded in another Node process or run standalone via
+// `pnpm dev`.
+
+export { buildServer, startServer } from './server.js';
+export { buildRelayCalldata, relayRequest } from './relay.js';
+export type { RelayCtx, RelayResult } from './relay.js';
+export {
+  buildEthSweepCalldata,
+  relayEthRequest,
+} from './relay-eth.js';
+export type { RelayEthCtx, RelayEthResult } from './relay-eth.js';
+export type {
+  RelayRequest,
+  RelayResponse,
+  RelaySuccess,
+  RelayFailure,
+  ServiceConfig,
+  RelayEthRequest,
+} from './types.js';
+export {
+  SelfHostRelayerError,
+  InvalidRelayRequestError,
+  RelayBroadcastError,
+  RelayConfigError,
+  InvalidRelayEthRequestError,
+  EthRelayerNotConfiguredError,
+  AuthorizationContractMismatchError,
+} from './errors.js';

package/src/prod-entry.ts

@@ -0,0 +1,112 @@
+/**
+ * Production entry: strict env, fail-fast on missing required values, no
+ * permissive defaults that could mask misconfiguration in deployment.
+ *
+ * Required env (no defaults — startup fails if any are missing):
+ *   SHROUDFI_RELAYER_CONTRACT       - deployed ShroudFiRelayer address
+ *   SHROUDFI_RELAYER_FORWARDER_KEY  - 0x-prefixed 32-byte forwarder EOA key
+ *   SHROUDFI_RELAYER_RPC_URL        - chain RPC URL
+ *   SHROUDFI_RELAYER_ORIGINS        - comma-sep allowed origins (e.g. https://app.shroudfi.live)
+ *   SHROUDFI_RELAYER_CHAIN_ID       - chain id (84532 = Base Sepolia, 8453 = Base)
+ *   SHROUDFI_RELAYER_PORT           - bind port (typically 8789 on droplet)
+ *
+ * Optional env:
+ *   SHROUDFI_RELAYER_RATE_LIMIT     - per-IP requests per minute (default 30)
+ *   SHROUDFI_ETH_RELAYER_CONTRACT   - deployed ShroudFiEthRelayer address.
+ *                                     When set, /relay-eth becomes active for
+ *                                     gasless ETH sweeps via EIP-7702. When
+ *                                     unset, /relay-eth returns 501.
+ *   DEBUG_DIAGNOSTICS               - "1" to enable per-request preflight + sig recovery logs
+ *
+ * Differences from dev-entry.ts:
+ *   - Every required field uses envOrThrow; no fallbacks
+ *   - SHROUDFI_RELAYER_ORIGINS is REQUIRED (dev defaults to localhost; prod must be explicit)
+ *   - No startup log line printed to stdout — only journald via PM2 captures fastify's
+ *     own "Server listening at ..." line
+ *   - DEBUG_DIAGNOSTICS env opts into the per-request debug logs (off by default)
+ *
+ * Privacy: this file is the ONLY place that touches process.env for the
+ * forwarder key. Once read, the key flows into a viem account closure inside
+ * the server and never resurfaces.
+ */
+
+import { startServer } from './server.js';
+import { RelayConfigError } from './errors.js';
+import type { Address, Hex } from 'viem';
+import type { ServiceConfig } from './types.js';
+
+function envOrThrow(name: string): string {
+  const v = process.env[name];
+  if (v === undefined || v.trim().length === 0) {
+    throw new RelayConfigError(name);
+  }
+  return v.trim();
+}
+
+function loadConfig(): ServiceConfig {
+  const chainId = Number(envOrThrow('SHROUDFI_RELAYER_CHAIN_ID'));
+  if (!Number.isFinite(chainId) || chainId <= 0) {
+    throw new RelayConfigError('SHROUDFI_RELAYER_CHAIN_ID');
+  }
+
+  const port = Number(envOrThrow('SHROUDFI_RELAYER_PORT'));
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new RelayConfigError('SHROUDFI_RELAYER_PORT');
+  }
+
+  const rateLimitRaw = process.env.SHROUDFI_RELAYER_RATE_LIMIT?.trim();
+  const rateLimitPerMinute =
+    rateLimitRaw && rateLimitRaw.length > 0 ? Number(rateLimitRaw) : 30;
+  if (!Number.isFinite(rateLimitPerMinute) || rateLimitPerMinute <= 0) {
+    throw new RelayConfigError('SHROUDFI_RELAYER_RATE_LIMIT');
+  }
+
+  const originsCsv = envOrThrow('SHROUDFI_RELAYER_ORIGINS');
+  const allowedOrigins = originsCsv
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+  if (allowedOrigins.length === 0) {
+    throw new RelayConfigError('SHROUDFI_RELAYER_ORIGINS');
+  }
+
+  const debugDiagnostics = process.env.DEBUG_DIAGNOSTICS === '1';
+
+  const ethRelayerRaw = process.env.SHROUDFI_ETH_RELAYER_CONTRACT?.trim();
+  const ethRelayerContract: Address | undefined =
+    ethRelayerRaw !== undefined && ethRelayerRaw.length > 0
+      ? (ethRelayerRaw as Address)
+      : undefined;
+
+  const base = {
+    chainId,
+    port,
+    rateLimitPerMinute,
+    allowedOrigins,
+    relayerContract: envOrThrow('SHROUDFI_RELAYER_CONTRACT') as Address,
+    rpcUrl: envOrThrow('SHROUDFI_RELAYER_RPC_URL'),
+    forwarderPrivateKey: envOrThrow(
+      'SHROUDFI_RELAYER_FORWARDER_KEY',
+    ) as Hex,
+    debugDiagnostics,
+  };
+  return ethRelayerContract === undefined
+    ? base
+    : { ...base, ethRelayerContract };
+}
+
+async function main(): Promise<void> {
+  const cfg = loadConfig();
+  await startServer(cfg);
+  // Intentionally no stdout — Fastify's logger already emits a "Server
+  // listening at ..." line that PM2/journald captures. Avoid extra surface.
+}
+
+void main().catch((err: unknown) => {
+  // Startup failure → emit only the error class name to stderr, then exit 1.
+  // PM2 will record this and (per ecosystem config) attempt restart up to
+  // max_restarts before giving up.
+  // eslint-disable-next-line no-console
+  console.error(err instanceof Error ? err.name : 'StartupError');
+  process.exit(1);
+});

package/src/relay-eth.ts

@@ -0,0 +1,122 @@
+/**
+ * ETH gasless sweep relay — broadcasts an EIP-7702 type-0x04 tx that delegates
+ * the stealth EOA to ShroudFiEthRelayer and calls sweepETH(destination,
+ * deadline, signature).
+ *
+ * Privacy invariants:
+ *   - Relayer EOA's private key held in the viem account closure. Never
+ *     logged or attached to thrown errors.
+ *   - The EIP-712 signature in the request is a one-time spending
+ *     authorization bound to (destination, deadline, chainId, stealthEOA).
+ *     We pass it through verbatim — never store or re-sign.
+ *   - No amount fields anywhere in the request or response.
+ */
+
+import {
+  encodeFunctionData,
+  type Account,
+  type Chain,
+  type Hex,
+  type PublicClient,
+  type SignedAuthorization,
+  type Transport,
+  type WalletClient,
+} from 'viem';
+import { RelayBroadcastError } from './errors.js';
+import type { RelayEthRequest } from './types.js';
+
+const SWEEP_ETH_ABI = [
+  {
+    type: 'function',
+    name: 'sweepETH',
+    stateMutability: 'nonpayable',
+    inputs: [
+      { name: 'destination', type: 'address' },
+      { name: 'deadline', type: 'uint256' },
+      { name: 'signature', type: 'bytes' },
+    ],
+    outputs: [],
+  },
+] as const;
+
+/**
+ * Same generic-loose shape as RelayCtx. Holds the broadcast-side viem clients
+ * plus the relayer EOA. The relayer EOA pays gas for the outer tx.
+ */
+export interface RelayEthCtx {
+  readonly publicClient: PublicClient<Transport, Chain | undefined>;
+  readonly walletClient: WalletClient<Transport, Chain | undefined, Account>;
+  readonly account: Account;
+}
+
+export interface RelayEthResult {
+  readonly txHash: Hex;
+  readonly blockNumber: bigint;
+}
+
+/**
+ * Reconstruct a viem `SignedAuthorization` from the wire-encoded fields. The
+ * fields are exactly what the SDK serialises in @shroud-fi/relayer's
+ * eth-sweep.ts — `nonce` arrives as a number, `chainId` as a number, `r`/`s`
+ * as 0x-prefixed hex, `yParity` as 0 or 1.
+ */
+function reconstructAuthorization(req: RelayEthRequest): SignedAuthorization {
+  return {
+    address: req.authorization.address,
+    chainId: req.authorization.chainId,
+    nonce: req.authorization.nonce,
+    r: req.authorization.r,
+    s: req.authorization.s,
+    yParity: req.authorization.yParity,
+  };
+}
+
+/**
+ * Build the inner sweepETH calldata. The OUTER tx is the type-0x04 transaction
+ * itself which carries the authorization list and the `to: stealthAddress`;
+ * the inner data is what executes once the EOA's code is set to the relayer.
+ */
+export function buildEthSweepCalldata(req: RelayEthRequest): Hex {
+  return encodeFunctionData({
+    abi: SWEEP_ETH_ABI,
+    functionName: 'sweepETH',
+    args: [req.destination, BigInt(req.deadline), req.signature],
+  });
+}
+
+/**
+ * Submit the type-0x04 tx and wait for receipt.
+ *
+ * On any viem error we wrap with RelayBroadcastError(name, { cause: err }) so
+ * the server can walk the cause chain and log the actual revert reason
+ * (public on-chain data) without surfacing it to clients.
+ */
+export async function relayEthRequest(
+  ctx: RelayEthCtx,
+  req: RelayEthRequest,
+): Promise<RelayEthResult> {
+  const data = buildEthSweepCalldata(req);
+  const authorization = reconstructAuthorization(req);
+
+  try {
+    const txHash = await ctx.walletClient.sendTransaction({
+      account: ctx.account,
+      chain: ctx.walletClient.chain ?? null,
+      to: req.stealthAddress,
+      data,
+      value: 0n,
+      authorizationList: [authorization],
+    });
+    const receipt = await ctx.publicClient.waitForTransactionReceipt({
+      hash: txHash,
+    });
+    if (receipt.status !== 'success') {
+      throw new RelayBroadcastError('TransactionReverted');
+    }
+    return { txHash, blockNumber: receipt.blockNumber };
+  } catch (err) {
+    if (err instanceof RelayBroadcastError) throw err;
+    const name = err instanceof Error ? err.name : 'UnknownError';
+    throw new RelayBroadcastError(name, { cause: err });
+  }
+}

package/src/relay.ts

@@ -0,0 +1,110 @@
+/**
+ * Core relay logic. Pure function — given a validated request + viem clients,
+ * encodes the ERC-2771 wrapped calldata and broadcasts via the relayer EOA.
+ *
+ * Privacy invariants:
+ *   - The relayer EOA's private key is held in a viem account closure. It is
+ *     never logged, serialized, or attached to thrown errors.
+ *   - The stealth address is data, not key material.
+ *   - The permit (v, r, s, deadline) is a one-time authorization for the
+ *     specific (owner, spender, value, deadline) bound at signing time.
+ */
+
+import {
+  encodeFunctionData,
+  type Account,
+  type Address,
+  type Chain,
+  type Hex,
+  type PublicClient,
+  type Transport,
+  type WalletClient,
+} from 'viem';
+import { RelayBroadcastError } from './errors.js';
+import type { RelayRequest } from './types.js';
+
+const SWEEP_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: [],
+  },
+] as const;
+
+// Generic-loose client types: the relay function only calls a small slice of
+// the viem surface (sendTransaction + waitForTransactionReceipt), so we let
+// callers pass clients keyed to any specific chain (Base, Base Sepolia, etc.)
+// without forcing their chain shape onto our type signature.
+export interface RelayCtx {
+  readonly publicClient: PublicClient<Transport, Chain | undefined>;
+  readonly walletClient: WalletClient<Transport, Chain | undefined, Account>;
+  readonly account: Account;
+  readonly relayerContract: Address;
+}
+
+export interface RelayResult {
+  readonly txHash: Hex;
+  readonly blockNumber: bigint;
+}
+
+/**
+ * Build the ERC-2771-wrapped calldata: encoded sweepERC20WithPermit(...) with
+ * the 20-byte stealth address appended. ShroudFiRelayer's ERC2771Context
+ * reads _msgSender() as the appended address when msg.sender is the trusted
+ * forwarder (= the relayer EOA = `account` here).
+ */
+export function buildRelayCalldata(req: RelayRequest): Hex {
+  const inner = encodeFunctionData({
+    abi: SWEEP_ABI,
+    functionName: 'sweepERC20WithPermit',
+    args: [
+      req.token,
+      req.destination,
+      BigInt(req.deadline),
+      req.v,
+      req.r,
+      req.s,
+    ],
+  });
+  const suffix = req.stealthAddress.slice(2).toLowerCase();
+  // Inner is `0x...`; concatenate stealth bytes (20 = 40 hex chars).
+  return (inner + suffix) as Hex;
+}
+
+/**
+ * Broadcast the wrapped tx. Waits for the receipt before returning.
+ *
+ * Throws RelayBroadcastError on any underlying viem error. Errors are wrapped
+ * to strip out potentially key-bearing payloads from the visible message.
+ */
+export async function relayRequest(
+  ctx: RelayCtx,
+  req: RelayRequest,
+): Promise<RelayResult> {
+  const data = buildRelayCalldata(req);
+  try {
+    const txHash = await ctx.walletClient.sendTransaction({
+      account: ctx.account,
+      chain: ctx.walletClient.chain ?? null,
+      to: ctx.relayerContract,
+      data,
+      value: 0n,
+    });
+    const receipt = await ctx.publicClient.waitForTransactionReceipt({
+      hash: txHash,
+    });
+    return { txHash, blockNumber: receipt.blockNumber };
+  } catch (err) {
+    const name = err instanceof Error ? err.name : 'UnknownError';
+    throw new RelayBroadcastError(name, { cause: err });
+  }
+}

package/src/server.ts

@@ -0,0 +1,408 @@
+/**
+ * Fastify server for @shroud-fi/self-host-relayer.
+ *
+ * Endpoints:
+ *   POST /relay   - submit a permit-signed sweep request
+ *   GET  /health  - liveness probe
+ *
+ * Privacy invariants:
+ *   - Request body is validated then discarded — never logged.
+ *   - Error responses carry only error class names, never inner messages.
+ *   - The forwarder EOA's private key is read from config once, then held in
+ *     a viem account closure. Never logged, never serialized to disk.
+ */
+
+import Fastify, { type FastifyInstance } from 'fastify';
+import cors from '@fastify/cors';
+import rateLimit from '@fastify/rate-limit';
+import {
+  createPublicClient,
+  createWalletClient,
+  http,
+  isAddress,
+  recoverTypedDataAddress,
+  serializeSignature,
+  getAddress,
+  type Address,
+  type Chain,
+  type Hex,
+  type PublicClient,
+  type Transport,
+  type WalletClient,
+} from 'viem';
+import type { Account } from 'viem/accounts';
+import { base, baseSepolia } from 'viem/chains';
+import { privateKeyToAccount } from 'viem/accounts';
+import {
+  AuthorizationContractMismatchError,
+  EthRelayerNotConfiguredError,
+  InvalidRelayEthRequestError,
+  InvalidRelayRequestError,
+} from './errors.js';
+import { relayRequest } from './relay.js';
+import { relayEthRequest } from './relay-eth.js';
+import type {
+  RelayEthRequest,
+  RelayRequest,
+  RelayResponse,
+  ServiceConfig,
+} from './types.js';
+
+const HEX32_RE = /^0x[0-9a-fA-F]{64}$/;
+
+function isHex32(s: unknown): s is Hex {
+  return typeof s === 'string' && HEX32_RE.test(s);
+}
+
+function validateRequest(body: unknown): RelayRequest {
+  if (typeof body !== 'object' || body === null) {
+    throw new InvalidRelayRequestError();
+  }
+  const b = body as Record<string, unknown>;
+  if (!isAddress(b.token as string)) throw new InvalidRelayRequestError();
+  if (!isAddress(b.destination as string)) throw new InvalidRelayRequestError();
+  if (!isAddress(b.stealthAddress as string)) throw new InvalidRelayRequestError();
+  if (typeof b.deadline !== 'string' || !/^\d+$/.test(b.deadline)) {
+    throw new InvalidRelayRequestError();
+  }
+  if (typeof b.v !== 'number' || b.v < 0 || b.v > 255) {
+    throw new InvalidRelayRequestError();
+  }
+  if (!isHex32(b.r)) throw new InvalidRelayRequestError();
+  if (!isHex32(b.s)) throw new InvalidRelayRequestError();
+  return {
+    token: b.token as Address,
+    destination: b.destination as Address,
+    stealthAddress: b.stealthAddress as Address,
+    deadline: b.deadline,
+    v: b.v,
+    r: b.r as Hex,
+    s: b.s as Hex,
+  };
+}
+
+const HEX_PREFIXED_RE = /^0x[0-9a-fA-F]+$/;
+
+function isHex(s: unknown): s is Hex {
+  return typeof s === 'string' && HEX_PREFIXED_RE.test(s);
+}
+
+function validateEthRequest(body: unknown): RelayEthRequest {
+  if (typeof body !== 'object' || body === null) {
+    throw new InvalidRelayEthRequestError();
+  }
+  const b = body as Record<string, unknown>;
+  if (!isAddress(b.stealthAddress as string)) throw new InvalidRelayEthRequestError();
+  if (!isAddress(b.destination as string)) throw new InvalidRelayEthRequestError();
+  if (typeof b.chainId !== 'number') throw new InvalidRelayEthRequestError();
+  if (typeof b.deadline !== 'string' || !/^\d+$/.test(b.deadline)) {
+    throw new InvalidRelayEthRequestError();
+  }
+  if (!isHex(b.signature)) throw new InvalidRelayEthRequestError();
+  const auth = b.authorization as Record<string, unknown> | undefined;
+  if (typeof auth !== 'object' || auth === null) throw new InvalidRelayEthRequestError();
+  if (!isAddress(auth.address as string)) throw new InvalidRelayEthRequestError();
+  if (typeof auth.chainId !== 'number') throw new InvalidRelayEthRequestError();
+  if (typeof auth.nonce !== 'number' || auth.nonce < 0) {
+    throw new InvalidRelayEthRequestError();
+  }
+  if (!isHex32(auth.r)) throw new InvalidRelayEthRequestError();
+  if (!isHex32(auth.s)) throw new InvalidRelayEthRequestError();
+  if (auth.yParity !== 0 && auth.yParity !== 1) throw new InvalidRelayEthRequestError();
+  return {
+    stealthAddress: b.stealthAddress as Address,
+    destination: b.destination as Address,
+    chainId: b.chainId,
+    deadline: b.deadline,
+    signature: b.signature,
+    authorization: {
+      address: auth.address as Address,
+      chainId: auth.chainId,
+      nonce: auth.nonce,
+      r: auth.r as Hex,
+      s: auth.s as Hex,
+      yParity: auth.yParity as 0 | 1,
+    },
+  };
+}
+
+export async function buildServer(
+  cfg: ServiceConfig,
+): Promise<FastifyInstance> {
+  const fastify = Fastify({
+    // Logging stripped of body — only method, url, status, response time.
+    logger: { level: 'info' },
+    disableRequestLogging: true,
+  });
+
+  await fastify.register(cors, {
+    origin: (origin, cb) => {
+      // Allow same-host requests (no Origin header) for curl/healthchecks.
+      if (origin === undefined) return cb(null, true);
+      if (cfg.allowedOrigins.includes(origin)) return cb(null, true);
+      return cb(new Error('Origin not allowed'), false);
+    },
+  });
+
+  await fastify.register(rateLimit, {
+    max: cfg.rateLimitPerMinute,
+    timeWindow: '1 minute',
+  });
+
+  const chain = cfg.chainId === 8453 ? base : baseSepolia;
+  const account = privateKeyToAccount(cfg.forwarderPrivateKey);
+  // Viem's OP-stack chain extension widens the tx type set. Our relayRequest
+  // signature uses a generic Chain; cast at the boundary so the OP extensions
+  // don't bleed into our public types.
+  const publicClient = createPublicClient({
+    chain,
+    transport: http(cfg.rpcUrl, { batch: false }),
+  }) as unknown as PublicClient<Transport, Chain | undefined>;
+  const walletClient = createWalletClient({
+    chain,
+    account,
+    transport: http(cfg.rpcUrl, { batch: false }),
+  }) as unknown as WalletClient<Transport, Chain | undefined, Account>;
+
+  fastify.get('/health', async () => ({ ok: true, chainId: cfg.chainId }));
+
+  fastify.post<{ Body: unknown }>('/relay', async (req, reply) => {
+    let validated: RelayRequest;
+    try {
+      validated = validateRequest(req.body);
+    } catch (err) {
+      const name = err instanceof Error ? err.name : 'InvalidRelayRequestError';
+      reply.status(400);
+      const body: RelayResponse = { ok: false, error: name };
+      return body;
+    }
+
+    // Diagnostic pre-flight: read on-chain state for the (stealth, token) pair
+    // before broadcasting. NOT key material — all four values (balance,
+    // allowance, nonce, name) are public reads. Off in prod by default; flip
+    // cfg.debugDiagnostics = true (DEBUG_DIAGNOSTICS=1 env) to enable when
+    // troubleshooting permit digest mismatches.
+    if (cfg.debugDiagnostics === true) try {
+      const tokenAbi = [
+        { type: 'function', name: 'balanceOf', stateMutability: 'view', inputs: [{ name: 'a', type: 'address' }], outputs: [{ type: 'uint256' }] },
+        { type: 'function', name: 'allowance', stateMutability: 'view', inputs: [{ name: 'o', type: 'address' }, { name: 's', type: 'address' }], outputs: [{ type: 'uint256' }] },
+        { type: 'function', name: 'nonces', stateMutability: 'view', inputs: [{ name: 'a', type: 'address' }], outputs: [{ type: 'uint256' }] },
+        { type: 'function', name: 'name', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
+        { type: 'function', name: 'version', stateMutability: 'view', inputs: [], outputs: [{ type: 'string' }] },
+      ] as const;
+      const [bal, allow, nonce, name] = await Promise.all([
+        publicClient.readContract({ address: validated.token, abi: tokenAbi, functionName: 'balanceOf', args: [validated.stealthAddress] }) as Promise<bigint>,
+        publicClient.readContract({ address: validated.token, abi: tokenAbi, functionName: 'allowance', args: [validated.stealthAddress, cfg.relayerContract] }) as Promise<bigint>,
+        publicClient.readContract({ address: validated.token, abi: tokenAbi, functionName: 'nonces', args: [validated.stealthAddress] }) as Promise<bigint>,
+        publicClient.readContract({ address: validated.token, abi: tokenAbi, functionName: 'name' }) as Promise<string>,
+      ]);
+      let probedVersion = 'unprobed';
+      try {
+        probedVersion = (await publicClient.readContract({
+          address: validated.token,
+          abi: tokenAbi,
+          functionName: 'version',
+        })) as string;
+      } catch {
+        probedVersion = 'NOT_EXPOSED(fallback_to_1)';
+      }
+      const now = Math.floor(Date.now() / 1000);
+      fastify.log.info({
+        stealth: validated.stealthAddress,
+        token: validated.token,
+        balance: bal.toString(),
+        allowance: allow.toString(),
+        nonce: nonce.toString(),
+        tokenName: name,
+        probedVersion,
+        deadline: validated.deadline,
+        nowUnix: now,
+        deadlineDelta: Number(BigInt(validated.deadline) - BigInt(now)),
+        v: validated.v,
+      }, 'relay preflight state');
+
+      // Signature recovery: rebuild the same EIP-712 message the agent SHOULD
+      // have signed (under both "1" and probed version) and see which (if any)
+      // recovers to the stealth address. Whichever ONE matches tells us the
+      // exact domain used. If NEITHER matches, the failure is in value/nonce/
+      // chainId/spender — list those candidates too.
+      try {
+        const fullSig = serializeSignature({ r: validated.r, s: validated.s, v: BigInt(validated.v) });
+        const message = {
+          owner: validated.stealthAddress,
+          spender: cfg.relayerContract,
+          value: bal,
+          nonce,
+          deadline: BigInt(validated.deadline),
+        } as const;
+        const types = {
+          Permit: [
+            { name: 'owner', type: 'address' },
+            { name: 'spender', type: 'address' },
+            { name: 'value', type: 'uint256' },
+            { name: 'nonce', type: 'uint256' },
+            { name: 'deadline', type: 'uint256' },
+          ],
+        } as const;
+        const candidates: Array<{ label: string; domain: { name: string; version: string; chainId: number; verifyingContract: Address } }> = [
+          { label: 'name=' + name + ',ver=1,chain=' + cfg.chainId,
+            domain: { name, version: '1', chainId: cfg.chainId, verifyingContract: validated.token } },
+        ];
+        if (probedVersion !== 'unprobed' && probedVersion !== 'NOT_EXPOSED(fallback_to_1)') {
+          candidates.push({
+            label: 'name=' + name + ',ver=' + probedVersion + ',chain=' + cfg.chainId,
+            domain: { name, version: probedVersion, chainId: cfg.chainId, verifyingContract: validated.token },
+          });
+        }
+        const recoveries: Array<{ label: string; recovered: string; matches: boolean }> = [];
+        for (const c of candidates) {
+          const recovered = await recoverTypedDataAddress({
+            domain: c.domain,
+            types,
+            primaryType: 'Permit',
+            message,
+            signature: fullSig,
+          });
+          recoveries.push({
+            label: c.label,
+            recovered,
+            matches: recovered.toLowerCase() === validated.stealthAddress.toLowerCase(),
+          });
+        }
+        fastify.log.info({ recoveries, expectedStealth: validated.stealthAddress }, 'sig recovery probe');
+      } catch (sigErr) {
+        fastify.log.warn({ name: sigErr instanceof Error ? sigErr.name : 'unknown', msg: sigErr instanceof Error ? sigErr.message.slice(0, 200) : '' }, 'sig recovery threw');
+      }
+    } catch (probeErr) {
+      fastify.log.warn({ name: probeErr instanceof Error ? probeErr.name : 'unknown' }, 'preflight probe failed');
+    }
+
+    try {
+      const result = await relayRequest(
+        {
+          publicClient,
+          walletClient,
+          account,
+          relayerContract: cfg.relayerContract,
+        },
+        validated,
+      );
+      const body: RelayResponse = {
+        ok: true,
+        txHash: result.txHash,
+        blockNumber: result.blockNumber.toString(),
+      };
+      return body;
+    } catch (err) {
+      const name = err instanceof Error ? err.name : 'RelayBroadcastError';
+      // Diagnostic: walk the cause chain and emit each viem error class +
+      // shortMessage (revert reason). These are public on-chain values, never
+      // key material. Logged via fastify.log.error so the operator can find
+      // the actual revert without surfacing it to clients.
+      const chain: Array<{ name: string; shortMessage?: string }> = [];
+      let cursor: unknown = err;
+      let depth = 0;
+      while (cursor instanceof Error && depth < 6) {
+        const sm = (cursor as { shortMessage?: string }).shortMessage;
+        const frame: { name: string; shortMessage?: string } = { name: cursor.name };
+        if (sm !== undefined) frame.shortMessage = sm;
+        chain.push(frame);
+        cursor = (cursor as { cause?: unknown }).cause;
+        depth++;
+      }
+      fastify.log.error({ chain }, 'relay broadcast failed');
+      reply.status(502);
+      const body: RelayResponse = { ok: false, error: name };
+      return body;
+    }
+  });
+
+  // ─── /relay-eth — P5.1 EIP-7702 ETH gasless sweep ─────────────────────
+  fastify.post<{ Body: unknown }>('/relay-eth', async (req, reply) => {
+    // Refuse early if the operator hasn't pinned the deployed ETH relayer.
+    if (cfg.ethRelayerContract === undefined) {
+      reply.status(501);
+      const body: RelayResponse = {
+        ok: false,
+        error: new EthRelayerNotConfiguredError().name,
+      };
+      return body;
+    }
+
+    let validated: RelayEthRequest;
+    try {
+      validated = validateEthRequest(req.body);
+    } catch (err) {
+      const name = err instanceof Error ? err.name : 'InvalidRelayEthRequestError';
+      reply.status(400);
+      const body: RelayResponse = { ok: false, error: name };
+      return body;
+    }
+
+    // Defence in depth: the authorization MUST delegate to the configured
+    // ETH relayer contract. A mismatch means either (a) the SDK is talking
+    // to a different deployment, or (b) someone is trying to delegate to an
+    // attacker contract via this relayer. Either way, refuse.
+    if (
+      getAddress(validated.authorization.address) !==
+      getAddress(cfg.ethRelayerContract)
+    ) {
+      reply.status(400);
+      const body: RelayResponse = {
+        ok: false,
+        error: new AuthorizationContractMismatchError().name,
+      };
+      return body;
+    }
+
+    // Chain ID consistency: the SDK's chainId must match this service's chain.
+    if (validated.chainId !== cfg.chainId) {
+      reply.status(400);
+      const body: RelayResponse = {
+        ok: false,
+        error: new InvalidRelayEthRequestError().name,
+      };
+      return body;
+    }
+
+    try {
+      const result = await relayEthRequest(
+        { publicClient, walletClient, account },
+        validated,
+      );
+      const body: RelayResponse = {
+        ok: true,
+        txHash: result.txHash,
+        blockNumber: result.blockNumber.toString(),
+      };
+      return body;
+    } catch (err) {
+      const name = err instanceof Error ? err.name : 'RelayBroadcastError';
+      // Same cause-chain diagnostic as /relay. Public on-chain data only —
+      // never signatures or amounts.
+      const chain: Array<{ name: string; shortMessage?: string }> = [];
+      let cursor: unknown = err;
+      let depth = 0;
+      while (cursor instanceof Error && depth < 6) {
+        const sm = (cursor as { shortMessage?: string }).shortMessage;
+        const frame: { name: string; shortMessage?: string } = { name: cursor.name };
+        if (sm !== undefined) frame.shortMessage = sm;
+        chain.push(frame);
+        cursor = (cursor as { cause?: unknown }).cause;
+        depth++;
+      }
+      fastify.log.error({ chain }, 'relay-eth broadcast failed');
+      reply.status(502);
+      const body: RelayResponse = { ok: false, error: name };
+      return body;
+    }
+  });
+
+  return fastify;
+}
+
+export async function startServer(cfg: ServiceConfig): Promise<FastifyInstance> {
+  const fastify = await buildServer(cfg);
+  await fastify.listen({ port: cfg.port, host: '127.0.0.1' });
+  return fastify;
+}

package/src/types.ts

@@ -0,0 +1,90 @@
+import type { Address, Hex } from 'viem';
+
+/**
+ * Inbound relay request from a browser/agent.
+ *
+ * Privacy invariants:
+ *   - The stealth address's PRIVATE key NEVER appears here. Only the EIP-2612
+ *     permit signature (v, r, s, deadline) + the public stealth address.
+ *   - No `amount` field — the contract reads `balanceOf(stealth)` on-chain.
+ *   - The relayer service NEVER logs the full body.
+ */
+export interface RelayRequest {
+  readonly token: Address;
+  readonly destination: Address;
+  readonly stealthAddress: Address;
+  readonly deadline: string;
+  readonly v: number;
+  readonly r: Hex;
+  readonly s: Hex;
+}
+
+export interface RelaySuccess {
+  readonly ok: true;
+  readonly txHash: Hex;
+  readonly blockNumber: string;
+}
+
+export interface RelayFailure {
+  readonly ok: false;
+  readonly error: string;
+}
+
+export type RelayResponse = RelaySuccess | RelayFailure;
+
+export interface ServiceConfig {
+  readonly chainId: number;
+  readonly rpcUrl: string;
+  readonly relayerContract: Address;
+  readonly forwarderPrivateKey: Hex;
+  readonly allowedOrigins: readonly string[];
+  readonly port: number;
+  readonly rateLimitPerMinute: number;
+  /**
+   * When true, the /relay handler emits per-request preflight + EIP-712
+   * signature-recovery probe logs. These are valuable for debugging permit
+   * digest mismatches but produce one log line per request and surface
+   * (public) on-chain state. Off by default; enable only when troubleshooting.
+   */
+  readonly debugDiagnostics?: boolean;
+  /**
+   * Address of the ShroudFiEthRelayer contract for the P5.1 ETH gasless path.
+   * Used by /relay-eth as a defence-in-depth check that the inbound
+   * authorization's `address` field matches the deployed contract. When
+   * undefined, /relay-eth returns 501 Not Implemented.
+   */
+  readonly ethRelayerContract?: Address;
+}
+
+// ─── /relay-eth (P5.1, EIP-7702 ETH gasless sweep) ────────────────────────
+
+/**
+ * Inbound /relay-eth request. The shape mirrors what
+ * @shroud-fi/relayer's relayedSweepETH serialises on the SDK side.
+ *
+ * Privacy invariants:
+ *   - The stealth EOA's PRIVATE key NEVER appears here. Only the public
+ *     stealth address + two signatures (EIP-7702 SET_CODE auth + EIP-712
+ *     EthSweep).
+ *   - The signature is a spending-authorisation credential bound to the
+ *     specific (destination, deadline, chainId, stealthEOA) tuple. Never
+ *     logged in full; only the class name of any error appears in server
+ *     logs.
+ *   - No `amount` field — the contract reads address(this).balance under
+ *     EIP-7702 delegation.
+ */
+export interface RelayEthRequest {
+  readonly stealthAddress: Address;
+  readonly destination: Address;
+  readonly chainId: number;
+  readonly deadline: string;
+  readonly signature: Hex;
+  readonly authorization: {
+    readonly address: Address;
+    readonly chainId: number;
+    readonly nonce: number;
+    readonly r: Hex;
+    readonly s: Hex;
+    readonly yParity: 0 | 1;
+  };
+}

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"]
+}