@absol-labs/agent 0.10.0 → 0.12.0-rc.1

package/src/x402-opener/refund-relay.ts

@@ -0,0 +1,1743 @@
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import {
+  BaseError,
+  ContractFunctionRevertedError,
+  concat,
+  decodeEventLog,
+  encodeAbiParameters,
+  getAddress,
+  isAddress,
+  isErc6492Signature,
+  isHex,
+  keccak256,
+  maxUint256,
+  type Account,
+  type Address,
+  type Chain,
+  type Hex,
+  type Log,
+  type PublicClient,
+  type Transport,
+  type WalletClient,
+} from "viem";
+
+import { x402StreamOpenerAbi, x402StreamOpenerFactoryAbi } from "./abi.js";
+import { RelayerQueue } from "./relayer-queue.js";
+import { chainIdFromNetwork } from "./terms.js";
+import {
+  escrowGenerationFor,
+  readEscapeHatchReadyAt,
+  UnsupportedEscrowGenerationError,
+  type EscapeHatchReader,
+  type KnownEscrowGeneration,
+} from "../escrow-generation.js";
+
+/**
+ * The gasless refund relay of the Metrik x402 opener facilitator
+ * (metrik-agent#119).
+ *
+ * A typical x402 payer holds only USDC. Paying through the opener is gasless
+ * (the facilitator's relayer submits `deployAndSettle`), but getting unearned
+ * money back needs two transactions: `close` (payer-only, because anyone else
+ * could cut a payer's service) and `reclaim`. This relay submits them from the
+ * same relayer, which pays the gas:
+ *
+ * - `close`: ONLY with the payer's EIP-712 `Close` signature, relayed as
+ *   `opener.closeWithSig`. Verified off-chain against `payerOf(streamId)`, the
+ *   payer's current opener nonce and the opener's own EIP-712 domain (read from
+ *   the opener, ERC-5267) before anything is simulated.
+ * - `reclaim`: permissionless, because the contract fixes both the amount (a
+ *   Merkle proof against the escrow's LATEST checkpoint root) and the
+ *   destination (`payerOf(streamId)`). The relay fetches the proof from the
+ *   oracle itself and checks it against the on-chain root before simulating.
+ * - `reclaimUnverified` (the no-proof escape hatch, which forfeits the
+ *   operator's earned-but-unclaimed revenue): ONLY with the payer's EIP-712
+ *   `ReclaimUnverified` signature, as `reclaimUnverifiedWithSig`. The unsigned
+ *   `reclaimUnverified` entrypoint is payer-only on-chain and is never called.
+ *
+ * There is no automatic refund and no keeper: nothing here runs unless someone
+ * calls an endpoint.
+ *
+ * ## Bounded against gas abuse
+ *
+ * - Only streams whose escrow buyer is an opener of the configured factory
+ *   (`factory.isOpener(stream.buyer)`, on-chain) are served; everything else is
+ *   `404` before any signature check, oracle call or simulation.
+ * - Every precondition the contract would check is read first (status, expiry,
+ *   settlement window, reclaimed flag, non-zero refund). A request that would
+ *   have no real effect never reaches the relayer.
+ * - Nothing is broadcast without a successful simulation from the relayer, and
+ *   a reclaim's simulation must return exactly the non-zero amount
+ *   `reclaimableFor` predicted.
+ * - At most ONE successful close and ONE successful reclaim (proof or escape
+ *   hatch — the escrow allows one) per stream from this instance. Concurrent
+ *   duplicates are refused synchronously; a repeat after success is refused
+ *   without an RPC write.
+ * - Submission attempts are capped per stream and globally per minute; refused
+ *   requests (bad signature, no effect) do not consume the per-stream budget,
+ *   so nobody can lock a payer out by spamming forged requests.
+ * - Success is reported ONLY from a mined receipt that carries the expected
+ *   escrow and opener events for exactly this stream, payer and amount.
+ * - Submissions go through the relayer's shared, serialized queue.
+ */
+
+/** EIP-712 domain name/version of `X402StreamOpener`. Checked against the opener's ERC-5267 domain. */
+export const OPENER_EIP712_NAME = "Metrik X402StreamOpener";
+export const OPENER_EIP712_VERSION = "1";
+
+/** The two payer-signed opener actions. */
+export type OpenerSignedAction = "Close" | "ReclaimUnverified";
+
+const ACTION_FIELDS = [
+  { name: "streamId", type: "bytes32" },
+  { name: "nonce", type: "uint256" },
+  { name: "deadline", type: "uint256" },
+] as const;
+
+/** Default per-stream relayed submission attempts per minute. */
+export const DEFAULT_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE = 3;
+/** Default relayed refund submission attempts per minute, all streams. */
+export const DEFAULT_REFUND_SUBMISSIONS_PER_MINUTE = 30;
+/** A signed deadline must leave at least this long for the tx to be mined. */
+export const MIN_SIGNATURE_DEADLINE_HEADROOM_SECONDS = 60n;
+
+const STREAM_ID_PATTERN = /^0x[0-9a-fA-F]{64}$/;
+const UINT_PATTERN = /^(0|[1-9]\d{0,77})$/;
+/** 2 KiB of signature is far above any EOA (65 B) or practical ERC-1271 signature. */
+const MAX_SIGNATURE_BYTES = 2048;
+const MAX_ORACLE_RESPONSE_BYTES = 64 * 1024;
+const MAX_PROOF_LENGTH = 64;
+const MAX_LEDGER_ENTRIES = 100_000;
+/** Advisory retry hint while waiting for a checkpoint (the oracle posts every ~15-22 s). */
+const CHECKPOINT_RETRY_HINT_SECONDS = 30;
+
+/**
+ * EIP-712 typed data for a payer-signed opener action (`Close` or
+ * `ReclaimUnverified`), domain-bound to one opener. `nonce` is the payer's
+ * current `opener.nonces(payer)`.
+ */
+export function openerActionTypedData(input: {
+  readonly action: OpenerSignedAction;
+  readonly opener: Address;
+  readonly chainId: number;
+  readonly streamId: Hex;
+  readonly nonce: bigint;
+  readonly deadline: bigint;
+}) {
+  return {
+    domain: {
+      name: OPENER_EIP712_NAME,
+      version: OPENER_EIP712_VERSION,
+      chainId: input.chainId,
+      verifyingContract: getAddress(input.opener),
+    },
+    types: { [input.action]: ACTION_FIELDS } as Record<
+      OpenerSignedAction,
+      typeof ACTION_FIELDS
+    >,
+    primaryType: input.action,
+    message: {
+      streamId: input.streamId,
+      nonce: input.nonce,
+      deadline: input.deadline,
+    },
+  } as const;
+}
+
+/**
+ * The escrow's canonical checkpoint leaf,
+ * `keccak256(bytes.concat(keccak256(abi.encode(streamId, cumulative))))` —
+ * double-hashed, OpenZeppelin `StandardMerkleTree`-compatible.
+ */
+export function checkpointLeaf(streamId: Hex, cumulativeAmount: bigint): Hex {
+  return keccak256(
+    concat([
+      keccak256(
+        encodeAbiParameters(
+          [{ type: "bytes32" }, { type: "uint256" }],
+          [streamId, cumulativeAmount],
+        ),
+      ),
+    ]),
+  );
+}
+
+/** OpenZeppelin `MerkleProof.processProof` (commutative, sorted-pair keccak). */
+export function processMerkleProof(leaf: Hex, proof: readonly Hex[]): Hex {
+  let computed = leaf;
+  for (const sibling of proof) {
+    computed =
+      BigInt(computed) < BigInt(sibling)
+        ? keccak256(concat([computed, sibling]))
+        : keccak256(concat([sibling, computed]));
+  }
+  return computed;
+}
+
+export interface OpenerRefundRelayConfig {
+  /** CAIP-2 network (`eip155:<chainId>`), as the registry gives it. Must match the RPC's chain id. */
+  readonly network: string;
+  readonly factoryAddress: Address;
+  /** The `StreamEscrowV2` the factory settles into (checked by {@link OpenerRefundRelay.init}). */
+  readonly escrowAddress: Address;
+  /** Base URL of the Metrik oracle that serves `GET /checkpoint/proof?streamId=`. */
+  readonly oracleUrl: string;
+  readonly publicClient: PublicClient<Transport, Chain | undefined>;
+  /** The relayer. Pays gas only; never receives or holds a refund. */
+  readonly walletClient: WalletClient<Transport, Chain | undefined, Account>;
+  /** Share with the opener scheme when both use one relayer key. */
+  readonly relayerQueue?: RelayerQueue;
+  /** How long to wait for a receipt before answering `202 pending`. Default 60 s. */
+  readonly receiptTimeoutMs?: number;
+  /** Oracle proof request timeout. Default 10 s. */
+  readonly oracleTimeoutMs?: number;
+  readonly maxSubmissionsPerStreamPerMinute?: number;
+  readonly maxSubmissionsPerMinute?: number;
+  /** Public origin of this service, used for absolute links in `next`. */
+  readonly publicBaseUrl?: string;
+  readonly fetch?: typeof fetch;
+  /** Injectable clock (ms) for the rate windows, for tests. Chain time drives every contract precondition. */
+  readonly nowMs?: () => number;
+  /**
+   * How long a stream's status and its oracle proof are reused, seconds, so
+   * repeated requests for the same stream do not re-hit the RPC or the oracle.
+   * Default {@link DEFAULT_REFUND_READ_CACHE_SECONDS}; 0 disables. Dropped for
+   * a stream as soon as a relayed transaction for it is mined. Never used to
+   * decide a broadcast on its own: the simulation re-checks on-chain state.
+   */
+  readonly readCacheSeconds?: number;
+  /** Where failure details go (server-side only; never sent to clients). */
+  readonly logger?: Pick<Console, "error">;
+  /**
+   * The escrow's generation, which decides when the no-proof escape hatch
+   * opens (V2: `expiresAt + grace`; V3: `min(expiresAt, closedAt) + grace`,
+   * read from `escapeHatchReadyAt`). Default: the SDK registry's
+   * `escrow.generation` for (chain, escrow), else `v2`.
+   */
+  readonly escrowGeneration?: string;
+}
+
+/** Default reuse window for a stream's status and oracle proof. */
+export const DEFAULT_REFUND_READ_CACHE_SECONDS = 5;
+const MAX_CACHED_STREAMS = 10_000;
+
+/** HTTP-shaped outcome of one relay call. `body` is JSON-safe. */
+export interface RefundRelayResponse {
+  readonly status: number;
+  readonly body: Record<string, unknown>;
+  /** Suggested `Retry-After`, seconds. */
+  readonly retryAfterSeconds?: number;
+}
+
+/** What the facilitator HTTP server needs from a refund relay. */
+export interface RefundRelayHandler {
+  status(streamId: string): Promise<RefundRelayResponse>;
+  close(streamId: string, body: unknown): Promise<RefundRelayResponse>;
+  reclaim(streamId: string): Promise<RefundRelayResponse>;
+  reclaimUnverified(
+    streamId: string,
+    body: unknown,
+  ): Promise<RefundRelayResponse>;
+}
+
+type LedgerKind = "close" | "reclaim";
+
+interface CloseExpectation {
+  readonly kind: "close";
+  readonly streamId: Hex;
+  readonly opener: Address;
+  readonly payer: Address;
+}
+interface ReclaimExpectation {
+  readonly kind: "reclaim";
+  readonly action: "reclaim" | "reclaim-unverified";
+  readonly streamId: Hex;
+  readonly opener: Address;
+  readonly payer: Address;
+  readonly amount: bigint;
+  readonly entitlement: bigint;
+  readonly viaEscapeHatch: boolean;
+}
+type Expectation = CloseExpectation | ReclaimExpectation;
+
+type LedgerEntry =
+  | { readonly state: "in-flight" }
+  | {
+      readonly state: "pending";
+      readonly hash: Hex;
+      readonly expectation: Expectation;
+    }
+  | { readonly state: "final"; readonly hash: Hex; readonly success: boolean };
+
+interface OpenerStream {
+  readonly buyer: Address;
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly deposit: bigint;
+  readonly ratePerSecond: bigint;
+  readonly claimedCumulative: bigint;
+  readonly settledCumulative: bigint;
+  readonly openedAt: bigint;
+  readonly expiresAt: bigint;
+  readonly closedAt: bigint;
+  /** 0 = Active, 1 = Closed. */
+  readonly status: number;
+  readonly reclaimed: boolean;
+}
+
+interface ResolvedStream {
+  readonly streamId: Hex;
+  readonly stream: OpenerStream;
+  readonly opener: Address;
+  readonly payer: Address;
+}
+
+type OracleProof =
+  | {
+      readonly kind: "ok";
+      readonly cumulativeAmount: bigint;
+      readonly checkpointId: bigint;
+      readonly checkedAt: bigint;
+      readonly root: Hex;
+      readonly proof: Hex[];
+    }
+  | { readonly kind: "absent"; readonly reason: string }
+  | { readonly kind: "unavailable"; readonly reason: string };
+
+class Refusal extends Error {}
+
+/** Reads the custom-error name out of a viem contract revert, if it is one. */
+function revertName(error: unknown): string | undefined {
+  if (!(error instanceof BaseError)) return undefined;
+  const reverted = error.walk(
+    (cause) => cause instanceof ContractFunctionRevertedError,
+  );
+  return reverted instanceof ContractFunctionRevertedError
+    ? reverted.data?.errorName
+    : undefined;
+}
+
+function describe(error: unknown): string {
+  if (error instanceof BaseError) return error.shortMessage;
+  return error instanceof Error ? error.message : String(error);
+}
+
+function fail(
+  status: number,
+  error: string,
+  message: string,
+  extra: Record<string, unknown> = {},
+  retryAfterSeconds?: number,
+): RefundRelayResponse {
+  return {
+    status,
+    body: { ok: false, error, message, ...extra },
+    ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }),
+  };
+}
+
+/** Fixed one-minute windows keyed by string, with a hard key cap (fail closed). */
+class MinuteWindows {
+  private readonly windows = new Map<
+    string,
+    { start: number; count: number }
+  >();
+  constructor(
+    private readonly limit: number,
+    private readonly nowMs: () => number,
+    private readonly maxKeys = 100_000,
+  ) {}
+  /** Consumes one unit for `key`; false when over the limit (or out of key space). */
+  take(key: string): boolean {
+    const now = this.nowMs();
+    const window = this.windows.get(key);
+    if (window === undefined || now - window.start >= 60_000) {
+      if (window === undefined && this.windows.size >= this.maxKeys) {
+        for (const [k, w] of this.windows) {
+          if (now - w.start >= 60_000) this.windows.delete(k);
+        }
+        if (this.windows.size >= this.maxKeys) return false;
+      }
+      this.windows.set(key, { start: now, count: 1 });
+      return true;
+    }
+    if (window.count >= this.limit) return false;
+    window.count += 1;
+    return true;
+  }
+  /** Seconds until `key`'s window resets. */
+  retryAfter(key: string): number {
+    const window = this.windows.get(key);
+    if (window === undefined) return 1;
+    return Math.max(
+      1,
+      Math.ceil((window.start + 60_000 - this.nowMs()) / 1000),
+    );
+  }
+}
+
+export class OpenerRefundRelay implements RefundRelayHandler {
+  private readonly chainId: number;
+  private readonly factory: Address;
+  private readonly escrow: Address;
+  private readonly oracleUrl: string;
+  private readonly queue: RelayerQueue;
+  private readonly receiptTimeoutMs: number;
+  private readonly oracleTimeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+  private readonly perStream: MinuteWindows;
+  private readonly global: MinuteWindows;
+  private readonly publicBaseUrl: string | undefined;
+  private readonly ledger = new Map<string, LedgerEntry>();
+  private escapeGraceSeconds: bigint | undefined;
+  private readonly generation: KnownEscrowGeneration;
+  private readonly nowMs: () => number;
+  private readonly cacheMs: number;
+  private readonly logger: Pick<Console, "error">;
+  private readonly statusCache = new Map<
+    string,
+    { readonly at: number; readonly response: RefundRelayResponse }
+  >();
+  private readonly proofCache = new Map<
+    string,
+    { readonly at: number; readonly proof: OracleProof }
+  >();
+
+  constructor(private readonly config: OpenerRefundRelayConfig) {
+    this.chainId = chainIdFromNetwork(config.network);
+    if (!isAddress(config.factoryAddress) || !isAddress(config.escrowAddress)) {
+      throw new Error("factoryAddress and escrowAddress must be EVM addresses");
+    }
+    this.factory = getAddress(config.factoryAddress);
+    this.escrow = getAddress(config.escrowAddress);
+    const generation =
+      config.escrowGeneration ?? escrowGenerationFor(this.chainId, this.escrow);
+    if (generation !== "v2" && generation !== "v3") {
+      throw new UnsupportedEscrowGenerationError(generation);
+    }
+    this.generation = generation;
+    const oracle = new URL(config.oracleUrl);
+    if (oracle.protocol !== "https:" && oracle.protocol !== "http:") {
+      throw new Error("oracleUrl must be an http(s) URL");
+    }
+    this.oracleUrl = config.oracleUrl.replace(/\/+$/, "");
+    if (config.publicBaseUrl !== undefined) {
+      // eslint-disable-next-line no-new -- validates the URL is well-formed.
+      new URL(config.publicBaseUrl);
+    }
+    this.publicBaseUrl = config.publicBaseUrl?.replace(/\/+$/, "");
+    this.queue = config.relayerQueue ?? new RelayerQueue();
+    this.receiptTimeoutMs = config.receiptTimeoutMs ?? 60_000;
+    this.oracleTimeoutMs = config.oracleTimeoutMs ?? 10_000;
+    for (const [name, value] of [
+      ["receiptTimeoutMs", this.receiptTimeoutMs],
+      ["oracleTimeoutMs", this.oracleTimeoutMs],
+    ] as const) {
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+      }
+    }
+    const perStream =
+      config.maxSubmissionsPerStreamPerMinute ??
+      DEFAULT_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE;
+    const global =
+      config.maxSubmissionsPerMinute ?? DEFAULT_REFUND_SUBMISSIONS_PER_MINUTE;
+    for (const [name, value] of [
+      ["maxSubmissionsPerStreamPerMinute", perStream],
+      ["maxSubmissionsPerMinute", global],
+    ] as const) {
+      if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+      }
+    }
+    const nowMs = config.nowMs ?? (() => Date.now());
+    this.nowMs = nowMs;
+    const cacheSeconds =
+      config.readCacheSeconds ?? DEFAULT_REFUND_READ_CACHE_SECONDS;
+    if (!Number.isInteger(cacheSeconds) || cacheSeconds < 0) {
+      throw new Error("readCacheSeconds must be a non-negative integer");
+    }
+    this.cacheMs = cacheSeconds * 1000;
+    this.logger = config.logger ?? console;
+    this.perStream = new MinuteWindows(perStream, nowMs);
+    this.global = new MinuteWindows(global, nowMs);
+    this.fetchImpl = config.fetch ?? ((...args) => fetch(...args));
+  }
+
+  /**
+   * Proves the wiring before serving: the RPC is on the configured chain and
+   * the factory settles into the configured escrow. Caches the escrow's
+   * immutable `escapeGraceSeconds`. Throws otherwise (refuse to start).
+   */
+  async init(): Promise<void> {
+    const { publicClient } = this.config;
+    const rpcChainId = await publicClient.getChainId();
+    if (rpcChainId !== this.chainId) {
+      throw new Error(
+        `refund relay: RPC chain id ${rpcChainId} does not match ${this.config.network}`,
+      );
+    }
+    const factoryEscrow = await publicClient.readContract({
+      address: this.factory,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "escrow",
+    });
+    if (getAddress(factoryEscrow) !== this.escrow) {
+      throw new Error(
+        `refund relay: factory escrow ${factoryEscrow} is not the configured escrow ${this.escrow}`,
+      );
+    }
+    this.escapeGraceSeconds = BigInt(
+      await publicClient.readContract({
+        address: this.escrow,
+        abi: streamEscrowV2Abi,
+        functionName: "escapeGraceSeconds",
+      }),
+    );
+  }
+
+  // ── GET /streams/:streamId ──────────────────────────────────────────────
+
+  async status(rawStreamId: string): Promise<RefundRelayResponse> {
+    const streamId = parseStreamId(rawStreamId);
+    if (streamId === undefined) return invalidStreamId();
+    const cached = this.fresh(this.statusCache, streamId);
+    if (cached !== undefined) return cached.response;
+    const response = await this.computeStatus(streamId);
+    // Cache definitive answers only (200 / 404), never an outage.
+    if (response.status === 200 || response.status === 404) {
+      this.remember(this.statusCache, streamId, { response });
+    }
+    return response;
+  }
+
+  private async computeStatus(
+    rawStreamId: string,
+  ): Promise<RefundRelayResponse> {
+    try {
+      const resolved = await this.resolve(rawStreamId);
+      if ("status" in resolved) return resolved;
+      const { streamId, stream, opener, payer } = resolved;
+      const grace = this.grace();
+      const [now, nonce, latestCheckedAt] = await Promise.all([
+        this.chainNow(),
+        this.readNonce(opener, payer),
+        this.readLatestCheckedAt(),
+      ]);
+      const closed = stream.status === 1;
+      const stopAt = stopTime(stream);
+      const settled = latestCheckedAt >= stopAt;
+      const fallbackAt = stopAt + grace;
+      const escapeAt = await this.escapeHatchAt(streamId, stream);
+
+      let oracle: Record<string, unknown> | null = null;
+      let oracleNote: string | undefined;
+      let reclaimable: bigint | undefined;
+      if (!stream.reclaimed) {
+        const proof = await this.fetchProof(streamId);
+        if (proof.kind === "ok") {
+          oracle = {
+            cumulativeAmount: proof.cumulativeAmount.toString(),
+            checkpointId: proof.checkpointId.toString(),
+            checkedAt: Number(proof.checkedAt),
+            root: proof.root,
+          };
+          reclaimable = await this.readReclaimable(
+            streamId,
+            proof.cumulativeAmount,
+          );
+        } else {
+          oracleNote = proof.reason;
+        }
+      }
+
+      const base = `/streams/${streamId}`;
+      let next: Record<string, unknown>;
+      if (stream.reclaimed) {
+        next = {
+          action: "none",
+          message:
+            "Already reclaimed: the unearned part of the deposit was sent to the payer. Nothing further to do.",
+        };
+      } else if (!closed && now < stream.expiresAt) {
+        next = {
+          action: "close",
+          method: "POST",
+          ...this.link(`${base}/close`),
+          body: {
+            deadline: "<the deadline you signed, unix seconds>",
+            signature: "<the payer's EIP-712 signature of typedData>",
+          },
+          typedData: jsonTypedData(
+            openerActionTypedData({
+              action: "Close",
+              opener,
+              chainId: this.chainId,
+              streamId,
+              nonce,
+              deadline: now + 900n,
+            }),
+          ),
+          message: `Stop the stream early: sign typedData with the payer key (set message.deadline to a unix time at least ${MIN_SIGNATURE_DEADLINE_HEADROOM_SECONDS} s ahead) and POST it; the relay pays the gas. Otherwise the stream ends by itself at expiresAt (${Number(stream.expiresAt)}). Either way, reclaim afterwards.`,
+        };
+      } else if (!settled && now < fallbackAt) {
+        next = {
+          action: "wait",
+          retryAt: Number(fallbackAt),
+          retryAfterSeconds: Math.min(
+            CHECKPOINT_RETRY_HINT_SECONDS,
+            Number(fallbackAt - now),
+          ),
+          message:
+            "The seller's settlement window is open: reclaim becomes possible once the oracle posts a checkpoint covering the stop time (usually within a minute), and at the latest at retryAt.",
+        };
+      } else if (oracle !== null && reclaimable !== undefined) {
+        next =
+          reclaimable > 0n
+            ? {
+                action: "reclaim",
+                method: "POST",
+                ...this.link(`${base}/reclaim`),
+                message: `POST with an empty body; the relay fetches the proof, pays the gas and the contract sends ${reclaimable.toString()} base units to the payer.`,
+              }
+            : {
+                action: "none",
+                message:
+                  "Nothing to reclaim: the verified delivery covers the whole deposit.",
+              };
+      } else if (now >= escapeAt) {
+        next = {
+          action: "reclaim-unverified",
+          method: "POST",
+          ...this.link(`${base}/reclaim-unverified`),
+          body: {
+            deadline: "<the deadline you signed, unix seconds>",
+            signature: "<the payer's EIP-712 signature of typedData>",
+          },
+          typedData: jsonTypedData(
+            openerActionTypedData({
+              action: "ReclaimUnverified",
+              opener,
+              chainId: this.chainId,
+              streamId,
+              nonce,
+              deadline: now + 900n,
+            }),
+          ),
+          message:
+            "No oracle proof is available and the escape hatch is open: the payer may sign ReclaimUnverified to recover deposit minus what the seller already claimed. This forfeits the seller's earned-but-unclaimed revenue, so it needs the payer's own signature.",
+        };
+      } else {
+        next = {
+          action: "wait",
+          retryAt: Number(escapeAt),
+          retryAfterSeconds: CHECKPOINT_RETRY_HINT_SECONDS,
+          message:
+            "No usable oracle proof yet: retry shortly. If none ever appears, the payer-signed escape hatch opens at retryAt.",
+        };
+      }
+
+      return {
+        status: 200,
+        body: {
+          streamId,
+          chainId: this.chainId,
+          escrow: this.escrow,
+          factory: this.factory,
+          opener,
+          payer,
+          operator: stream.operator,
+          serviceRef: stream.serviceRef,
+          deposit: stream.deposit.toString(),
+          ratePerSecond: stream.ratePerSecond.toString(),
+          claimedCumulative: stream.claimedCumulative.toString(),
+          openedAt: Number(stream.openedAt),
+          expiresAt: Number(stream.expiresAt),
+          closedAt: closed ? Number(stream.closedAt) : null,
+          status: closed ? "closed" : "active",
+          reclaimed: stream.reclaimed,
+          chainTime: Number(now),
+          settlement: {
+            stopAt: Number(stopAt),
+            latestCheckpointCheckedAt: Number(latestCheckedAt),
+            checkpointCoversStop: settled,
+            fallbackAt: Number(fallbackAt),
+            escapeHatchAt: Number(escapeAt),
+          },
+          oracle,
+          ...(oracleNote === undefined ? {} : { oracleNote }),
+          reclaimable:
+            reclaimable === undefined ? null : reclaimable.toString(),
+          payerNonce: nonce.toString(),
+          next,
+          refunds:
+            "There is no automatic refund. Unearned money is returned only when someone calls close/reclaim here (the relay pays the gas) or the payer calls the opener directly.",
+        },
+      };
+    } catch (error) {
+      return this.unavailable("chain read", error);
+    }
+  }
+
+  // ── POST /streams/:streamId/close ───────────────────────────────────────
+
+  async close(
+    rawStreamId: string,
+    body: unknown,
+  ): Promise<RefundRelayResponse> {
+    const streamId = parseStreamId(rawStreamId);
+    if (streamId === undefined) return invalidStreamId();
+    const signed = parseSignedBody(body);
+    if ("status" in signed) return signed;
+    const key = ledgerKey("close", streamId);
+    const early = await this.precheck(key, "close");
+    if (early !== undefined) return early;
+    try {
+      const resolved = await this.resolve(streamId);
+      if ("status" in resolved) return resolved;
+      const { stream, opener, payer } = resolved;
+      const now = await this.chainNow();
+      if (stream.status === 1) {
+        return fail(409, "already-closed", "the stream is already closed", {
+          next: this.link(`/streams/${streamId}/reclaim`),
+        });
+      }
+      if (now >= stream.expiresAt) {
+        return fail(
+          409,
+          "stream-expired",
+          "the stream has already reached expiresAt; there is nothing to close — reclaim directly",
+          { next: this.link(`/streams/${streamId}/reclaim`) },
+        );
+      }
+      const refused = await this.verifyPayerSignature(
+        "Close",
+        streamId,
+        opener,
+        payer,
+        signed,
+        now,
+      );
+      if (refused !== undefined) return refused;
+      return await this.submit(
+        key,
+        streamId,
+        {
+          address: opener,
+          functionName: "closeWithSig",
+          args: [streamId, signed.deadline, signed.signature],
+        },
+        undefined,
+        { kind: "close", streamId, opener, payer },
+      );
+    } catch (error) {
+      return this.unavailable("chain read", error);
+    }
+  }
+
+  // ── POST /streams/:streamId/reclaim ─────────────────────────────────────
+
+  async reclaim(rawStreamId: string): Promise<RefundRelayResponse> {
+    const streamId = parseStreamId(rawStreamId);
+    if (streamId === undefined) return invalidStreamId();
+    const key = ledgerKey("reclaim", streamId);
+    const early = await this.precheck(key, "reclaim");
+    if (early !== undefined) return early;
+    try {
+      const resolved = await this.resolve(streamId);
+      if ("status" in resolved) return resolved;
+      const { stream, opener, payer } = resolved;
+      if (stream.reclaimed) return alreadyReclaimed();
+      const now = await this.chainNow();
+      if (stream.status !== 1 && now < stream.expiresAt) {
+        return fail(
+          409,
+          "not-reclaimable-yet",
+          "the stream is still running: close it first (POST /streams/:streamId/close with the payer's signature) or wait until expiresAt",
+          {
+            retryAt: Number(stream.expiresAt),
+            next: this.link(`/streams/${streamId}/close`),
+          },
+          Number(stream.expiresAt - now),
+        );
+      }
+      const stopAt = stopTime(stream);
+      const fallbackAt = stopAt + this.grace();
+      const latestCheckedAt = await this.readLatestCheckedAt();
+      if (latestCheckedAt < stopAt && now < fallbackAt) {
+        return fail(
+          409,
+          "settlement-window-open",
+          "the seller's settlement window is open: the reclaim needs a checkpoint covering the stop time (the oracle usually posts one within a minute); it is possible at the latest at retryAt",
+          { retryAt: Number(fallbackAt), stopAt: Number(stopAt) },
+          Math.min(CHECKPOINT_RETRY_HINT_SECONDS, Number(fallbackAt - now)),
+        );
+      }
+      const proof = await this.fetchProof(streamId);
+      if (proof.kind === "unavailable") {
+        return fail(503, "oracle-unavailable", proof.reason, {}, 30);
+      }
+      if (proof.kind === "absent") {
+        return fail(
+          409,
+          "proof-unavailable",
+          `${proof.reason}; retry shortly. If no proof ever appears, the payer-signed escape hatch (POST /streams/:streamId/reclaim-unverified) opens at escapeHatchAt.`,
+          {
+            escapeHatchAt: Number(await this.escapeHatchAt(streamId, stream)),
+          },
+          CHECKPOINT_RETRY_HINT_SECONDS,
+        );
+      }
+      const amount = await this.readReclaimable(
+        streamId,
+        proof.cumulativeAmount,
+      );
+      if (amount === 0n) {
+        return fail(
+          409,
+          "nothing-to-reclaim",
+          "the verified delivery covers the whole deposit; there is nothing to refund",
+        );
+      }
+      return await this.submit(
+        key,
+        streamId,
+        {
+          address: opener,
+          functionName: "reclaim",
+          args: [streamId, proof.cumulativeAmount, proof.proof],
+        },
+        amount,
+        {
+          kind: "reclaim",
+          action: "reclaim",
+          streamId,
+          opener,
+          payer,
+          amount,
+          entitlement: stream.deposit - amount,
+          viaEscapeHatch: false,
+        },
+      );
+    } catch (error) {
+      return this.unavailable("chain read", error);
+    }
+  }
+
+  // ── POST /streams/:streamId/reclaim-unverified ──────────────────────────
+
+  async reclaimUnverified(
+    rawStreamId: string,
+    body: unknown,
+  ): Promise<RefundRelayResponse> {
+    const streamId = parseStreamId(rawStreamId);
+    if (streamId === undefined) return invalidStreamId();
+    const signed = parseSignedBody(body);
+    if ("status" in signed) return signed;
+    const key = ledgerKey("reclaim", streamId);
+    const early = await this.precheck(key, "reclaim");
+    if (early !== undefined) return early;
+    try {
+      const resolved = await this.resolve(streamId);
+      if ("status" in resolved) return resolved;
+      const { stream, opener, payer } = resolved;
+      if (stream.reclaimed) return alreadyReclaimed();
+      const now = await this.chainNow();
+      const escapeAt = await this.escapeHatchAt(streamId, stream);
+      if (now < escapeAt) {
+        return fail(
+          409,
+          "escape-hatch-not-ready",
+          this.generation === "v2"
+            ? "the no-proof escape hatch opens only at expiresAt + escapeGraceSeconds; use the proof-based reclaim before then"
+            : "the no-proof escape hatch opens only at min(expiresAt, closedAt) + escapeGraceSeconds; use the proof-based reclaim before then",
+          {
+            retryAt: Number(escapeAt),
+            next: this.link(`/streams/${streamId}/reclaim`),
+          },
+          Number(escapeAt - now),
+        );
+      }
+      const amount = stream.deposit - stream.claimedCumulative;
+      if (amount <= 0n) {
+        return fail(
+          409,
+          "nothing-to-reclaim",
+          "the seller already claimed the whole deposit; there is nothing to refund",
+        );
+      }
+      const refused = await this.verifyPayerSignature(
+        "ReclaimUnverified",
+        streamId,
+        opener,
+        payer,
+        signed,
+        now,
+      );
+      if (refused !== undefined) return refused;
+      return await this.submit(
+        key,
+        streamId,
+        {
+          address: opener,
+          functionName: "reclaimUnverifiedWithSig",
+          args: [streamId, signed.deadline, signed.signature],
+        },
+        amount,
+        {
+          kind: "reclaim",
+          action: "reclaim-unverified",
+          streamId,
+          opener,
+          payer,
+          amount,
+          entitlement: stream.claimedCumulative,
+          viaEscapeHatch: true,
+        },
+      );
+    } catch (error) {
+      return this.unavailable("chain read", error);
+    }
+  }
+
+  // ── internals ────────────────────────────────────────────────────────────
+
+  private fresh<T extends { readonly at: number }>(
+    cache: Map<string, T>,
+    streamId: string,
+  ): T | undefined {
+    if (this.cacheMs === 0) return undefined;
+    const entry = cache.get(streamId.toLowerCase());
+    if (entry === undefined) return undefined;
+    if (this.nowMs() - entry.at >= this.cacheMs) {
+      cache.delete(streamId.toLowerCase());
+      return undefined;
+    }
+    return entry;
+  }
+
+  private remember<T extends { readonly at: number }>(
+    cache: Map<string, T>,
+    streamId: string,
+    value: Omit<T, "at">,
+  ): void {
+    if (this.cacheMs === 0) return;
+    if (cache.size >= MAX_CACHED_STREAMS) {
+      const now = this.nowMs();
+      for (const [key, entry] of cache) {
+        if (now - entry.at >= this.cacheMs) cache.delete(key);
+      }
+      if (cache.size >= MAX_CACHED_STREAMS) cache.clear();
+    }
+    cache.set(streamId.toLowerCase(), { ...value, at: this.nowMs() } as T);
+  }
+
+  private forget(streamId: string): void {
+    this.statusCache.delete(streamId.toLowerCase());
+    this.proofCache.delete(streamId.toLowerCase());
+  }
+
+  /** Logs a failure server-side; clients only ever get a generic code. */
+  private log(context: string, error: unknown): void {
+    this.logger.error(
+      `[metrik-refund-relay] ${context}: ${redact(describe(error))}`,
+    );
+  }
+
+  private logged(reason: string, error: unknown): string {
+    this.log(reason, error);
+    return reason;
+  }
+
+  private unavailable(context: string, error: unknown): RefundRelayResponse {
+    this.log(context, error);
+    return fail(
+      503,
+      "chain-unavailable",
+      "the chain could not be read right now; retry shortly",
+      {},
+      10,
+    );
+  }
+
+  /** When the no-proof escape hatch opens for this stream, per generation. */
+  private async escapeHatchAt(
+    streamId: Hex,
+    stream: { readonly expiresAt: bigint; readonly closedAt: bigint },
+  ): Promise<bigint> {
+    return await readEscapeHatchReadyAt({
+      generation: this.generation,
+      reader: this.config.publicClient as unknown as EscapeHatchReader,
+      escrow: this.escrow,
+      streamId,
+      stream,
+      graceSeconds: this.grace(),
+    });
+  }
+
+  private grace(): bigint {
+    if (this.escapeGraceSeconds === undefined) {
+      throw new Error("refund relay not initialized");
+    }
+    return this.escapeGraceSeconds;
+  }
+
+  private link(path: string): { readonly path: string; readonly url?: string } {
+    return this.publicBaseUrl === undefined
+      ? { path }
+      : { path, url: `${this.publicBaseUrl}${path}` };
+  }
+
+  /**
+   * Ledger state that answers a request before any chain read: a delivered
+   * success, a blocked (unknown-outcome) tx, a concurrent in-flight request,
+   * or a pending tx to reconcile (never re-broadcast).
+   */
+  private async precheck(
+    key: string,
+    kind: LedgerKind,
+  ): Promise<RefundRelayResponse | undefined> {
+    const entry = this.ledger.get(key);
+    if (entry === undefined) return undefined;
+    if (entry.state === "in-flight") return inProgress();
+    if (entry.state === "final") {
+      if (entry.success) {
+        return kind === "close"
+          ? fail(
+              409,
+              "already-closed",
+              "this stream was already closed through this relay",
+              {
+                transaction: entry.hash,
+              },
+            )
+          : alreadyReclaimed(entry.hash);
+      }
+      return fail(
+        409,
+        "blocked",
+        "an earlier relayed transaction for this stream was mined with an unexpected outcome; inspect it on-chain before retrying directly with the opener",
+        { transaction: entry.hash },
+      );
+    }
+    // pending: reconcile the SAME transaction.
+    this.ledger.set(key, { state: "in-flight" });
+    return this.awaitOutcome(key, entry.hash, entry.expectation);
+  }
+
+  /**
+   * Claims the one submission slot for `key` (synchronously), then simulates
+   * and broadcasts through the shared relayer queue. `expectedResult`, when
+   * set, is the exact non-zero amount the simulation must return.
+   */
+  private async submit(
+    key: string,
+    streamId: Hex,
+    call: {
+      readonly address: Address;
+      readonly functionName:
+        | "closeWithSig"
+        | "reclaim"
+        | "reclaimUnverifiedWithSig";
+      readonly args: readonly unknown[];
+    },
+    expectedResult: bigint | undefined,
+    expectation: Expectation,
+  ): Promise<RefundRelayResponse> {
+    // Synchronous from here to the ledger write: two concurrent requests for
+    // the same stream and action can never both reach the relayer.
+    const current = this.ledger.get(key);
+    if (current !== undefined) {
+      return current.state === "in-flight"
+        ? inProgress()
+        : ((await this.precheck(key, expectation.kind)) ?? inProgress());
+    }
+    if (this.ledger.size >= MAX_LEDGER_ENTRIES) {
+      return fail(
+        503,
+        "relay-capacity",
+        "the relay ledger is full; retry later",
+        {},
+        60,
+      );
+    }
+    if (!this.global.take("*")) {
+      return fail(
+        429,
+        "rate-limited",
+        "the relay's submission budget is exhausted for this minute",
+        {},
+        this.global.retryAfter("*"),
+      );
+    }
+    if (!this.perStream.take(streamId)) {
+      return fail(
+        429,
+        "rate-limited",
+        "too many relayed submissions for this stream in the last minute",
+        {},
+        this.perStream.retryAfter(streamId),
+      );
+    }
+    this.ledger.set(key, { state: "in-flight" });
+
+    const { publicClient, walletClient } = this.config;
+    let phase: "simulate" | "write" = "simulate";
+    let hash: Hex;
+    try {
+      hash = await this.queue.run(async () => {
+        const { result, request } = await publicClient.simulateContract({
+          account: walletClient.account,
+          address: call.address,
+          abi: x402StreamOpenerAbi,
+          functionName: call.functionName,
+          args: call.args,
+        } as unknown as Parameters<typeof publicClient.simulateContract>[0]);
+        if (expectedResult !== undefined) {
+          if (
+            typeof result !== "bigint" ||
+            result !== expectedResult ||
+            result === 0n
+          ) {
+            throw new Refusal(
+              `simulation returned ${String(result)}, expected ${expectedResult}`,
+            );
+          }
+        }
+        phase = "write";
+        return walletClient.writeContract({
+          ...(request as object),
+          chain: walletClient.chain ?? null,
+        } as Parameters<typeof walletClient.writeContract>[0]);
+      });
+    } catch (error) {
+      this.ledger.delete(key);
+      this.log(`${call.functionName} ${phase} for ${streamId} failed`, error);
+      if (phase === "simulate") {
+        return fail(
+          409,
+          "simulation-failed",
+          `the transaction would not succeed right now${
+            error instanceof Refusal
+              ? ""
+              : revertName(error) === undefined
+                ? ""
+                : `: ${revertName(error)}`
+          }`,
+        );
+      }
+      return fail(
+        502,
+        "submission-failed",
+        "the transaction could not be submitted; retry shortly",
+        {},
+        10,
+      );
+    }
+    return this.awaitOutcome(key, hash, expectation);
+  }
+
+  private async awaitOutcome(
+    key: string,
+    hash: Hex,
+    expectation: Expectation,
+  ): Promise<RefundRelayResponse> {
+    let receipt;
+    try {
+      receipt = await this.config.publicClient.waitForTransactionReceipt({
+        hash,
+        timeout: this.receiptTimeoutMs,
+      });
+    } catch {
+      // Broadcast, not yet mined: never a success without a receipt. The next
+      // request for this stream reconciles THIS hash instead of re-sending.
+      this.ledger.set(key, { state: "pending", hash, expectation });
+      return fail(
+        202,
+        "pending",
+        "the transaction was sent but is not mined yet; repeat the same request to see the outcome (it is never sent twice)",
+        { transaction: hash },
+        10,
+      );
+    }
+    this.forget(expectation.streamId);
+    if (receipt.status !== "success") {
+      // A reverted call changed nothing on-chain; the slot is free again.
+      this.ledger.delete(key);
+      return fail(
+        502,
+        "transaction-reverted",
+        "the relayed transaction reverted on-chain; nothing changed",
+        {
+          transaction: hash,
+        },
+      );
+    }
+    if (!receiptMatches(receipt.logs, this.escrow, expectation)) {
+      this.ledger.set(key, { state: "final", hash, success: false });
+      return fail(
+        502,
+        "unexpected-receipt",
+        "the mined receipt does not show the expected outcome for this stream",
+        { transaction: hash },
+      );
+    }
+    this.ledger.set(key, { state: "final", hash, success: true });
+    if (expectation.kind === "close") {
+      return {
+        status: 200,
+        body: {
+          ok: true,
+          action: "close",
+          streamId: expectation.streamId,
+          opener: expectation.opener,
+          payer: expectation.payer,
+          transaction: hash,
+          message:
+            "Closed. The seller keeps only verified delivery up to now. Reclaim the rest once a checkpoint covering the close is posted (usually within a minute).",
+          next: this.link(`/streams/${expectation.streamId}/reclaim`),
+        },
+      };
+    }
+    return {
+      status: 200,
+      body: {
+        ok: true,
+        action: expectation.action,
+        streamId: expectation.streamId,
+        opener: expectation.opener,
+        payer: expectation.payer,
+        amount: expectation.amount.toString(),
+        entitlement: expectation.entitlement.toString(),
+        transaction: hash,
+        message: `Reclaimed: ${expectation.amount.toString()} base units were sent to the payer.`,
+      },
+    };
+  }
+
+  /** Streams whose escrow buyer is an opener of the configured factory, or a 404. */
+  private async resolve(
+    rawStreamId: string,
+  ): Promise<ResolvedStream | RefundRelayResponse> {
+    const streamId = parseStreamId(rawStreamId);
+    if (streamId === undefined) return invalidStreamId();
+    const { publicClient } = this.config;
+    let stream: OpenerStream;
+    try {
+      stream = (await publicClient.readContract({
+        address: this.escrow,
+        abi: streamEscrowV2Abi,
+        functionName: "getStream",
+        args: [streamId],
+      })) as unknown as OpenerStream;
+    } catch (error) {
+      if (revertName(error) === "UnknownStream") return notFound();
+      throw error;
+    }
+    if (!isAddress(stream.buyer)) return notFound();
+    const buyer = getAddress(stream.buyer);
+    const isOpener = await publicClient.readContract({
+      address: this.factory,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "isOpener",
+      args: [buyer],
+    });
+    if (isOpener !== true) return notFound();
+    const payer = await publicClient.readContract({
+      address: buyer,
+      abi: x402StreamOpenerAbi,
+      functionName: "payerOf",
+      args: [streamId],
+    });
+    if (!isAddress(payer) || /^0x0{40}$/i.test(payer)) return notFound();
+    return {
+      streamId,
+      opener: buyer,
+      payer: getAddress(payer),
+      stream: {
+        buyer,
+        operator: getAddress(stream.operator),
+        serviceRef: stream.serviceRef,
+        deposit: BigInt(stream.deposit),
+        ratePerSecond: BigInt(stream.ratePerSecond),
+        claimedCumulative: BigInt(stream.claimedCumulative),
+        settledCumulative: BigInt(stream.settledCumulative),
+        openedAt: BigInt(stream.openedAt),
+        expiresAt: BigInt(stream.expiresAt),
+        closedAt: BigInt(stream.closedAt),
+        status: Number(stream.status),
+        reclaimed: stream.reclaimed === true,
+      },
+    };
+  }
+
+  /** Off-chain check of a payer-signed opener action. `undefined` = valid. */
+  private async verifyPayerSignature(
+    action: OpenerSignedAction,
+    streamId: Hex,
+    opener: Address,
+    payer: Address,
+    signed: SignedBody,
+    now: bigint,
+  ): Promise<RefundRelayResponse | undefined> {
+    if (signed.deadline < now + MIN_SIGNATURE_DEADLINE_HEADROOM_SECONDS) {
+      return fail(
+        403,
+        "signature-expired",
+        `the signed deadline must be at least ${MIN_SIGNATURE_DEADLINE_HEADROOM_SECONDS} s after the current chain time (${Number(now)}) so the transaction can be mined in time`,
+        { chainTime: Number(now) },
+      );
+    }
+    if (isErc6492Signature(signed.signature)) {
+      return fail(
+        403,
+        "invalid-signature",
+        "ERC-6492 (counterfactual wallet) signatures are not accepted by the opener",
+      );
+    }
+    const { publicClient } = this.config;
+    const [nonce, domain] = await Promise.all([
+      this.readNonce(opener, payer),
+      publicClient.readContract({
+        address: opener,
+        abi: x402StreamOpenerAbi,
+        functionName: "eip712Domain",
+      }),
+    ]);
+    if (signed.nonce !== undefined && signed.nonce !== nonce) {
+      return fail(
+        409,
+        "nonce-mismatch",
+        `the payer's current opener nonce is ${nonce}; sign again over it`,
+        { payerNonce: nonce.toString() },
+      );
+    }
+    const [, name, version, chainId, verifyingContract] = domain as readonly [
+      Hex,
+      string,
+      string,
+      bigint,
+      Address,
+      Hex,
+      readonly bigint[],
+    ];
+    if (
+      name !== OPENER_EIP712_NAME ||
+      version !== OPENER_EIP712_VERSION ||
+      BigInt(chainId) !== BigInt(this.chainId) ||
+      getAddress(verifyingContract) !== opener
+    ) {
+      // Fail closed: never verify against a domain the opener does not report.
+      return fail(
+        503,
+        "opener-domain-mismatch",
+        "the opener's EIP-712 domain is not the expected one",
+      );
+    }
+    let valid = false;
+    try {
+      valid = await publicClient.verifyTypedData({
+        address: payer,
+        ...openerActionTypedData({
+          action,
+          opener,
+          chainId: this.chainId,
+          streamId,
+          nonce,
+          deadline: signed.deadline,
+        }),
+        signature: signed.signature,
+      } as Parameters<typeof publicClient.verifyTypedData>[0]);
+    } catch {
+      valid = false;
+    }
+    if (!valid) {
+      return fail(
+        403,
+        "invalid-signature",
+        `the signature is not the payer's EIP-712 ${action}(streamId, nonce ${nonce}, deadline) for this opener`,
+        { payerNonce: nonce.toString() },
+      );
+    }
+    return undefined;
+  }
+
+  private async chainNow(): Promise<bigint> {
+    const block = await this.config.publicClient.getBlock({
+      blockTag: "latest",
+    });
+    return BigInt(block.timestamp);
+  }
+
+  private async readNonce(opener: Address, payer: Address): Promise<bigint> {
+    return BigInt(
+      await this.config.publicClient.readContract({
+        address: opener,
+        abi: x402StreamOpenerAbi,
+        functionName: "nonces",
+        args: [payer],
+      }),
+    );
+  }
+
+  private async readLatestCheckedAt(): Promise<bigint> {
+    return BigInt(
+      await this.config.publicClient.readContract({
+        address: this.escrow,
+        abi: streamEscrowV2Abi,
+        functionName: "latestCheckpointCheckedAt",
+      }),
+    );
+  }
+
+  private async readReclaimable(
+    streamId: Hex,
+    cumulativeAmount: bigint,
+  ): Promise<bigint> {
+    return BigInt(
+      await this.config.publicClient.readContract({
+        address: this.escrow,
+        abi: streamEscrowV2Abi,
+        functionName: "reclaimableFor",
+        args: [streamId, cumulativeAmount],
+      }),
+    );
+  }
+
+  /**
+   * The oracle's proof for `streamId`, accepted ONLY if it is well-formed, is
+   * for this stream, verifies under the escrow's double-hashed leaf, and its
+   * root is the escrow's on-chain `latestCheckpointRoot` (the only root the
+   * buyer's reclaim settles against).
+   */
+  private async fetchProof(streamId: Hex): Promise<OracleProof> {
+    const cached = this.fresh(this.proofCache, streamId);
+    if (cached !== undefined) return cached.proof;
+    const proof = await this.loadProof(streamId);
+    if (proof.kind !== "unavailable") {
+      this.remember(this.proofCache, streamId, { proof });
+    }
+    return proof;
+  }
+
+  private async loadProof(streamId: Hex): Promise<OracleProof> {
+    const url = `${this.oracleUrl}/checkpoint/proof?streamId=${streamId}`;
+    let response: Response;
+    try {
+      response = await this.fetchImpl(url, {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(this.oracleTimeoutMs),
+      });
+    } catch (error) {
+      return {
+        kind: "unavailable",
+        reason: this.logged("oracle unreachable", error),
+      };
+    }
+    if (response.status === 404 || response.status === 503) {
+      await response.body?.cancel().catch(() => undefined);
+      return {
+        kind: "absent",
+        reason:
+          response.status === 404
+            ? "the oracle's latest checkpoint does not include this stream yet"
+            : "the oracle has not posted a checkpoint yet",
+      };
+    }
+    if (response.status !== 200) {
+      await response.body?.cancel().catch(() => undefined);
+      return {
+        kind: "unavailable",
+        reason: `oracle answered HTTP ${response.status}`,
+      };
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(
+        await readLimited(response, MAX_ORACLE_RESPONSE_BYTES),
+      );
+    } catch (error) {
+      return {
+        kind: "unavailable",
+        reason: this.logged("oracle response unreadable", error),
+      };
+    }
+    const record = parsed as Record<string, unknown>;
+    if (
+      typeof record !== "object" ||
+      record === null ||
+      typeof record.streamId !== "string" ||
+      record.streamId.toLowerCase() !== streamId.toLowerCase() ||
+      typeof record.cumulativeAmount !== "string" ||
+      !UINT_PATTERN.test(record.cumulativeAmount) ||
+      typeof record.checkpointId !== "string" ||
+      !UINT_PATTERN.test(record.checkpointId) ||
+      typeof record.checkedAt !== "string" ||
+      !UINT_PATTERN.test(record.checkedAt) ||
+      typeof record.root !== "string" ||
+      !STREAM_ID_PATTERN.test(record.root) ||
+      !Array.isArray(record.proof) ||
+      record.proof.length > MAX_PROOF_LENGTH ||
+      !record.proof.every(
+        (node) => typeof node === "string" && STREAM_ID_PATTERN.test(node),
+      )
+    ) {
+      return { kind: "absent", reason: "the oracle's proof is malformed" };
+    }
+    const cumulativeAmount = BigInt(record.cumulativeAmount);
+    if (cumulativeAmount > maxUint256) {
+      return { kind: "absent", reason: "the oracle's proof is malformed" };
+    }
+    const root = (record.root as string).toLowerCase() as Hex;
+    const proof = (record.proof as string[]).map(
+      (node) => node.toLowerCase() as Hex,
+    );
+    if (
+      processMerkleProof(checkpointLeaf(streamId, cumulativeAmount), proof) !==
+      root
+    ) {
+      return { kind: "absent", reason: "the oracle's proof does not verify" };
+    }
+    const onchainRoot = (
+      await this.config.publicClient.readContract({
+        address: this.escrow,
+        abi: streamEscrowV2Abi,
+        functionName: "latestCheckpointRoot",
+      })
+    ).toLowerCase();
+    if (onchainRoot !== root) {
+      return {
+        kind: "absent",
+        reason:
+          "the oracle's proof is not against the escrow's latest on-chain checkpoint",
+      };
+    }
+    return {
+      kind: "ok",
+      cumulativeAmount,
+      checkpointId: BigInt(record.checkpointId as string),
+      checkedAt: BigInt(record.checkedAt as string),
+      root,
+      proof,
+    };
+  }
+}
+
+/** Effective delivery-stop time, exactly as `StreamEscrowV2.reclaim` computes it. */
+function stopTime(stream: OpenerStream): bigint {
+  return stream.status === 1 && stream.closedAt < stream.expiresAt
+    ? stream.closedAt
+    : stream.expiresAt;
+}
+
+/**
+ * The mined receipt shows exactly the expected outcome: for a close, the
+ * escrow's `StreamClosed` and the opener's `StreamCloseRequested` for this
+ * payer; for a reclaim, the escrow's `BuyerReclaimed` (buyer = opener) and the
+ * opener's `ReclaimForwarded` to the payer, both for exactly the simulated
+ * amount.
+ */
+function receiptMatches(
+  logs: readonly Log[],
+  escrow: Address,
+  expectation: Expectation,
+): boolean {
+  let escrowSide = false;
+  let openerSide = false;
+  const id = expectation.streamId.toLowerCase();
+  for (const log of logs) {
+    const address = getAddress(log.address);
+    try {
+      if (address === escrow) {
+        const decoded = decodeEventLog({
+          abi: streamEscrowV2Abi,
+          data: log.data,
+          topics: log.topics,
+        });
+        const args = decoded.args as unknown as Record<string, unknown>;
+        if (String(args.streamId).toLowerCase() !== id) continue;
+        if (
+          expectation.kind === "close" &&
+          decoded.eventName === "StreamClosed"
+        ) {
+          escrowSide = true;
+        }
+        if (
+          expectation.kind === "reclaim" &&
+          decoded.eventName === "BuyerReclaimed" &&
+          getAddress(args.buyer as Address) === expectation.opener &&
+          args.amount === expectation.amount &&
+          args.settledCumulative === expectation.entitlement &&
+          args.viaEscapeHatch === expectation.viaEscapeHatch
+        ) {
+          escrowSide = true;
+        }
+      } else if (address === expectation.opener) {
+        const decoded = decodeEventLog({
+          abi: x402StreamOpenerAbi,
+          data: log.data,
+          topics: log.topics,
+        });
+        const args = decoded.args as unknown as Record<string, unknown>;
+        if (String(args.streamId).toLowerCase() !== id) continue;
+        if (
+          expectation.kind === "close" &&
+          decoded.eventName === "StreamCloseRequested" &&
+          getAddress(args.payer as Address) === expectation.payer
+        ) {
+          openerSide = true;
+        }
+        if (
+          expectation.kind === "reclaim" &&
+          decoded.eventName === "ReclaimForwarded" &&
+          getAddress(args.payer as Address) === expectation.payer &&
+          args.amount === expectation.amount &&
+          args.viaEscapeHatch === expectation.viaEscapeHatch
+        ) {
+          openerSide = true;
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return escrowSide && openerSide;
+}
+
+interface SignedBody {
+  readonly deadline: bigint;
+  readonly signature: Hex;
+  readonly nonce?: bigint;
+}
+
+function parseSignedBody(body: unknown): SignedBody | RefundRelayResponse {
+  const bad = (message: string) => fail(400, "invalid-request", message);
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    return bad("expected a JSON object {deadline, signature}");
+  }
+  const record = body as Record<string, unknown>;
+  for (const key of Object.keys(record)) {
+    if (!["deadline", "signature", "nonce"].includes(key)) {
+      return bad(`unknown field ${key}`);
+    }
+  }
+  const { deadline, signature, nonce } = record;
+  if (typeof deadline !== "string" || !UINT_PATTERN.test(deadline)) {
+    return bad("deadline must be a base-10 unix-seconds string");
+  }
+  const parsedDeadline = BigInt(deadline);
+  if (parsedDeadline > maxUint256) return bad("deadline exceeds uint256");
+  if (
+    typeof signature !== "string" ||
+    !isHex(signature, { strict: true }) ||
+    signature.length % 2 !== 0 ||
+    signature.length <= 2 ||
+    (signature.length - 2) / 2 > MAX_SIGNATURE_BYTES
+  ) {
+    return bad(
+      `signature must be 0x-hex bytes (at most ${MAX_SIGNATURE_BYTES})`,
+    );
+  }
+  let parsedNonce: bigint | undefined;
+  if (nonce !== undefined) {
+    if (typeof nonce !== "string" || !UINT_PATTERN.test(nonce)) {
+      return bad("nonce, when given, must be a base-10 integer string");
+    }
+    parsedNonce = BigInt(nonce);
+  }
+  return {
+    deadline: parsedDeadline,
+    signature: signature as Hex,
+    ...(parsedNonce === undefined ? {} : { nonce: parsedNonce }),
+  };
+}
+
+function parseStreamId(raw: string): Hex | undefined {
+  return STREAM_ID_PATTERN.test(raw) ? (raw.toLowerCase() as Hex) : undefined;
+}
+
+function ledgerKey(kind: LedgerKind, streamId: Hex): string {
+  return `${kind}:${streamId.toLowerCase()}`;
+}
+
+function invalidStreamId(): RefundRelayResponse {
+  return fail(
+    400,
+    "invalid-stream-id",
+    "streamId must be a 32-byte 0x-hex value",
+  );
+}
+
+function notFound(): RefundRelayResponse {
+  return fail(
+    404,
+    "not-found",
+    "no stream opened through this facilitator's X402StreamOpenerFactory has that id",
+  );
+}
+
+function inProgress(): RefundRelayResponse {
+  return fail(
+    409,
+    "in-progress",
+    "a relayed transaction for this stream is in flight; retry shortly",
+    {},
+    5,
+  );
+}
+
+function alreadyReclaimed(transaction?: Hex): RefundRelayResponse {
+  return fail(
+    409,
+    "already-reclaimed",
+    "this stream was already reclaimed; the escrow allows exactly one reclaim",
+    transaction === undefined ? {} : { transaction },
+  );
+}
+
+/** JSON-safe typed data: bigints as decimal strings (chainId stays a number). */
+function jsonTypedData(
+  typed: ReturnType<typeof openerActionTypedData>,
+): Record<string, unknown> {
+  return {
+    domain: typed.domain,
+    types: {
+      EIP712Domain: [
+        { name: "name", type: "string" },
+        { name: "version", type: "string" },
+        { name: "chainId", type: "uint256" },
+        { name: "verifyingContract", type: "address" },
+      ],
+      ...typed.types,
+    },
+    primaryType: typed.primaryType,
+    message: {
+      streamId: typed.message.streamId,
+      nonce: typed.message.nonce.toString(),
+      deadline: typed.message.deadline.toString(),
+    },
+  };
+}
+
+async function readLimited(response: Response, limit: number): Promise<string> {
+  if (response.body === null) return "";
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel().catch(() => undefined);
+      throw new Error("response too large");
+    }
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** Strips URL paths and query strings (RPC URLs often carry an API key) from a log line. */
+function redact(text: string): string {
+  return text.replace(/(https?:\/\/[^\s/?#]+)[^\s]*/g, "$1/…");
+}