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

package/src/x402-buyer/refund-actions.ts

@@ -0,0 +1,486 @@
+import type {
+  RefundClient,
+  RefundRelayResult,
+  RefundStatus,
+  X402PayerSigner,
+} from "@absol-labs/sdk/x402";
+
+/**
+ * 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;
+
+/** Why a recovery is over. */
+export type FinishedReason = "reclaimed" | "nothing-to-reclaim";
+/** Why a requested close / reclaim sent nothing. */
+export type SkipReason = FinishedReason | "already-closed";
+/** Which step of a close + reclaim did not finish. */
+export type RefundActionStage = "close" | "reclaim";
+
+export interface RefundActionsInput {
+  /** The SDK refund client, bound to ONE stream. */
+  readonly refunds: RefundClient;
+  readonly streamId: `0x${string}`;
+  readonly opener: `0x${string}`;
+  /** The payer as the chain (or the signed payment) knows it, when known. */
+  readonly payer: `0x${string}` | null;
+  /** Stop the stream (the payer signs the opener's EIP-712 Close). */
+  readonly close: boolean;
+  /** Ask the relay to send the permissionless reclaim (to the payer). */
+  readonly reclaim: boolean;
+  /**
+   * The payer's signer, resolved only when a Close actually has to be signed
+   * (a stream that is already closed needs no wallet). Its caller authorizes
+   * it (e.g. the mandate owner's signature) before returning it.
+   */
+  readonly closeSigner: () => Promise<X402PayerSigner>;
+  readonly sleep: (ms: number) => Promise<void>;
+  /** Progress lines (stderr in the CLI). */
+  readonly note?: (line: string) => void;
+  /** What the run is waiting on, while it waits (`null` clears it). */
+  readonly setActivity?: (activity: string | null) => void;
+  /** Wording of the reclaim wait for {@link RefundActionsInput.setActivity}. */
+  readonly reclaimActivity?: string;
+}
+
+export interface RefundActionsResult {
+  readonly close: RefundRelayResult | null;
+  readonly closeSkipped: SkipReason | null;
+  readonly reclaim: RefundRelayResult | null;
+  readonly reclaimSkipped: SkipReason | null;
+  /** The relay's view AFTER this run's actions (or derived from their receipts). */
+  readonly status: RefundStatus;
+  /**
+   * Set when the recovery is over without a reclaim from THIS run: the stream
+   * was already reclaimed, or the verified delivery covers the whole deposit.
+   */
+  readonly finished: FinishedReason | null;
+}
+
+/**
+ * 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 {
+  readonly stage: RefundActionStage;
+  readonly closed: boolean;
+  readonly closeResult: RefundRelayResult | null;
+
+  constructor(context: {
+    readonly stage: RefundActionStage;
+    readonly closed: boolean;
+    readonly closeResult: RefundRelayResult | null;
+    readonly cause: unknown;
+  }) {
+    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: RefundActionsInput,
+): Promise<RefundActionsResult> {
+  const { refunds } = input;
+  let closeResult: RefundRelayResult | null = null;
+  let closeSkipped: SkipReason | null = 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: FinishedReason | null = 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: RefundRelayResult | null = null;
+  let reclaimSkipped: SkipReason | null = 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,
+  };
+}
+
+/** The outcome of a close + reclaim run right after a paid response. */
+export interface CloseAfterOutcome {
+  /**
+   * `completed`: closed and reclaimed (or the relay says nothing is left).
+   * `nothing-to-close`: an upfront-only payment, no stream was opened.
+   * `incomplete`: the close or the reclaim did not finish; nothing is lost —
+   * finish it with the refund command (`incomplete.stage` says which part).
+   */
+  readonly outcome: "completed" | "nothing-to-close" | "incomplete";
+  readonly streamId: `0x${string}` | null;
+  readonly close: RefundRelayResult | null;
+  readonly closeSkipped: SkipReason | null;
+  readonly reclaim: RefundRelayResult | null;
+  readonly reclaimSkipped: SkipReason | null;
+  /**
+   * Base units returned to the payer by THIS run's reclaim, from the mined
+   * receipt's `ReclaimForwarded` (only when the receipt was verified; `null`
+   * otherwise, including a relay-reported amount nobody checked).
+   */
+  readonly refundedUsdc: bigint | null;
+  readonly finished: FinishedReason | null;
+  readonly status: RefundStatus | null;
+  readonly incomplete: {
+    readonly stage: RefundActionStage | "no-relay";
+    /** Whether the stream is known to be closed already. */
+    readonly closed: boolean;
+    readonly reason: string;
+    readonly error: unknown;
+  } | null;
+}
+
+export interface CloseAfterPaymentInput extends Omit<
+  RefundActionsInput,
+  "refunds" | "streamId" | "opener" | "close" | "reclaim"
+> {
+  /** The settled payment (`metrikStreamOpener` of the pay result). */
+  readonly payment: {
+    readonly streamId: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    readonly refundUrl: string | null;
+  };
+  /** Builds the SDK refund client for that stream (the caller's own wiring). */
+  readonly openRefunds: () => Promise<RefundClient>;
+}
+
+/**
+ * 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: CloseAfterPaymentInput,
+): Promise<CloseAfterOutcome> {
+  const { payment } = input;
+  const empty = {
+    close: null,
+    closeSkipped: null,
+    reclaim: null,
+    reclaimSkipped: null,
+    refundedUsdc: null,
+    finished: null,
+    status: null,
+  } as const;
+  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: RefundClient;
+  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: unknown): string {
+  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: RefundClient,
+  done: {
+    readonly closed: boolean;
+    readonly reclaim: RefundRelayResult | null;
+    readonly payer: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    readonly streamId: `0x${string}`;
+    readonly sleep: (ms: number) => Promise<void>;
+  },
+): Promise<RefundStatus> {
+  const reclaimed = done.reclaim !== null;
+  if (!done.closed && !reclaimed) return await refunds.status();
+  const reflects = (status: RefundStatus): boolean =>
+    (!done.closed || status.status === "closed" || status.reclaimed) &&
+    (!reclaimed || status.reclaimed);
+  let last: RefundStatus | null = 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: RefundStatus | null,
+  done: {
+    readonly closed: boolean;
+    readonly reclaim: RefundRelayResult | null;
+    readonly payer: `0x${string}` | null;
+    readonly opener: `0x${string}`;
+    readonly streamId: `0x${string}`;
+  },
+): RefundStatus {
+  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 },
+  } satisfies RefundStatus;
+}
+
+/**
+ * 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: RefundStatus): FinishedReason | null {
+  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: string | null): FinishedReason | null {
+  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: unknown): string | null {
+  for (let current: unknown = error, depth = 0; depth < 4; depth++) {
+    if (!(current instanceof Error)) return null;
+    const code = (current as { code?: unknown }).code;
+    if (current.name === "RefundRelayError" && typeof code === "string") {
+      return code;
+    }
+    current = current.cause;
+  }
+  return null;
+}

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";