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

package/dist/x402-opener/refund-relay.js

@@ -1,6 +1,7 @@
 import { streamEscrowV2Abi, x402UpfrontStreamOpenerAbi, x402UpfrontStreamOpenerFactoryAbi, } from "@absol-labs/shared";
 import { BaseError, ContractFunctionRevertedError, concat, decodeEventLog, encodeAbiParameters, getAddress, isAddress, isErc6492Signature, isHex, keccak256, maxUint256, } from "viem";
 import { x402StreamOpenerAbi, x402StreamOpenerFactoryAbi } from "./abi.js";
+import { StreamBlockFloors } from "./block-floors.js";
 import { RelayerQueue } from "./relayer-queue.js";
 import { chainIdFromNetwork } from "./terms.js";
 import { escrowGenerationFor, readEscapeHatchReadyAt, UnsupportedEscrowGenerationError, } from "../escrow-generation.js";
@@ -137,6 +138,19 @@ export function processMerkleProof(leaf, proof) {
     }
     return computed;
 }
+/** 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;
+/** The RPC did not reach the stream's floor block within the tolerance. */
+class ChainLagging extends Error {
+    floor;
+    seen;
+    constructor(floor, seen) {
+        super(`RPC is at block ${String(seen)}, below the stream's floor ${floor}`);
+        this.floor = floor;
+        this.seen = seen;
+    }
+}
 /** 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;
@@ -224,6 +238,10 @@ export class OpenerRefundRelay {
     cacheMs;
     logger;
     statusCache = new Map();
+    floors;
+    lagToleranceMs;
+    lagPollMs;
+    sleep;
     proofCache = new Map();
     constructor(config) {
         this.config = config;
@@ -292,6 +310,21 @@ export class OpenerRefundRelay {
         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],
+        ]) {
+            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)));
     }
     /**
      * Proves the wiring before serving: the RPC is on the configured chain and
@@ -335,185 +368,218 @@ export class OpenerRefundRelay {
             return invalidStreamId();
         if (isNoStreamId(streamId))
             return nothingToRefund(404);
+        const floor = this.floors.get(streamId);
         const cached = this.fresh(this.statusCache, streamId);
-        if (cached !== undefined)
+        // 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 = await this.computeStatus(streamId);
-        // Cache definitive answers only (200 / 404), never an outage.
+        }
+        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;
     }
-    async computeStatus(rawStreamId) {
+    async computeStatus(streamId) {
         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 = null;
-            let oracleNote;
-            let reclaimable;
-            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 };
             }
-            const base = `/streams/${streamId}`;
-            let next;
-            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.",
-                        };
+            return {
+                response: await this.describeStatus(resolved, view),
+                block: view.number,
+            };
+        }
+        catch (error) {
+            if (error instanceof ChainLagging) {
+                return { response: this.lagging(error), block: undefined };
             }
-            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.",
+            return {
+                response: this.unavailable("chain read", error),
+                block: undefined,
+            };
+        }
+    }
+    async describeStatus(resolved, view) {
+        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 = null;
+        let oracleNote;
+        let reclaimable;
+        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;
+        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,
+                    deadline: "<the deadline you signed, unix seconds>",
+                    signature: "<the payer's EIP-712 signature of typedData>",
+                },
+                typedData: jsonTypedData(openerActionTypedData({
+                    action: "Close",
+                    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.",
+                    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.",
             };
         }
-        catch (error) {
-            return this.unavailable("chain read", error);
+        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,
+                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 ───────────────────────────────────────
     async close(rawStreamId, body) {
@@ -530,11 +596,11 @@ export class OpenerRefundRelay {
         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`),
@@ -543,16 +609,18 @@ export class OpenerRefundRelay {
             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", kind, streamId, opener, payer, signed, now);
+            const refused = await this.verifyPayerSignature("Close", kind, streamId, opener, payer, signed, now, view);
             if (refused !== undefined)
                 return refused;
-            return await this.submit(key, streamId, {
+            return await this.submit(key, streamId, view, {
                 address: opener,
                 functionName: "closeWithSig",
                 args: [streamId, signed.deadline, signed.signature],
             }, undefined, { kind: "close", streamId, opener, payer });
         }
         catch (error) {
+            if (error instanceof ChainLagging)
+                return this.lagging(error);
             return this.unavailable("chain read", error);
         }
     }
@@ -568,13 +636,13 @@ export class OpenerRefundRelay {
         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, "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),
@@ -583,24 +651,24 @@ export class OpenerRefundRelay {
             }
             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, "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);
+            const proof = await this.fetchProof(streamId, view);
             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)),
+                    escapeHatchAt: Number(await this.escapeHatchAt(streamId, stream, view)),
                 }, CHECKPOINT_RETRY_HINT_SECONDS);
             }
-            const amount = await this.readReclaimable(streamId, proof.cumulativeAmount);
+            const amount = await this.readReclaimable(streamId, proof.cumulativeAmount, view);
             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, {
+            return await this.submit(key, streamId, view, {
                 address: opener,
                 functionName: "reclaim",
                 args: [streamId, proof.cumulativeAmount, proof.proof],
@@ -616,6 +684,8 @@ export class OpenerRefundRelay {
             });
         }
         catch (error) {
+            if (error instanceof ChainLagging)
+                return this.lagging(error);
             return this.unavailable("chain read", error);
         }
     }
@@ -634,14 +704,14 @@ export class OpenerRefundRelay {
         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, "escape-hatch-not-ready", this.generation === "v2"
                     ? "the no-proof escape hatch opens only at expiresAt + escapeGraceSeconds; use the proof-based reclaim before then"
@@ -654,10 +724,10 @@ export class OpenerRefundRelay {
             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", kind, streamId, opener, payer, signed, now);
+            const refused = await this.verifyPayerSignature("ReclaimUnverified", kind, streamId, opener, payer, signed, now, view);
             if (refused !== undefined)
                 return refused;
-            return await this.submit(key, streamId, {
+            return await this.submit(key, streamId, view, {
                 address: opener,
                 functionName: "reclaimUnverifiedWithSig",
                 args: [streamId, signed.deadline, signed.signature],
@@ -673,6 +743,8 @@ export class OpenerRefundRelay {
             });
         }
         catch (error) {
+            if (error instanceof ChainLagging)
+                return this.lagging(error);
             return this.unavailable("chain read", error);
         }
     }
@@ -719,11 +791,110 @@ export class OpenerRefundRelay {
         this.log(context, error);
         return fail(503, "chain-unavailable", "the chain could not be read right now; retry shortly", {}, 10);
     }
+    /**
+     * 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`.
+     */
+    lagging(error) {
+        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). */
+    maxLagPolls() {
+        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}.
+     */
+    async snapshot(floor) {
+        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".
+     */
+    async resolveFresh(streamId) {
+        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) => {
+            // 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.
+     */
+    async read(view, params) {
+        for (;;) {
+            try {
+                return (await this.config.publicClient.readContract({
+                    ...params,
+                    ...(view?.number === undefined ? {} : { blockNumber: view.number }),
+                }));
+            }
+            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. */
-    async escapeHatchAt(streamId, stream) {
+    async escapeHatchAt(streamId, stream, view) {
+        const reader = {
+            readContract: (args) => this.read(view, args),
+        };
         return await readEscapeHatchReadyAt({
             generation: this.generation,
-            reader: this.config.publicClient,
+            reader,
             escrow: this.escrow,
             streamId,
             stream,
@@ -771,7 +942,7 @@ export class OpenerRefundRelay {
      * and broadcasts through the shared relayer queue. `expectedResult`, when
      * set, is the exact non-zero amount the simulation must return.
      */
-    async submit(key, streamId, call, expectedResult, expectation) {
+    async submit(key, streamId, view, call, expectedResult, expectation) {
         // 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);
@@ -801,6 +972,9 @@ export class OpenerRefundRelay {
                     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 }),
                 });
                 if (expectedResult !== undefined) {
                     if (typeof result !== "bigint" ||
@@ -857,6 +1031,8 @@ export class OpenerRefundRelay {
             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 });
+        // Every later answer about this stream must reflect this transaction.
+        this.floors.note(expectation.streamId, receipt.blockNumber);
         if (expectation.kind === "close") {
             return {
                 status: 200,
@@ -888,19 +1064,18 @@ export class OpenerRefundRelay {
         };
     }
     /** Streams whose escrow buyer is an opener of the configured factory, or a 404. */
-    async resolve(rawStreamId) {
+    async resolve(rawStreamId, view) {
         const streamId = parseStreamId(rawStreamId);
         if (streamId === undefined)
             return invalidStreamId();
-        const { publicClient } = this.config;
         let stream;
         try {
-            stream = (await publicClient.readContract({
+            stream = await this.read(view, {
                 address: this.escrow,
                 abi: streamEscrowV2Abi,
                 functionName: "getStream",
                 args: [streamId],
-            }));
+            });
         }
         catch (error) {
             if (revertName(error) === "UnknownStream")
@@ -913,7 +1088,7 @@ export class OpenerRefundRelay {
         // 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(view, {
                 address: this.factory,
                 abi: x402StreamOpenerFactoryAbi,
                 functionName: "isOpener",
@@ -921,7 +1096,7 @@ export class OpenerRefundRelay {
             }),
             this.upfrontFactory === undefined
                 ? Promise.resolve(false)
-                : publicClient.readContract({
+                : this.read(view, {
                     address: this.upfrontFactory,
                     abi: x402UpfrontStreamOpenerFactoryAbi,
                     functionName: "isOpener",
@@ -934,7 +1109,7 @@ export class OpenerRefundRelay {
         }
         const kind = isUpfrontOpener === true ? "upfront" : "stream";
         const factory = kind === "upfront" ? this.upfrontFactory : this.factory;
-        const payer = await publicClient.readContract({
+        const payer = await this.read(view, {
             address: buyer,
             abi: x402StreamOpenerAbi,
             functionName: "payerOf",
@@ -965,7 +1140,7 @@ export class OpenerRefundRelay {
         };
     }
     /** Off-chain check of a payer-signed opener action. `undefined` = valid. */
-    async verifyPayerSignature(action, kind, streamId, opener, payer, signed, now) {
+    async verifyPayerSignature(action, kind, streamId, opener, payer, signed, now, view) {
         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) });
         }
@@ -974,8 +1149,8 @@ export class OpenerRefundRelay {
         }
         const { publicClient } = this.config;
         const [nonce, domain] = await Promise.all([
-            this.readNonce(opener, payer),
-            publicClient.readContract({
+            this.readNonce(opener, payer, view),
+            this.read(view, {
                 address: opener,
                 abi: x402StreamOpenerAbi,
                 functionName: "eip712Domain",
@@ -1016,14 +1191,8 @@ export class OpenerRefundRelay {
         }
         return undefined;
     }
-    async chainNow() {
-        const block = await this.config.publicClient.getBlock({
-            blockTag: "latest",
-        });
-        return BigInt(block.timestamp);
-    }
-    async readNonce(opener, payer) {
-        return BigInt(await this.config.publicClient.readContract({
+    async readNonce(opener, payer, view) {
+        return BigInt(await this.read(view, {
             address: opener,
             abi: x402StreamOpenerAbi,
             functionName: "nonces",
@@ -1031,26 +1200,26 @@ export class OpenerRefundRelay {
         }));
     }
     /** An upfront opener's immutable terms (`price`, `upfrontAmount`). */
-    async readUpfrontTerms(opener) {
-        const terms = (await this.config.publicClient.readContract({
+    async readUpfrontTerms(opener, view) {
+        const terms = await this.read(view, {
             address: opener,
             abi: x402UpfrontStreamOpenerAbi,
             functionName: "terms",
-        }));
+        });
         return {
             price: BigInt(terms.price),
             upfrontAmount: BigInt(terms.upfrontAmount),
         };
     }
-    async readLatestCheckedAt() {
-        return BigInt(await this.config.publicClient.readContract({
+    async readLatestCheckedAt(view) {
+        return BigInt(await this.read(view, {
             address: this.escrow,
             abi: streamEscrowV2Abi,
             functionName: "latestCheckpointCheckedAt",
         }));
     }
-    async readReclaimable(streamId, cumulativeAmount) {
-        return BigInt(await this.config.publicClient.readContract({
+    async readReclaimable(streamId, cumulativeAmount, view) {
+        return BigInt(await this.read(view, {
             address: this.escrow,
             abi: streamEscrowV2Abi,
             functionName: "reclaimableFor",
@@ -1063,17 +1232,17 @@ export class OpenerRefundRelay {
      * root is the escrow's on-chain `latestCheckpointRoot` (the only root the
      * buyer's reclaim settles against).
      */
-    async fetchProof(streamId) {
+    async fetchProof(streamId, view) {
         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;
     }
-    async loadProof(streamId) {
+    async loadProof(streamId, view) {
         const url = `${this.oracleUrl}/checkpoint/proof?streamId=${streamId}`;
         let response;
         try {
@@ -1142,7 +1311,7 @@ export class OpenerRefundRelay {
             root) {
             return { kind: "absent", reason: "the oracle's proof does not verify" };
         }
-        const onchainRoot = (await this.config.publicClient.readContract({
+        const onchainRoot = (await this.read(view, {
             address: this.escrow,
             abi: streamEscrowV2Abi,
             functionName: "latestCheckpointRoot",
@@ -1163,6 +1332,16 @@ export class OpenerRefundRelay {
         };
     }
 }
+/**
+ * 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, now) {
+    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) {
     return stream.status === 1 && stream.closedAt < stream.expiresAt