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

package/dist/x402-buyer/refund-actions.js

@@ -0,0 +1,351 @@
+/**
+ * The buyer's own close + reclaim of an x402 stream, through the seller's
+ * gasless refund relay. ONE implementation behind `metrik refund`,
+ * `metrik pay --close-after`, the MCP `x402_pay` tool's `closeAfter` and
+ * {@link closeAfterPayment} (`@absol-labs/agent/x402-buyer`).
+ *
+ * Nothing here is an automatic refund: it runs only when the buyer asks for
+ * it, and it is the buyer's own client that signs the Close and asks the
+ * relay to send the permissionless reclaim. The relay pays the gas; the
+ * opener always sends the reclaim to the payer.
+ *
+ * The waits are bounded and the relay's own: `RefundClient.status()` waits
+ * out a `503 chain-lagging` (honouring `Retry-After`), and
+ * `RefundClient.reclaim()` retries, bounded by the client's `maxAttempts` /
+ * `maxDelayMs`, while the relay says the checkpoint covering the close is not
+ * posted yet.
+ */
+/**
+ * After a close/reclaim, how many times the summary re-reads the relay until
+ * it reflects the transaction just mined (a load-balanced RPC behind the relay
+ * can answer from a node that has not seen it yet), and how long it waits
+ * between reads. Bounded: past it the summary is derived from the verified
+ * receipts instead.
+ */
+export const POST_ACTION_READS = 6;
+export const POST_ACTION_INTERVAL_MS = 1_500;
+/**
+ * A close or reclaim that did not complete. `closed` says whether the stream
+ * is known to be closed (by this run or before it), so the caller can name the
+ * exact command that finishes the job. `cause` is the SDK's error, unchanged.
+ */
+export class RefundActionsError extends Error {
+    stage;
+    closed;
+    closeResult;
+    constructor(context) {
+        super(`the ${context.stage} did not finish: ${context.cause instanceof Error ? context.cause.message : String(context.cause)}`, { cause: context.cause });
+        this.name = "RefundActionsError";
+        this.stage = context.stage;
+        this.closed = context.closed;
+        this.closeResult = context.closeResult;
+    }
+}
+/**
+ * Close and/or reclaim one x402 stream through its refund relay, then read
+ * the state AFTER those actions. Finished states (already closed, already
+ * reclaimed, nothing to reclaim) are reported, not thrown. Anything else that
+ * fails is a {@link RefundActionsError} carrying the SDK's error as `cause`.
+ */
+export async function runRefundActions(input) {
+    const { refunds } = input;
+    let closeResult = null;
+    let closeSkipped = null;
+    // Set when the relay itself says there is nothing left: the stream was
+    // already reclaimed, or the verified delivery covers the whole deposit.
+    // Those are FINISHED recoveries, not failures — a second close + reclaim on
+    // a done stream must succeed and never point the payer at a gas-spending
+    // on-chain recovery that cannot recover a cent.
+    let finishedByRelay = null;
+    if (input.close) {
+        try {
+            // Ask first: a stream that is already closed (or already finished)
+            // needs no Close, so there is nothing to sign and no wallet is needed.
+            const before = await refunds.status();
+            const finishedBefore = finishedReason(before);
+            if (finishedBefore !== null || before.status === "closed") {
+                closeSkipped = finishedBefore ?? "already-closed";
+                finishedByRelay = finishedBefore;
+                input.note?.(finishedBefore === null
+                    ? "stream is already closed — no Close to sign."
+                    : `stream is already closed and ${finishedBefore === "reclaimed" ? "reclaimed" : "has nothing left to reclaim"} — no Close to sign.`);
+            }
+            else {
+                const signer = await input.closeSigner();
+                try {
+                    closeResult = await refunds.close({ signer });
+                    input.note?.(`close relayed in ${closeResult.transaction}${closeResult.verified ? " (receipt verified on-chain)" : ""}`);
+                }
+                catch (error) {
+                    // The status read above said "active", but the stream closed in the
+                    // meantime (it reached expiresAt, or another close landed): the
+                    // state the payer asked for. Anything else is a real failure.
+                    if (relayCode(error) !== "already-closed")
+                        throw error;
+                    closeSkipped = "already-closed";
+                    input.note?.("stream was already closed — no Close was needed.");
+                }
+            }
+        }
+        catch (error) {
+            throw new RefundActionsError({
+                stage: "close",
+                closed: false,
+                closeResult: null,
+                cause: error,
+            });
+        }
+    }
+    let reclaimResult = null;
+    let reclaimSkipped = null;
+    if (input.reclaim) {
+        if (finishedByRelay !== null) {
+            reclaimSkipped = finishedByRelay;
+        }
+        else {
+            if (input.reclaimActivity !== undefined) {
+                input.setActivity?.(input.reclaimActivity);
+            }
+            try {
+                reclaimResult = await refunds.reclaim();
+            }
+            catch (error) {
+                const finished = finishedFromRelayCode(relayCode(error));
+                if (finished === null) {
+                    throw new RefundActionsError({
+                        stage: "reclaim",
+                        closed: closeResult !== null || closeSkipped !== null,
+                        closeResult,
+                        cause: error,
+                    });
+                }
+                reclaimSkipped = finished;
+                finishedByRelay = finished;
+            }
+            finally {
+                input.setActivity?.(null);
+            }
+        }
+    }
+    // The summary describes the state AFTER what this run did: re-read until
+    // the relay reflects the close/reclaim just mined (bounded), else derive it
+    // from the verified receipts. Never the pre-action state.
+    const status = await statusAfterActions(refunds, {
+        closed: closeResult !== null,
+        reclaim: reclaimResult,
+        payer: input.payer,
+        opener: input.opener,
+        streamId: input.streamId,
+        sleep: input.sleep,
+    });
+    // A reclaim THIS run performed is reported as a reclaim, not as "already
+    // finished".
+    const finished = reclaimResult === null ? (finishedReason(status) ?? finishedByRelay) : null;
+    return {
+        close: closeResult,
+        closeSkipped,
+        reclaim: reclaimResult,
+        reclaimSkipped,
+        status,
+        finished,
+    };
+}
+/**
+ * Right after a paid response, at the BUYER's request: close the stream the
+ * payment opened (the payer signs the Close, the relay pays the gas), wait for
+ * the checkpoint covering the close, and reclaim the unearned remainder to the
+ * payer. Never throws for a close/reclaim failure: the payment already
+ * succeeded, so the outcome says what did not finish instead.
+ *
+ * An upfront-only payment (no stream) has nothing to close: the outcome is
+ * `nothing-to-close` and nothing is requested, signed or sent.
+ */
+export async function closeAfterPayment(input) {
+    const { payment } = input;
+    const empty = {
+        close: null,
+        closeSkipped: null,
+        reclaim: null,
+        reclaimSkipped: null,
+        refundedUsdc: null,
+        finished: null,
+        status: null,
+    };
+    if (payment.streamId === null || /^0x0{64}$/i.test(payment.streamId)) {
+        return {
+            ...empty,
+            outcome: "nothing-to-close",
+            streamId: null,
+            incomplete: null,
+        };
+    }
+    const streamId = payment.streamId;
+    if (payment.refundUrl === null) {
+        return {
+            ...empty,
+            outcome: "incomplete",
+            streamId,
+            incomplete: {
+                stage: "no-relay",
+                closed: false,
+                reason: "the seller advertised no refund relay, so there is no gasless close; the stream accrues only for verified seconds until it expires, and anyone can reclaim the unearned remainder to the payer after that",
+                error: null,
+            },
+        };
+    }
+    let refunds;
+    try {
+        refunds = await input.openRefunds();
+    }
+    catch (error) {
+        return {
+            ...empty,
+            outcome: "incomplete",
+            streamId,
+            incomplete: {
+                stage: "close",
+                closed: false,
+                reason: errorMessage(error),
+                error,
+            },
+        };
+    }
+    try {
+        const result = await runRefundActions({
+            ...input,
+            refunds,
+            streamId,
+            opener: payment.opener,
+            close: true,
+            reclaim: true,
+        });
+        return {
+            outcome: "completed",
+            streamId,
+            close: result.close,
+            closeSkipped: result.closeSkipped,
+            reclaim: result.reclaim,
+            reclaimSkipped: result.reclaimSkipped,
+            refundedUsdc: result.reclaim !== null && result.reclaim.verified
+                ? result.reclaim.amount
+                : null,
+            finished: result.finished,
+            status: result.status,
+            incomplete: null,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof RefundActionsError))
+            throw error;
+        return {
+            ...empty,
+            outcome: "incomplete",
+            streamId,
+            close: error.closeResult,
+            incomplete: {
+                stage: error.stage,
+                closed: error.closed,
+                reason: errorMessage(error.cause),
+                error: error.cause,
+            },
+        };
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * The relay's view of a stream AFTER this run's actions. Reads until it
+ * reflects them (closed after a close, reclaimed after a reclaim), bounded;
+ * if the relay still lags, the state those verified transactions imply is
+ * reported instead, marked as derived. With no action, one plain read.
+ */
+export async function statusAfterActions(refunds, done) {
+    const reclaimed = done.reclaim !== null;
+    if (!done.closed && !reclaimed)
+        return await refunds.status();
+    const reflects = (status) => (!done.closed || status.status === "closed" || status.reclaimed) &&
+        (!reclaimed || status.reclaimed);
+    let last = null;
+    for (let attempt = 1; attempt <= POST_ACTION_READS; attempt++) {
+        try {
+            const status = await refunds.status();
+            if (reflects(status))
+                return status;
+            last = status;
+        }
+        catch {
+            // A lagging relay (503 chain-lagging, a stale not-found, a blip): the
+            // transactions already happened, so keep going and derive if need be.
+        }
+        if (attempt < POST_ACTION_READS)
+            await done.sleep(POST_ACTION_INTERVAL_MS);
+    }
+    return derivedStatus(last, done);
+}
+/** The state this run's verified close/reclaim imply, when the relay lags. */
+function derivedStatus(last, done) {
+    const reclaimed = done.reclaim !== null;
+    const note = "derived from this run's transaction receipts; the refund relay had not caught up with them yet";
+    return {
+        streamId: done.streamId,
+        chainId: last?.chainId ?? 0,
+        opener: last?.opener ?? done.opener,
+        payer: last?.payer ?? done.payer ?? done.opener,
+        status: "closed",
+        reclaimed: reclaimed || (last?.reclaimed ?? false),
+        chainTime: last?.chainTime ?? null,
+        reclaimable: null,
+        // Both legs this run verified are on-chain facts: the stream is closed.
+        state: "closed",
+        onChainStatus: "closed",
+        maxRefund: last?.maxRefund ?? null,
+        maxRefundMeaning: last?.maxRefundMeaning ?? null,
+        reclaimableMeaning: last?.reclaimableMeaning ?? null,
+        next: reclaimed
+            ? {
+                action: "none",
+                message: "Reclaimed: the unearned remainder was returned to the payer. Nothing further to do.",
+            }
+            : {
+                action: "reclaim",
+                message: "Closed. Reclaim the unearned remainder once a checkpoint covering the close is posted (usually within a minute).",
+            },
+        raw: { derived: true, note },
+    };
+}
+/**
+ * Whether the relay's status says nothing is left to recover. `reclaimed` is
+ * the chain's one-reclaim-per-stream flag; `next: none` with `reclaimable: 0`
+ * is the relay's "the verified delivery covers the whole deposit".
+ */
+export function finishedReason(status) {
+    if (status.reclaimed)
+        return "reclaimed";
+    if (status.next.action === "none" && status.reclaimable === 0n) {
+        return "nothing-to-reclaim";
+    }
+    return null;
+}
+/** The relay's 409 codes that mean "finished", not "failed". */
+function finishedFromRelayCode(code) {
+    if (code === "already-reclaimed")
+        return "reclaimed";
+    if (code === "nothing-to-reclaim")
+        return "nothing-to-reclaim";
+    return null;
+}
+/** The relay's refusal code, looked up through a few `cause` links. */
+export function relayCode(error) {
+    for (let current = error, depth = 0; depth < 4; depth++) {
+        if (!(current instanceof Error))
+            return null;
+        const code = current.code;
+        if (current.name === "RefundRelayError" && typeof code === "string") {
+            return code;
+        }
+        current = current.cause;
+    }
+    return null;
+}
+//# sourceMappingURL=refund-actions.js.map

package/dist/x402-buyer/refund-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refund-actions.js","sourceRoot":"","sources":["../../src/x402-buyer/refund-actions.ts"],"names":[],"mappings":"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"}

package/dist/x402-opener/block-floors.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The lowest block a read about a stream must be served from, per stream.
+ *
+ * A public RPC endpoint is usually a load balancer over several nodes that are
+ * not all at the same height: the node that returned a transaction's receipt
+ * can be a block or two ahead of the node that answers the next `eth_call` at
+ * `latest`. Right after the facilitator settles a payment (or the refund relay
+ * mines a close or reclaim), a read at `latest` can therefore still see the
+ * stream as it was BEFORE that transaction — not opened yet, still active,
+ * not reclaimed (live finding 2026-10-03: the relay answered `not-found` for a
+ * stream it had settled half a second earlier).
+ *
+ * Whoever observes a mined receipt for a stream records its block here; the
+ * refund relay then refuses to answer from any block below it (it waits,
+ * bounded, for the RPC to catch up and pins every read of one answer to one
+ * block). In-memory, per process, bounded; an entry only ever raises.
+ */
+export declare class StreamBlockFloors {
+    private readonly options;
+    private readonly floors;
+    constructor(options?: {
+        /** How long an entry is kept, ms. Default 1 h. */
+        readonly ttlMs?: number;
+        /** Hard cap on entries (oldest dropped first). Default 10 000. */
+        readonly maxEntries?: number;
+        readonly nowMs?: () => number;
+    });
+    private now;
+    /** Records that `streamId` changed in `block` (a mined receipt's block). */
+    note(streamId: string, block: bigint | number | null | undefined): void;
+    /** The floor for `streamId`, or `undefined` when none is known. */
+    get(streamId: string): bigint | undefined;
+    private prune;
+}
+//# sourceMappingURL=block-floors.d.ts.map

package/dist/x402-opener/block-floors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-floors.d.ts","sourceRoot":"","sources":["../../src/x402-opener/block-floors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAiB;IAO1B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAGnB;gBAGe,OAAO,GAAE;QACxB,kDAAkD;QAClD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QACxB,kEAAkE;QAClE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;KAC1B;IAGR,OAAO,CAAC,GAAG;IAIX,4EAA4E;IAC5E,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,IAAI;IAoBvE,mEAAmE;IACnE,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAWzC,OAAO,CAAC,KAAK;CAOd"}

package/dist/x402-opener/block-floors.js

@@ -0,0 +1,72 @@
+/**
+ * The lowest block a read about a stream must be served from, per stream.
+ *
+ * A public RPC endpoint is usually a load balancer over several nodes that are
+ * not all at the same height: the node that returned a transaction's receipt
+ * can be a block or two ahead of the node that answers the next `eth_call` at
+ * `latest`. Right after the facilitator settles a payment (or the refund relay
+ * mines a close or reclaim), a read at `latest` can therefore still see the
+ * stream as it was BEFORE that transaction — not opened yet, still active,
+ * not reclaimed (live finding 2026-10-03: the relay answered `not-found` for a
+ * stream it had settled half a second earlier).
+ *
+ * Whoever observes a mined receipt for a stream records its block here; the
+ * refund relay then refuses to answer from any block below it (it waits,
+ * bounded, for the RPC to catch up and pins every read of one answer to one
+ * block). In-memory, per process, bounded; an entry only ever raises.
+ */
+export class StreamBlockFloors {
+    options;
+    floors = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
+    now() {
+        return (this.options.nowMs ?? Date.now)();
+    }
+    /** Records that `streamId` changed in `block` (a mined receipt's block). */
+    note(streamId, block) {
+        if (block === null || block === undefined)
+            return;
+        const value = BigInt(block);
+        if (value <= 0n)
+            return;
+        const key = streamId.toLowerCase();
+        const current = this.get(key);
+        if (current !== undefined && current >= value)
+            return;
+        const max = this.options.maxEntries ?? 10_000;
+        if (!this.floors.has(key) && this.floors.size >= max) {
+            this.prune();
+            while (this.floors.size >= max) {
+                const oldest = this.floors.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.floors.delete(oldest);
+            }
+        }
+        this.floors.delete(key);
+        this.floors.set(key, { block: value, at: this.now() });
+    }
+    /** The floor for `streamId`, or `undefined` when none is known. */
+    get(streamId) {
+        const key = streamId.toLowerCase();
+        const entry = this.floors.get(key);
+        if (entry === undefined)
+            return undefined;
+        if (this.now() - entry.at >= (this.options.ttlMs ?? 3_600_000)) {
+            this.floors.delete(key);
+            return undefined;
+        }
+        return entry.block;
+    }
+    prune() {
+        const ttl = this.options.ttlMs ?? 3_600_000;
+        const now = this.now();
+        for (const [key, entry] of this.floors) {
+            if (now - entry.at >= ttl)
+                this.floors.delete(key);
+        }
+    }
+}
+//# sourceMappingURL=block-floors.js.map

package/dist/x402-opener/block-floors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-floors.js","sourceRoot":"","sources":["../../src/x402-opener/block-floors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,OAAO,iBAAiB;IAOT;IANF,MAAM,GAAG,IAAI,GAAG,EAG9B,CAAC;IAEJ,YACmB,UAMb,EAAE;QANW,YAAO,GAAP,OAAO,CAMlB;IACL,CAAC;IAEI,GAAG;QACT,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAC5C,CAAC;IAED,4EAA4E;IAC5E,IAAI,CAAC,QAAgB,EAAE,KAAyC;QAC9D,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAClD,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,KAAK,IAAI,EAAE;YAAE,OAAO;QACxB,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,IAAI,KAAK;YAAE,OAAO;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;YACrD,IAAI,CAAC,KAAK,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,IAAI,GAAG,EAAE,CAAC;gBAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC;gBAC/C,IAAI,MAAM,KAAK,SAAS;oBAAE,MAAM;gBAChC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAC7B,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,mEAAmE;IACnE,GAAG,CAAC,QAAgB;QAClB,MAAM,GAAG,GAAG,QAAQ,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC1C,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC,EAAE,CAAC;YAC/D,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,KAAK,CAAC,KAAK,CAAC;IACrB,CAAC;IAEO,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,SAAS,CAAC;QAC5C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YACvC,IAAI,GAAG,GAAG,KAAK,CAAC,EAAE,IAAI,GAAG;gBAAE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACrD,CAAC;IACH,CAAC;CACF"}

package/dist/x402-opener/facilitator-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facilitator-server.d.ts","sourceRoot":"","sources":["../../src/x402-opener/facilitator-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"facilitator-server.d.ts","sourceRoot":"","sources":["../../src/x402-opener/facilitator-server.ts"],"names":[],"mappings":"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"}

package/dist/x402-opener/facilitator-server.js

@@ -7,6 +7,7 @@ import { privateKeyToAccount } from "viem/accounts";
 import { DEFAULT_METRIK_PUBLIC_REGISTRY_URL } from "../discovery/registry.js";
 import { DEFAULT_LISTING_CACHE_SECONDS, RegistryListingResolver, } from "./listing-resolver.js";
 import { DEFAULT_REFUND_READ_CACHE_SECONDS, DEFAULT_REFUND_SUBMISSIONS_PER_MINUTE, DEFAULT_REFUND_SUBMISSIONS_PER_STREAM_PER_MINUTE, OpenerRefundRelay, } from "./refund-relay.js";
+import { StreamBlockFloors } from "./block-floors.js";
 import { RelayerQueue } from "./relayer-queue.js";
 import { MetrikOpenerExactScheme, } from "./scheme.js";
 import { chainIdFromNetwork } from "./terms.js";
@@ -342,9 +343,14 @@ export async function buildOpenerFacilitator(options) {
     const walletClient = createWalletClient({ account, chain, transport });
     // ONE queue for every transaction this relayer key sends.
     const relayerQueue = new RelayerQueue();
+    // ONE set of per-stream block floors: the scheme records each settlement's
+    // block, and the refund relay never answers below it (a lagging RPC node
+    // would otherwise call a stream settled a second ago "not found").
+    const streamFloors = new StreamBlockFloors();
     const receiptTimeoutMs = options.receiptTimeoutMs;
     const scheme = new MetrikOpenerExactScheme({
         relayerQueue,
+        streamFloors,
         advertiseRefundRelay: options.refundRelay !== undefined,
         network: options.network,
         factoryAddress: options.factoryAddress,
@@ -385,6 +391,7 @@ export async function buildOpenerFacilitator(options) {
             publicClient,
             walletClient,
             relayerQueue,
+            streamFloors,
             ...(receiptTimeoutMs === undefined ? {} : { receiptTimeoutMs }),
             ...(relay.publicBaseUrl === undefined
                 ? {}