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

package/src/x402-opener/block-floors.ts

@@ -0,0 +1,78 @@
+/**
+ * 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 {
+  private readonly floors = new Map<
+    string,
+    { readonly block: bigint; readonly at: number }
+  >();
+
+  constructor(
+    private readonly 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(): number {
+    return (this.options.nowMs ?? Date.now)();
+  }
+
+  /** Records that `streamId` changed in `block` (a mined receipt's block). */
+  note(streamId: string, block: bigint | number | null | undefined): void {
+    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: string): bigint | undefined {
+    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;
+  }
+
+  private prune(): void {
+    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);
+    }
+  }
+}

package/src/x402-opener/facilitator-server.ts

@@ -36,6 +36,7 @@ import {
   type RefundRelayHandler,
   type RefundRelayResponse,
 } from "./refund-relay.js";
+import { StreamBlockFloors } from "./block-floors.js";
 import { RelayerQueue } from "./relayer-queue.js";
 import {
   MetrikOpenerExactScheme,
@@ -528,10 +529,15 @@ export async function buildOpenerFacilitator(
   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,
@@ -574,6 +580,7 @@ export async function buildOpenerFacilitator(
       publicClient,
       walletClient,
       relayerQueue,
+      streamFloors,
       ...(receiptTimeoutMs === undefined ? {} : { receiptTimeoutMs }),
       ...(relay.publicBaseUrl === undefined
         ? {}

package/src/x402-opener/index.ts

@@ -11,3 +11,4 @@ export * from "./scheme.js";
 export * from "./facilitator-server.js";
 export * from "./refund-relay.js";
 export * from "./relayer-queue.js";
+export * from "./block-floors.js";