@absol-labs/agent 0.12.0-rc.2 → 0.12.0-rc.3

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

@@ -26,6 +26,7 @@ import {
 } from "viem";
 
 import { x402StreamOpenerAbi, x402StreamOpenerFactoryAbi } from "./abi.js";
+import { StreamBlockFloors } from "./block-floors.js";
 import { RelayerQueue } from "./relayer-queue.js";
 import { chainIdFromNetwork, type OpenerKind } from "./terms.js";
 import {
@@ -247,6 +248,50 @@ export interface OpenerRefundRelayConfig {
    * `escrow.generation` for (chain, escrow), else `v2`.
    */
   readonly escrowGeneration?: string;
+  /**
+   * Per-stream block floors shared with the opener scheme: the block of every
+   * mined settlement (and of every close/reclaim this relay mines). The relay
+   * never answers about a stream from a block below its floor, so a lagging
+   * RPC node cannot make a just-opened stream look unknown or a just-closed
+   * one look active. Default: a private instance (this relay's own txs only).
+   */
+  readonly streamFloors?: StreamBlockFloors;
+  /**
+   * How long one request may wait for the RPC to reach a stream's floor
+   * block, ms, before answering `503 chain-lagging` (never a wrong `404`).
+   * Default {@link DEFAULT_REFUND_LAG_TOLERANCE_MS}.
+   */
+  readonly lagToleranceMs?: number;
+  /** Poll interval while waiting for the RPC to catch up, ms. Default 1000. */
+  readonly lagPollMs?: number;
+  /** Injectable sleep, for tests. */
+  readonly sleep?: (ms: number) => Promise<void>;
+}
+
+/** Default bound on waiting for a lagging RPC inside one relay request. */
+export const DEFAULT_REFUND_LAG_TOLERANCE_MS = 8_000;
+const DEFAULT_LAG_POLL_MS = 1_000;
+
+/**
+ * One consistent view of the chain for one relay answer: every read is pinned
+ * to `number` (when the RPC reports it), so a load-balanced RPC cannot mix
+ * state from two heights into one answer.
+ */
+interface ChainView {
+  readonly number: bigint | undefined;
+  readonly timestamp: bigint;
+  /** Shared poll budget of this answer (snapshot waits + pinned-read retries). */
+  readonly budget: { left: number };
+}
+
+/** The RPC did not reach the stream's floor block within the tolerance. */
+class ChainLagging extends Error {
+  constructor(
+    readonly floor: bigint,
+    readonly seen: bigint | undefined,
+  ) {
+    super(`RPC is at block ${String(seen)}, below the stream's floor ${floor}`);
+  }
 }
 
 /** Default reuse window for a stream's status and oracle proof. */
@@ -432,8 +477,17 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   private readonly logger: Pick<Console, "error">;
   private readonly statusCache = new Map<
     string,
-    { readonly at: number; readonly response: RefundRelayResponse }
+    {
+      readonly at: number;
+      readonly response: RefundRelayResponse;
+      /** The block the answer was computed at, when known. */
+      readonly block: bigint | undefined;
+    }
   >();
+  private readonly floors: StreamBlockFloors;
+  private readonly lagToleranceMs: number;
+  private readonly lagPollMs: number;
+  private readonly sleep: (ms: number) => Promise<void>;
   private readonly proofCache = new Map<
     string,
     { readonly at: number; readonly proof: OracleProof }
@@ -511,6 +565,21 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     this.perStream = new MinuteWindows(perStream, nowMs);
     this.global = new MinuteWindows(global, nowMs);
     this.fetchImpl = config.fetch ?? ((...args) => fetch(...args));
+    this.floors = config.streamFloors ?? new StreamBlockFloors();
+    this.lagToleranceMs =
+      config.lagToleranceMs ?? DEFAULT_REFUND_LAG_TOLERANCE_MS;
+    this.lagPollMs = config.lagPollMs ?? DEFAULT_LAG_POLL_MS;
+    for (const [name, value] of [
+      ["lagToleranceMs", this.lagToleranceMs],
+      ["lagPollMs", this.lagPollMs],
+    ] as const) {
+      if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${name} must be a non-negative integer`);
+      }
+    }
+    this.sleep =
+      config.sleep ??
+      ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   }
 
   /**
@@ -563,199 +632,242 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     const streamId = parseStreamId(rawStreamId);
     if (streamId === undefined) return invalidStreamId();
     if (isNoStreamId(streamId)) return nothingToRefund(404);
+    const floor = this.floors.get(streamId);
     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.
+    // A cached answer computed below the stream's floor (a tx for it was mined
+    // since) is stale by construction: never serve it.
+    if (
+      cached !== undefined &&
+      (floor === undefined ||
+        (cached.block !== undefined && cached.block >= floor))
+    ) {
+      return cached.response;
+    }
+    const { response, block } = await this.computeStatus(streamId);
+    // Cache definitive answers only (200 / 404), never an outage or a lag.
     if (response.status === 200 || response.status === 404) {
-      this.remember(this.statusCache, streamId, { response });
+      this.remember(this.statusCache, streamId, { response, block });
     }
     return response;
   }
 
-  private async computeStatus(
-    rawStreamId: string,
-  ): Promise<RefundRelayResponse> {
+  private async computeStatus(streamId: Hex): Promise<{
+    readonly response: RefundRelayResponse;
+    readonly block: bigint | undefined;
+  }> {
     try {
-      const resolved = await this.resolve(rawStreamId);
-      if ("status" in resolved) return resolved;
-      const { streamId, stream, opener, payer, kind, factory } = resolved;
-      const grace = this.grace();
-      const [now, nonce, latestCheckedAt, upfrontTerms] = await Promise.all([
-        this.chainNow(),
-        this.readNonce(opener, payer),
-        this.readLatestCheckedAt(),
-        kind === "upfront"
-          ? this.readUpfrontTerms(opener)
-          : Promise.resolve(undefined),
-      ]);
-      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 { view, resolved } = await this.resolveFresh(streamId);
+      if ("status" in resolved) {
+        return { response: resolved, block: view.number };
+      }
+      return {
+        response: await this.describeStatus(resolved, view),
+        block: view.number,
+      };
+    } catch (error) {
+      if (error instanceof ChainLagging) {
+        return { response: this.lagging(error), block: undefined };
       }
+      return {
+        response: this.unavailable("chain read", error),
+        block: undefined,
+      };
+    }
+  }
 
-      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",
-              kind,
-              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",
-              kind,
-              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.",
+  private async describeStatus(
+    resolved: ResolvedStream,
+    view: ChainView,
+  ): Promise<RefundRelayResponse> {
+    const { streamId, stream, opener, payer, kind, factory } = resolved;
+    const grace = this.grace();
+    const now = view.timestamp;
+    const [nonce, latestCheckedAt, upfrontTerms] = await Promise.all([
+      this.readNonce(opener, payer, view),
+      this.readLatestCheckedAt(view),
+      kind === "upfront"
+        ? this.readUpfrontTerms(opener, view)
+        : Promise.resolve(undefined),
+    ]);
+    const closed = stream.status === 1;
+    const stopAt = stopTime(stream);
+    const settled = latestCheckedAt >= stopAt;
+    const fallbackAt = stopAt + grace;
+    const escapeAt = await this.escapeHatchAt(streamId, stream, view);
+
+    let oracle: Record<string, unknown> | null = null;
+    let oracleNote: string | undefined;
+    let reclaimable: bigint | undefined;
+    if (!stream.reclaimed) {
+      const proof = await this.fetchProof(streamId, view);
+      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,
+          view,
+        );
       } 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.",
-        };
+        oracleNote = proof.reason;
       }
+    }
 
-      return {
-        status: 200,
+    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: {
-          streamId,
-          chainId: this.chainId,
-          escrow: this.escrow,
-          factory,
-          openerKind: kind,
-          opener,
-          payer,
-          operator: stream.operator,
-          serviceRef: stream.serviceRef,
-          deposit: stream.deposit.toString(),
-          // The most any refund of this payment can return: the escrowed
-          // deposit. For an upfront opener that is price - upfrontAmount; the
-          // upfront part was paid to the seller at settlement and is final.
-          maxRefund: stream.deposit.toString(),
-          ...(upfrontTerms === undefined
-            ? {}
-            : {
-                price: upfrontTerms.price.toString(),
-                upfrontAmount: upfrontTerms.upfrontAmount.toString(),
-                upfrontNote: `${upfrontTerms.upfrontAmount.toString()} of the ${upfrontTerms.price.toString()} paid was a non-refundable per-call charge, paid to the seller at settlement; at most the ${stream.deposit.toString()} escrowed can be refunded.`,
-              }),
-          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.",
+          deadline: "<the deadline you signed, unix seconds>",
+          signature: "<the payer's EIP-712 signature of typedData>",
         },
+        typedData: jsonTypedData(
+          openerActionTypedData({
+            action: "Close",
+            kind,
+            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",
+            kind,
+            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.",
       };
-    } catch (error) {
-      return this.unavailable("chain read", error);
     }
+
+    return {
+      status: 200,
+      body: {
+        streamId,
+        chainId: this.chainId,
+        escrow: this.escrow,
+        factory,
+        openerKind: kind,
+        opener,
+        payer,
+        operator: stream.operator,
+        serviceRef: stream.serviceRef,
+        deposit: stream.deposit.toString(),
+        // The most any refund of this payment can EVER return (a ceiling,
+        // not what is available now — that is `reclaimable`): the escrowed
+        // deposit. For an upfront opener that is price - upfrontAmount; the
+        // upfront part was paid to the seller at settlement and is final.
+        maxRefund: stream.deposit.toString(),
+        maxRefundMeaning:
+          "ceiling: the most this payment could ever refund (the escrowed deposit), whatever was delivered. Not the amount available now; see reclaimable.",
+        ...(upfrontTerms === undefined
+          ? {}
+          : {
+              price: upfrontTerms.price.toString(),
+              upfrontAmount: upfrontTerms.upfrontAmount.toString(),
+              upfrontNote: `${upfrontTerms.upfrontAmount.toString()} of the ${upfrontTerms.price.toString()} paid was a non-refundable per-call charge, paid to the seller at settlement; at most the ${stream.deposit.toString()} escrowed can be refunded.`,
+            }),
+        ratePerSecond: stream.ratePerSecond.toString(),
+        claimedCumulative: stream.claimedCumulative.toString(),
+        openedAt: Number(stream.openedAt),
+        expiresAt: Number(stream.expiresAt),
+        closedAt: closed ? Number(stream.closedAt) : null,
+        // `status` is the escrow's own on-chain status (Active/Closed), kept
+        // verbatim for clients that parse it. An Active stream past
+        // expiresAt is not running any more: `state` says so.
+        status: closed ? "closed" : "active",
+        onChainStatus: closed ? "closed" : "active",
+        state: streamState(stream, now),
+        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(),
+        reclaimableMeaning: stream.reclaimed
+          ? "already reclaimed: nothing more can be refunded for this stream."
+          : reclaimable === undefined
+            ? "unknown right now (no usable oracle proof yet); see next."
+            : !closed && now < stream.expiresAt
+              ? "what a reclaim would return if the stream stopped now, given the latest verified delivery; it shrinks while the stream runs. Close it first (see next)."
+              : "available now: what a reclaim returns to the payer, given the latest verified delivery. 0 means the verified delivery covers the whole deposit.",
+        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.",
+      },
+    };
   }
 
   // ── POST /streams/:streamId/close ───────────────────────────────────────
@@ -773,10 +885,10 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     const early = await this.precheck(key, "close");
     if (early !== undefined) return early;
     try {
-      const resolved = await this.resolve(streamId);
+      const { view, resolved } = await this.resolveFresh(streamId);
       if ("status" in resolved) return resolved;
       const { stream, opener, payer, kind } = resolved;
-      const now = await this.chainNow();
+      const now = view.timestamp;
       if (stream.status === 1) {
         return fail(409, "already-closed", "the stream is already closed", {
           next: this.link(`/streams/${streamId}/reclaim`),
@@ -798,11 +910,13 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         payer,
         signed,
         now,
+        view,
       );
       if (refused !== undefined) return refused;
       return await this.submit(
         key,
         streamId,
+        view,
         {
           address: opener,
           functionName: "closeWithSig",
@@ -812,6 +926,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         { kind: "close", streamId, opener, payer },
       );
     } catch (error) {
+      if (error instanceof ChainLagging) return this.lagging(error);
       return this.unavailable("chain read", error);
     }
   }
@@ -826,11 +941,11 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     const early = await this.precheck(key, "reclaim");
     if (early !== undefined) return early;
     try {
-      const resolved = await this.resolve(streamId);
+      const { view, resolved } = await this.resolveFresh(streamId);
       if ("status" in resolved) return resolved;
       const { stream, opener, payer } = resolved;
       if (stream.reclaimed) return alreadyReclaimed();
-      const now = await this.chainNow();
+      const now = view.timestamp;
       if (stream.status !== 1 && now < stream.expiresAt) {
         return fail(
           409,
@@ -845,7 +960,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       }
       const stopAt = stopTime(stream);
       const fallbackAt = stopAt + this.grace();
-      const latestCheckedAt = await this.readLatestCheckedAt();
+      const latestCheckedAt = await this.readLatestCheckedAt(view);
       if (latestCheckedAt < stopAt && now < fallbackAt) {
         return fail(
           409,
@@ -855,7 +970,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
           Math.min(CHECKPOINT_RETRY_HINT_SECONDS, Number(fallbackAt - now)),
         );
       }
-      const proof = await this.fetchProof(streamId);
+      const proof = await this.fetchProof(streamId, view);
       if (proof.kind === "unavailable") {
         return fail(503, "oracle-unavailable", proof.reason, {}, 30);
       }
@@ -865,7 +980,9 @@ export class OpenerRefundRelay implements RefundRelayHandler {
           "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)),
+            escapeHatchAt: Number(
+              await this.escapeHatchAt(streamId, stream, view),
+            ),
           },
           CHECKPOINT_RETRY_HINT_SECONDS,
         );
@@ -873,6 +990,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       const amount = await this.readReclaimable(
         streamId,
         proof.cumulativeAmount,
+        view,
       );
       if (amount === 0n) {
         return fail(
@@ -884,6 +1002,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       return await this.submit(
         key,
         streamId,
+        view,
         {
           address: opener,
           functionName: "reclaim",
@@ -902,6 +1021,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         },
       );
     } catch (error) {
+      if (error instanceof ChainLagging) return this.lagging(error);
       return this.unavailable("chain read", error);
     }
   }
@@ -921,12 +1041,12 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     const early = await this.precheck(key, "reclaim");
     if (early !== undefined) return early;
     try {
-      const resolved = await this.resolve(streamId);
+      const { view, resolved } = await this.resolveFresh(streamId);
       if ("status" in resolved) return resolved;
       const { stream, opener, payer, kind } = resolved;
       if (stream.reclaimed) return alreadyReclaimed();
-      const now = await this.chainNow();
-      const escapeAt = await this.escapeHatchAt(streamId, stream);
+      const now = view.timestamp;
+      const escapeAt = await this.escapeHatchAt(streamId, stream, view);
       if (now < escapeAt) {
         return fail(
           409,
@@ -957,11 +1077,13 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         payer,
         signed,
         now,
+        view,
       );
       if (refused !== undefined) return refused;
       return await this.submit(
         key,
         streamId,
+        view,
         {
           address: opener,
           functionName: "reclaimUnverifiedWithSig",
@@ -980,6 +1102,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         },
       );
     } catch (error) {
+      if (error instanceof ChainLagging) return this.lagging(error);
       return this.unavailable("chain read", error);
     }
   }
@@ -1044,14 +1167,132 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     );
   }
 
+  /**
+   * The RPC has not reached the block of a transaction this facilitator saw
+   * mined for the stream. NEVER a `404` (the stream exists) and never a stale
+   * answer: a retryable `503`.
+   */
+  private lagging(error: ChainLagging): RefundRelayResponse {
+    this.log("rpc lagging", error);
+    return fail(
+      503,
+      "chain-lagging",
+      `a transaction for this stream was mined in block ${error.floor}, but the RPC has not caught up to it yet; retry in a few seconds`,
+      { minBlock: error.floor.toString() },
+      2,
+    );
+  }
+
+  /** Poll budget of one answer (snapshot waits + pinned-read retries). */
+  private maxLagPolls(): number {
+    if (this.lagToleranceMs === 0) return 0;
+    return this.lagPollMs === 0
+      ? 3
+      : Math.max(1, Math.ceil(this.lagToleranceMs / this.lagPollMs));
+  }
+
+  /**
+   * A view of the chain at a block >= `floor`: waits (bounded) while the RPC's
+   * `latest` is below it, then throws {@link ChainLagging}.
+   */
+  private async snapshot(floor: bigint | undefined): Promise<ChainView> {
+    const budget = { left: this.maxLagPolls() };
+    for (;;) {
+      const block = await this.config.publicClient.getBlock({
+        blockTag: "latest",
+      });
+      const number =
+        typeof block.number === "bigint" ? block.number : undefined;
+      if (floor === undefined || (number !== undefined && number >= floor)) {
+        return { number, timestamp: BigInt(block.timestamp), budget };
+      }
+      if (budget.left <= 0) throw new ChainLagging(floor, number);
+      budget.left -= 1;
+      await this.sleep(this.lagPollMs);
+    }
+  }
+
+  /**
+   * Resolves a stream on a view that is at or above its floor. A miss for a
+   * stream with no known floor is confirmed once more, a poll interval later,
+   * before it is answered as `404`, so a node that lags the one which mined the stream
+   * (or a facilitator restarted since the settlement) cannot turn a real
+   * stream into "not found".
+   */
+  private async resolveFresh(streamId: Hex): Promise<{
+    readonly view: ChainView;
+    readonly resolved: ResolvedStream | RefundRelayResponse;
+  }> {
+    const floor = this.floors.get(streamId);
+    const view = await this.snapshot(floor);
+    const resolved = await this.resolve(streamId, view);
+    if (!("status" in resolved) || resolved.status !== 404) {
+      return { view, resolved };
+    }
+    if (floor !== undefined) {
+      // Pinned at or above the block that mined it, and still absent: the
+      // chain itself says no. Unexpected for a stream this process settled.
+      this.log(
+        "not found at or above its floor",
+        new Error(`${streamId} absent at block ${String(view.number)}`),
+      );
+      return { view, resolved };
+    }
+    // One confirmation, a poll interval later, on a view at least as high as
+    // the first (a node behind it is waited for, bounded). Not "strictly
+    // newer": a chain that mines no idle blocks (a local fork) would make
+    // every genuine 404 wait the whole bound.
+    await this.sleep(this.lagPollMs);
+    const again = await this.snapshot(view.number).catch((error: unknown) => {
+      // The RPC fell back below the first view: the first (pinned) read stands.
+      if (error instanceof ChainLagging) return undefined;
+      throw error;
+    });
+    if (again === undefined) return { view, resolved };
+    return { view: again, resolved: await this.resolve(streamId, again) };
+  }
+
+  /**
+   * `readContract` pinned to the view's block. A node behind that block
+   * answers with an error rather than old state; such errors are retried
+   * within the view's poll budget. Contract reverts are never retried.
+   */
+  private async read<T>(
+    view: ChainView | undefined,
+    params: Record<string, unknown> | object,
+  ): Promise<T> {
+    for (;;) {
+      try {
+        return (await this.config.publicClient.readContract({
+          ...(params as object),
+          ...(view?.number === undefined ? {} : { blockNumber: view.number }),
+        } as Parameters<PublicClient["readContract"]>[0])) as T;
+      } catch (error) {
+        if (
+          view?.number === undefined ||
+          revertName(error) !== undefined ||
+          view.budget.left <= 0
+        ) {
+          throw error;
+        }
+        view.budget.left -= 1;
+        await this.sleep(this.lagPollMs);
+      }
+    }
+  }
+
   /** When the no-proof escape hatch opens for this stream, per generation. */
   private async escapeHatchAt(
     streamId: Hex,
     stream: { readonly expiresAt: bigint; readonly closedAt: bigint },
+    view: ChainView,
   ): Promise<bigint> {
+    const reader: EscapeHatchReader = {
+      readContract: (args) => this.read<bigint>(view, args),
+    };
     return await readEscapeHatchReadyAt({
       generation: this.generation,
-      reader: this.config.publicClient as unknown as EscapeHatchReader,
+      reader,
       escrow: this.escrow,
       streamId,
       stream,
@@ -1117,6 +1358,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   private async submit(
     key: string,
     streamId: Hex,
+    view: ChainView,
     call: {
       readonly address: Address;
       readonly functionName:
@@ -1176,6 +1418,9 @@ export class OpenerRefundRelay implements RefundRelayHandler {
           abi: x402StreamOpenerAbi,
           functionName: call.functionName,
           args: call.args,
+          // The same block every precondition (and the expected amount) was
+          // read at: a lagging node cannot simulate against older state.
+          ...(view.number === undefined ? {} : { blockNumber: view.number }),
         } as unknown as Parameters<typeof publicClient.simulateContract>[0]);
         if (expectedResult !== undefined) {
           if (
@@ -1267,6 +1512,8 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       );
     }
     this.ledger.set(key, { state: "final", hash, success: true });
+    // Every later answer about this stream must reflect this transaction.
+    this.floors.note(expectation.streamId, receipt.blockNumber);
     if (expectation.kind === "close") {
       return {
         status: 200,
@@ -1302,18 +1549,18 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   /** Streams whose escrow buyer is an opener of the configured factory, or a 404. */
   private async resolve(
     rawStreamId: string,
+    view: ChainView,
   ): Promise<ResolvedStream | RefundRelayResponse> {
     const streamId = parseStreamId(rawStreamId);
     if (streamId === undefined) return invalidStreamId();
-    const { publicClient } = this.config;
     let stream: OpenerStream;
     try {
-      stream = (await publicClient.readContract({
+      stream = await this.read<OpenerStream>(view, {
         address: this.escrow,
         abi: streamEscrowV2Abi,
         functionName: "getStream",
         args: [streamId],
-      })) as unknown as OpenerStream;
+      });
     } catch (error) {
       if (revertName(error) === "UnknownStream") return notFound();
       throw error;
@@ -1323,7 +1570,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     // The kind is whichever CONFIGURED factory's isOpener claims the buyer,
     // read on-chain — never inferred from the address, code or the request.
     const [isStreamOpener, isUpfrontOpener] = await Promise.all([
-      publicClient.readContract({
+      this.read<boolean>(view, {
         address: this.factory,
         abi: x402StreamOpenerFactoryAbi,
         functionName: "isOpener",
@@ -1331,7 +1578,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       }),
       this.upfrontFactory === undefined
         ? Promise.resolve(false)
-        : publicClient.readContract({
+        : this.read<boolean>(view, {
             address: this.upfrontFactory,
             abi: x402UpfrontStreamOpenerFactoryAbi,
             functionName: "isOpener",
@@ -1345,7 +1592,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     const kind: OpenerKind = isUpfrontOpener === true ? "upfront" : "stream";
     const factory =
       kind === "upfront" ? (this.upfrontFactory as Address) : this.factory;
-    const payer = await publicClient.readContract({
+    const payer = await this.read<Address>(view, {
       address: buyer,
       abi: x402StreamOpenerAbi,
       functionName: "payerOf",
@@ -1384,6 +1631,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     payer: Address,
     signed: SignedBody,
     now: bigint,
+    view: ChainView,
   ): Promise<RefundRelayResponse | undefined> {
     if (signed.deadline < now + MIN_SIGNATURE_DEADLINE_HEADROOM_SECONDS) {
       return fail(
@@ -1402,8 +1650,8 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     }
     const { publicClient } = this.config;
     const [nonce, domain] = await Promise.all([
-      this.readNonce(opener, payer),
-      publicClient.readContract({
+      this.readNonce(opener, payer, view),
+      this.read<unknown>(view, {
         address: opener,
         abi: x402StreamOpenerAbi,
         functionName: "eip712Domain",
@@ -1468,16 +1716,13 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     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> {
+  private async readNonce(
+    opener: Address,
+    payer: Address,
+    view: ChainView,
+  ): Promise<bigint> {
     return BigInt(
-      await this.config.publicClient.readContract({
+      await this.read<bigint>(view, {
         address: opener,
         abi: x402StreamOpenerAbi,
         functionName: "nonces",
@@ -1489,21 +1734,25 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   /** An upfront opener's immutable terms (`price`, `upfrontAmount`). */
   private async readUpfrontTerms(
     opener: Address,
+    view: ChainView,
   ): Promise<{ readonly price: bigint; readonly upfrontAmount: bigint }> {
-    const terms = (await this.config.publicClient.readContract({
-      address: opener,
-      abi: x402UpfrontStreamOpenerAbi,
-      functionName: "terms",
-    })) as unknown as { price: bigint; upfrontAmount: bigint };
+    const terms = await this.read<{ price: bigint; upfrontAmount: bigint }>(
+      view,
+      {
+        address: opener,
+        abi: x402UpfrontStreamOpenerAbi,
+        functionName: "terms",
+      },
+    );
     return {
       price: BigInt(terms.price),
       upfrontAmount: BigInt(terms.upfrontAmount),
     };
   }
 
-  private async readLatestCheckedAt(): Promise<bigint> {
+  private async readLatestCheckedAt(view: ChainView): Promise<bigint> {
     return BigInt(
-      await this.config.publicClient.readContract({
+      await this.read<bigint>(view, {
         address: this.escrow,
         abi: streamEscrowV2Abi,
         functionName: "latestCheckpointCheckedAt",
@@ -1514,9 +1763,10 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   private async readReclaimable(
     streamId: Hex,
     cumulativeAmount: bigint,
+    view: ChainView,
   ): Promise<bigint> {
     return BigInt(
-      await this.config.publicClient.readContract({
+      await this.read<bigint>(view, {
         address: this.escrow,
         abi: streamEscrowV2Abi,
         functionName: "reclaimableFor",
@@ -1531,17 +1781,23 @@ export class OpenerRefundRelay implements RefundRelayHandler {
    * root is the escrow's on-chain `latestCheckpointRoot` (the only root the
    * buyer's reclaim settles against).
    */
-  private async fetchProof(streamId: Hex): Promise<OracleProof> {
+  private async fetchProof(
+    streamId: Hex,
+    view: ChainView,
+  ): Promise<OracleProof> {
     const cached = this.fresh(this.proofCache, streamId);
     if (cached !== undefined) return cached.proof;
-    const proof = await this.loadProof(streamId);
+    const proof = await this.loadProof(streamId, view);
     if (proof.kind !== "unavailable") {
       this.remember(this.proofCache, streamId, { proof });
     }
     return proof;
   }
 
-  private async loadProof(streamId: Hex): Promise<OracleProof> {
+  private async loadProof(
+    streamId: Hex,
+    view: ChainView,
+  ): Promise<OracleProof> {
     const url = `${this.oracleUrl}/checkpoint/proof?streamId=${streamId}`;
     let response: Response;
     try {
@@ -1620,7 +1876,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       return { kind: "absent", reason: "the oracle's proof does not verify" };
     }
     const onchainRoot = (
-      await this.config.publicClient.readContract({
+      await this.read<string>(view, {
         address: this.escrow,
         abi: streamEscrowV2Abi,
         functionName: "latestCheckpointRoot",
@@ -1644,6 +1900,19 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   }
 }
 
+/**
+ * What the stream is doing now, as a payer means it: `closed` (on-chain
+ * Closed), `expired` (on-chain still Active, but past `expiresAt`, so it
+ * accrues nothing more and needs no close), or `active` (running).
+ */
+export function streamState(
+  stream: { readonly status: number; readonly expiresAt: bigint },
+  now: bigint,
+): "active" | "expired" | "closed" {
+  if (stream.status === 1) return "closed";
+  return now >= stream.expiresAt ? "expired" : "active";
+}
+
 /** Effective delivery-stop time, exactly as `StreamEscrowV2.reclaim` computes it. */
 function stopTime(stream: OpenerStream): bigint {
   return stream.status === 1 && stream.closedAt < stream.expiresAt