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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shroud-fi/self-host-relayer",
-  "version": "0.1.1",
+  "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.2"
+    "@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 });
+  }
+}