@absol-labs/agent 0.11.0 → 0.12.0-rc.1

package/src/x402-opener/scheme.ts

@@ -0,0 +1,1133 @@
+import { streamEscrowV2Abi } from "@absol-labs/shared";
+import type {
+  FacilitatorContext,
+  Network,
+  PaymentPayload,
+  PaymentRequirements,
+  SchemeNetworkFacilitator,
+  SettleResponse,
+  VerifyResponse,
+} from "@x402/core/types";
+import { deepEqual } from "@x402/core/utils";
+import {
+  isEIP3009Payload,
+  toFacilitatorEvmSigner,
+  type ExactEIP3009Payload,
+  type ExactEvmPayloadV2,
+} from "@x402/evm";
+import { ExactEvmScheme } from "@x402/evm/exact/facilitator";
+import {
+  BaseError,
+  ContractFunctionRevertedError,
+  decodeEventLog,
+  getAddress,
+  isAddress,
+  isErc6492Signature,
+  isHex,
+  type Account,
+  type Address,
+  type Chain,
+  type Hex,
+  type Log,
+  type PublicClient,
+  type Transport,
+  type WalletClient,
+} from "viem";
+
+import { x402StreamOpenerAbi, x402StreamOpenerFactoryAbi } from "./abi.js";
+import type { OperatorSignedListingResolver } from "./listing-resolver.js";
+import { RelayerQueue } from "./relayer-queue.js";
+import {
+  chainIdFromNetwork,
+  maxEarnable,
+  OPENER_EXTRA_KEY,
+  OPENER_SCHEME,
+  parseUintString,
+  termsFromExtra,
+  termsTuple,
+  type OpenerTerms,
+} from "./terms.js";
+
+/**
+ * `MetrikOpenerExactScheme` — an x402 v2 `exact` facilitator scheme that
+ * settles every payment INTO a `StreamEscrowV2` stream through the ownerless
+ * `X402StreamOpenerFactory` (metrik-agent#116, metrik-contracts#48).
+ *
+ * ## What it composes, and what it refuses
+ *
+ * Standard `exact` checks (EIP-712 signature, recipient == `payTo`, value ==
+ * amount, validity window, asset is a contract, balance / nonce simulation of
+ * the transfer) are delegated to the official `@x402/evm` `ExactEvmScheme`
+ * verifier, never reimplemented. On top of it, every payment must satisfy:
+ *
+ * - `assetTransferMethod` is EIP-3009. Permit2 and every other method are
+ *   refused: the opener only ever pulls an EIP-3009 authorization.
+ * - The signature is NOT ERC-6492-wrapped. A counterfactual smart wallet would
+ *   need a factory deploy the opener cannot perform; refused with a reason.
+ * - `asset` is on the allowlist AND is the factory's own settlement token.
+ * - `payTo == factory.predict(terms)`, recomputed on-chain from the configured
+ *   factory for the terms in `extra.metrikStreamOpener` — never compared by
+ *   code or codehash (a byte-identical clone outside the factory proves
+ *   nothing). The factory named in `extra` must be the configured one.
+ * - `(operator, serviceRef)` resolve to exactly ONE operator-signed listing via
+ *   the existing discovery signature verification; the rate is inside the
+ *   listing's signed commercial bounds when it declares them.
+ * - `0 < amount <= ratePerSecond * maxDuration`.
+ * - `factory.deployAndSettle` simulates cleanly from the relayer.
+ *
+ * Any doubt — an RPC error, an unreachable registry, a malformed field — is an
+ * invalid verdict. Nothing here ever fails open.
+ *
+ * ## Settlement
+ *
+ * `settle` re-runs the full verification, then calls `deployAndSettle` from the
+ * relayer, waits for the receipt, and returns success ONLY when the mined
+ * receipt carries both the opener's `StreamOpenedFor` and the escrow's
+ * `StreamOpened` for exactly this payer, nonce, amount and terms. The stock
+ * `ExactEvmScheme.settle` is never called: it would transfer the USDC straight
+ * to `payTo`, and USDC that reaches an opener any other way than
+ * `settleAndOpen` is unrecoverable. The signer handed to the stock scheme
+ * cannot broadcast at all, so that path is closed structurally too.
+ *
+ * ## At most one success per authorization
+ *
+ * An EIP-3009 authorization (chain + asset + payer + nonce) receives AT MOST
+ * ONE successful `SettleResponse` from this instance, ever. A settle of an
+ * authorization that is in flight, or already settled, returns `success:
+ * false` with `duplicate_settlement` (carrying the tx hash when there is one),
+ * and `verify` refuses it the same way — so one payment can never buy two
+ * served responses. After a `settlement_pending` (receipt wait timed out) the
+ * next settle of the SAME payload reconciles against the broadcast tx and may
+ * receive the one success, if none was delivered before. The ledger is
+ * in-memory and per instance: a multi-instance deployment needs a shared store
+ * and does not have one today.
+ *
+ * Relayer submissions (simulate + write) are serialized so concurrent payers
+ * never race for the relayer's account nonce.
+ */
+
+/** Reasons this scheme adds to the stock `exact` ones. All fail closed. */
+export const OpenerInvalidReason = {
+  unsupportedScheme: "metrik_opener_unsupported_scheme",
+  unsupportedNetwork: "metrik_opener_unsupported_network",
+  unsupportedVersion: "metrik_opener_unsupported_x402_version",
+  acceptedMismatch: "metrik_opener_accepted_requirements_mismatch",
+  unsupportedAssetTransferMethod:
+    "metrik_opener_asset_transfer_method_not_eip3009",
+  erc6492Unsupported: "metrik_opener_erc6492_signature_unsupported",
+  missingSignature: "metrik_opener_missing_signature",
+  assetNotAllowed: "metrik_opener_asset_not_allowed",
+  invalidTerms: "metrik_opener_invalid_terms",
+  factoryMismatch: "metrik_opener_factory_mismatch",
+  payToMismatch: "metrik_opener_pay_to_not_predicted_opener",
+  invalidAmount: "metrik_opener_invalid_amount",
+  amountExceedsTerms: "metrik_opener_amount_exceeds_rate_times_duration",
+  listingUnavailable: "metrik_opener_listing_registry_unavailable",
+  listingNotFound: "metrik_opener_listing_not_found",
+  listingAmbiguous: "metrik_opener_listing_ambiguous",
+  listingRateOutOfBounds: "metrik_opener_listing_rate_out_of_bounds",
+  simulationFailed: "metrik_opener_settle_simulation_failed",
+  verifyError: "metrik_opener_verify_error",
+  transactionReverted: "metrik_opener_transaction_reverted",
+  streamEventMismatch: "metrik_opener_stream_event_mismatch",
+  settlementPending: "settlement_pending",
+  settleError: "metrik_opener_settle_error",
+  amountBelowMinimum: "metrik_opener_amount_below_minimum",
+  /**
+   * This authorization is already being settled, or already settled, by this
+   * facilitator instance. May carry the settlement transaction hash. Never a
+   * second success (see "At most one success" on the class).
+   */
+  duplicateSettlement: "duplicate_settlement",
+  settlementCapacity: "metrik_opener_settlement_capacity_exhausted",
+} as const;
+
+/** Default facilitator minimum payment: 10000 base units = 0.01 USDC. */
+export const DEFAULT_OPENER_MIN_AMOUNT = 10_000n;
+
+/** Hard cap on remembered authorizations; beyond it new settles fail closed. */
+const MAX_LEDGER_ENTRIES = 100_000;
+
+/** Grace after an authorization's `validBefore` before its ledger entry is dropped. */
+const LEDGER_GRACE_SECONDS = 600n;
+
+export interface MetrikOpenerExactSchemeConfig {
+  /** CAIP-2 network (`eip155:<chainId>`), as the registry gives it. Must match the RPC's chain id. */
+  readonly network: Network;
+  /** The deployed `X402StreamOpenerFactory`. */
+  readonly factoryAddress: Address;
+  /** The `StreamEscrowV2` the factory must point at (checked by {@link init}). */
+  readonly escrowAddress: Address;
+  /** Settlement tokens this facilitator accepts. Must contain `factory.usdc()`. */
+  readonly assetAllowlist: readonly Address[];
+  /** Read client for the network. */
+  readonly publicClient: PublicClient<Transport, Chain | undefined>;
+  /** Relayer wallet. Pays gas for `deployAndSettle`; never holds buyer funds. */
+  readonly walletClient: WalletClient<Transport, Chain | undefined, Account>;
+  readonly listingResolver: OperatorSignedListingResolver;
+  /** How long to wait for a settlement receipt before reporting `settlement_pending`. Default 60s. */
+  readonly receiptTimeoutMs?: number;
+  /**
+   * Smallest accepted payment, token base units. Default
+   * {@link DEFAULT_OPENER_MIN_AMOUNT}. Every settlement costs the relayer a
+   * full `deployAndSettle`, so dust payments would be a gas drain.
+   */
+  readonly minAmount?: bigint;
+  /** Injectable clock (unix seconds), for tests. */
+  readonly now?: () => number;
+  /**
+   * The relayer's submission queue. Pass the SAME queue to every component
+   * that broadcasts from this relayer key (the refund relay does), so their
+   * transactions never race for the account nonce. Default: a private queue.
+   */
+  readonly relayerQueue?: RelayerQueue;
+  /**
+   * Advertise `refundRelay: true` in the `/supported` marker: this service
+   * also runs the gasless refund relay (`/streams/:streamId/...`). Set only
+   * when the relay is actually mounted. Default false.
+   */
+  readonly advertiseRefundRelay?: boolean;
+}
+
+/**
+ * One remembered EIP-3009 authorization, keyed by chain + asset + payer +
+ * authorization nonce.
+ *
+ * - `in-flight`: a settle is actively running (verify → submit → receipt).
+ * - `pending`: submitted, but the receipt wait timed out; the next settle of
+ *   the SAME payload reconciles against `hash` instead of broadcasting again.
+ * - `final`: settled (the one success was delivered) or otherwise terminal.
+ */
+type LedgerEntry =
+  | {
+      readonly state: "in-flight";
+      readonly validBefore: bigint;
+      hash?: Hex;
+    }
+  | {
+      readonly state: "pending";
+      readonly validBefore: bigint;
+      readonly hash: Hex;
+      readonly payload: PaymentPayload;
+      readonly requirements: PaymentRequirements;
+      readonly auth: ExactEIP3009Payload & { signature: Hex };
+      readonly terms: OpenerTerms;
+      readonly opener: Address;
+    }
+  | {
+      readonly state: "final";
+      readonly validBefore: bigint;
+      readonly hash: Hex | "";
+    };
+
+/** What {@link MetrikOpenerExactScheme.init} proved about the on-chain wiring. */
+export interface OpenerFacilitatorBinding {
+  readonly chainId: number;
+  readonly factory: Address;
+  readonly escrow: Address;
+  readonly usdc: Address;
+  readonly relayer: Address;
+}
+
+/**
+ * Marker this facilitator advertises in `GET /supported` (`kinds[].extra`), so
+ * a resource server can refuse to quote an opener `payTo` through any
+ * facilitator that would settle it with a plain `transferWithAuthorization`
+ * (which strands the funds). See {@link readOpenerFacilitatorMarker}.
+ */
+export interface OpenerFacilitatorMarker {
+  readonly settlement: "x402-stream-opener";
+  readonly factory: Address;
+  readonly escrow: Address;
+  readonly usdc: Address;
+  readonly chainId: number;
+  /** Smallest accepted amount, base units (decimal string). */
+  readonly minAmount: string;
+  /** How long `settle` waits for a receipt before `settlement_pending`. */
+  readonly receiptTimeoutSeconds: number;
+  /**
+   * True when the same service runs the gasless refund relay
+   * (`GET /streams/:streamId`, `POST /streams/:streamId/close|reclaim`).
+   * Absent (read as false) otherwise.
+   */
+  readonly refundRelay?: true;
+}
+
+export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
+  readonly scheme = OPENER_SCHEME;
+  readonly caipFamily = "eip155:*";
+
+  private readonly stock: ExactEvmScheme;
+  private readonly chainId: number;
+  private readonly allowlist: ReadonlySet<string>;
+  private readonly receiptTimeoutMs: number;
+  private readonly minAmount: bigint;
+  private readonly now: () => number;
+  private readonly ledger = new Map<string, LedgerEntry>();
+  /** Serializes relayer submissions (simulate + write) so nonces never collide. */
+  private readonly relayerQueue: RelayerQueue;
+  private binding: OpenerFacilitatorBinding | undefined;
+
+  constructor(private readonly config: MetrikOpenerExactSchemeConfig) {
+    this.chainId = chainIdFromNetwork(config.network);
+    if (!isAddress(config.factoryAddress)) {
+      throw new Error("factoryAddress must be an EVM address");
+    }
+    if (!isAddress(config.escrowAddress)) {
+      throw new Error("escrowAddress must be an EVM address");
+    }
+    if (config.assetAllowlist.length === 0) {
+      throw new Error("assetAllowlist must not be empty");
+    }
+    for (const asset of config.assetAllowlist) {
+      if (!isAddress(asset)) {
+        throw new Error(`assetAllowlist entry is not an address: ${asset}`);
+      }
+    }
+    this.allowlist = new Set(
+      config.assetAllowlist.map((asset) => asset.toLowerCase()),
+    );
+    this.receiptTimeoutMs = config.receiptTimeoutMs ?? 60_000;
+    if (
+      !Number.isInteger(this.receiptTimeoutMs) ||
+      this.receiptTimeoutMs <= 0
+    ) {
+      throw new Error("receiptTimeoutMs must be a positive integer");
+    }
+    this.minAmount = config.minAmount ?? DEFAULT_OPENER_MIN_AMOUNT;
+    if (this.minAmount <= 0n) {
+      throw new Error("minAmount must be > 0");
+    }
+    this.now = config.now ?? (() => Math.floor(Date.now() / 1000));
+    this.relayerQueue = config.relayerQueue ?? new RelayerQueue();
+
+    // The stock verifier gets a READ-ONLY signer. Its settle path would send the
+    // USDC straight to payTo; making writes impossible closes that path even if
+    // a future refactor called it by mistake.
+    const publicClient = config.publicClient;
+    const refuseWrite = async (): Promise<never> => {
+      throw new Error(
+        "MetrikOpenerExactScheme: the stock exact scheme may not broadcast; opener payments settle only via deployAndSettle",
+      );
+    };
+    this.stock = new ExactEvmScheme(
+      toFacilitatorEvmSigner({
+        address: config.walletClient.account.address,
+        readContract: (args) =>
+          publicClient.readContract(
+            args as Parameters<typeof publicClient.readContract>[0],
+          ),
+        verifyTypedData: (args) =>
+          publicClient.verifyTypedData(
+            args as Parameters<typeof publicClient.verifyTypedData>[0],
+          ),
+        getCode: (args) => publicClient.getCode(args),
+        waitForTransactionReceipt: refuseWrite,
+        writeContract: refuseWrite,
+        sendTransaction: refuseWrite,
+      }),
+      // ERC-6492 factory deployment disabled: 6492 signatures are refused
+      // before the stock verifier is ever reached.
+      { eip6492AllowedFactories: [] },
+    );
+  }
+
+  /**
+   * Proves the on-chain wiring before the facilitator serves anything: the RPC
+   * is on the configured chain, the factory has code, points at the configured
+   * escrow, and its token is allowlisted. Throws otherwise (the service refuses
+   * to start).
+   */
+  async init(): Promise<OpenerFacilitatorBinding> {
+    const { publicClient, factoryAddress, escrowAddress } = this.config;
+    const rpcChainId = await publicClient.getChainId();
+    if (rpcChainId !== this.chainId) {
+      throw new Error(
+        `RPC chain id ${rpcChainId} does not match network ${this.config.network}`,
+      );
+    }
+    const code = await publicClient.getCode({ address: factoryAddress });
+    if (code === undefined || code === "0x") {
+      throw new Error(`no contract at factory address ${factoryAddress}`);
+    }
+    const [factoryEscrow, factoryUsdc] = await Promise.all([
+      publicClient.readContract({
+        address: factoryAddress,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "escrow",
+      }),
+      publicClient.readContract({
+        address: factoryAddress,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "usdc",
+      }),
+    ]);
+    if (getAddress(factoryEscrow) !== getAddress(escrowAddress)) {
+      throw new Error(
+        `factory escrow ${factoryEscrow} is not the configured escrow ${escrowAddress}`,
+      );
+    }
+    if (!this.allowlist.has(factoryUsdc.toLowerCase())) {
+      throw new Error(
+        `factory settlement token ${factoryUsdc} is not on the asset allowlist`,
+      );
+    }
+    this.binding = {
+      chainId: this.chainId,
+      factory: getAddress(factoryAddress),
+      escrow: getAddress(factoryEscrow),
+      usdc: getAddress(factoryUsdc),
+      relayer: this.config.walletClient.account.address,
+    };
+    return this.binding;
+  }
+
+  /** `/supported` extra: the marker a resource server checks before quoting an opener. */
+  getExtra(_network: string): Record<string, unknown> | undefined {
+    const binding = this.binding;
+    if (binding === undefined) {
+      return undefined;
+    }
+    const marker: OpenerFacilitatorMarker = {
+      settlement: "x402-stream-opener",
+      factory: binding.factory,
+      escrow: binding.escrow,
+      usdc: binding.usdc,
+      chainId: binding.chainId,
+      minAmount: this.minAmount.toString(),
+      receiptTimeoutSeconds: Math.ceil(this.receiptTimeoutMs / 1000),
+      ...(this.config.advertiseRefundRelay === true
+        ? { refundRelay: true as const }
+        : {}),
+    };
+    return { [OPENER_EXTRA_KEY]: marker };
+  }
+
+  getSigners(_network: string): string[] {
+    return [this.config.walletClient.account.address];
+  }
+
+  async verify(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+    context?: FacilitatorContext,
+  ): Promise<VerifyResponse> {
+    try {
+      const key = this.ledgerKey(payload);
+      const entry = key === undefined ? undefined : this.ledger.get(key);
+      if (entry !== undefined) {
+        if (
+          entry.state === "pending" &&
+          deepEqual(entry.payload, payload) &&
+          deepEqual(entry.requirements, requirements)
+        ) {
+          // Submitted earlier, receipt not yet seen: the authorization may
+          // already be used on-chain, so the on-chain checks would refuse it.
+          // The retry is valid only so that settle can reconcile THIS tx.
+          return { isValid: true, payer: entry.auth.authorization.from };
+        }
+        return invalid(
+          OpenerInvalidReason.duplicateSettlement,
+          "this authorization is already being settled or was settled",
+          payerOf(payload),
+        );
+      }
+      const checked = await this.check(payload, requirements, context);
+      if (!checked.ok) {
+        return checked.response;
+      }
+      return { isValid: true, payer: checked.auth.authorization.from };
+    } catch (error) {
+      return invalid(
+        OpenerInvalidReason.verifyError,
+        describe(error),
+        payerOf(payload),
+      );
+    }
+  }
+
+  async settle(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+    context?: FacilitatorContext,
+  ): Promise<SettleResponse> {
+    const network = requirements.network;
+    const payer = payerOf(payload);
+    const key = this.ledgerKey(payload);
+    if (key === undefined) {
+      // Not a parseable EIP-3009 authorization: the full check refuses it.
+      const checked = await this.check(payload, requirements, context).catch(
+        (error: unknown) => ({
+          ok: false as const,
+          response: invalid(
+            OpenerInvalidReason.verifyError,
+            describe(error),
+            payer,
+          ),
+        }),
+      );
+      return checked.ok
+        ? failure(
+            OpenerInvalidReason.verifyError,
+            network,
+            payer,
+            "unparseable authorization",
+          )
+        : refusal(checked.response, network, payer);
+    }
+
+    // ── At most one success per authorization ─────────────────────────────
+    // Everything from here to the ledger write is synchronous, so two
+    // concurrent settles of the same authorization can never both claim it.
+    this.pruneLedger();
+    const existing = this.ledger.get(key);
+    if (existing !== undefined) {
+      if (
+        existing.state === "pending" &&
+        deepEqual(existing.payload, payload) &&
+        deepEqual(existing.requirements, requirements)
+      ) {
+        this.ledger.set(key, {
+          state: "in-flight",
+          validBefore: existing.validBefore,
+          hash: existing.hash,
+        });
+        return this.finish(
+          key,
+          payload,
+          requirements,
+          existing.validBefore,
+          await this.awaitSettlement(
+            existing.hash,
+            existing.auth,
+            existing.terms,
+            existing.opener,
+            network,
+          ),
+          existing,
+        );
+      }
+      return failure(
+        OpenerInvalidReason.duplicateSettlement,
+        network,
+        payer,
+        "this authorization is already being settled or was settled",
+        existing.hash ?? "",
+      );
+    }
+    if (this.ledger.size >= MAX_LEDGER_ENTRIES) {
+      return failure(
+        OpenerInvalidReason.settlementCapacity,
+        network,
+        payer,
+        undefined,
+      );
+    }
+    const validBefore = BigInt(
+      (eip3009(payload) as ExactEIP3009Payload).authorization.validBefore,
+    );
+    const entry: LedgerEntry = { state: "in-flight", validBefore };
+    this.ledger.set(key, entry);
+
+    try {
+      const checked = await this.check(payload, requirements, context);
+      if (!checked.ok) {
+        this.ledger.delete(key);
+        return refusal(checked.response, network, payer);
+      }
+
+      const { auth, terms, opener } = checked;
+      let hash: Hex;
+      try {
+        hash = await this.submitSerialized(auth, terms);
+      } catch (error) {
+        this.ledger.delete(key);
+        return failure(
+          OpenerInvalidReason.simulationFailed,
+          network,
+          auth.authorization.from,
+          revertReason(error),
+        );
+      }
+      entry.hash = hash;
+      return this.finish(
+        key,
+        payload,
+        requirements,
+        validBefore,
+        await this.awaitSettlement(hash, auth, terms, opener, network),
+        { auth, terms, opener },
+      );
+    } catch (error) {
+      // Unknown state after a possible broadcast: keep the authorization
+      // blocked (never a second success), but only if something was sent.
+      if (entry.hash === undefined) {
+        this.ledger.delete(key);
+      } else {
+        this.ledger.set(key, { state: "final", validBefore, hash: entry.hash });
+      }
+      return failure(
+        OpenerInvalidReason.settleError,
+        network,
+        payer,
+        describe(error),
+        entry.hash ?? "",
+      );
+    }
+  }
+
+  /** Records the outcome of one settle attempt in the ledger and returns it. */
+  private finish(
+    key: string,
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+    validBefore: bigint,
+    result: SettleResponse,
+    context: {
+      readonly auth: ExactEIP3009Payload & { signature: Hex };
+      readonly terms: OpenerTerms;
+      readonly opener: Address;
+    },
+  ): SettleResponse {
+    if (result.success) {
+      // THE one success for this authorization. Nothing succeeds again.
+      this.ledger.set(key, {
+        state: "final",
+        validBefore,
+        hash: result.transaction as Hex,
+      });
+      return result;
+    }
+    if (result.errorReason === OpenerInvalidReason.settlementPending) {
+      this.ledger.set(key, {
+        state: "pending",
+        validBefore,
+        hash: result.transaction as Hex,
+        payload,
+        requirements,
+        auth: context.auth,
+        terms: context.terms,
+        opener: context.opener,
+      });
+      return result;
+    }
+    if (result.errorReason === OpenerInvalidReason.transactionReverted) {
+      // A reverted deployAndSettle consumed nothing (the whole call reverts),
+      // so the authorization may be settled again.
+      this.ledger.delete(key);
+      return result;
+    }
+    // Mined but not the expected stream, or anything else terminal: block.
+    this.ledger.set(key, {
+      state: "final",
+      validBefore,
+      hash: (result.transaction as Hex) || "",
+    });
+    return result;
+  }
+
+  /**
+   * Simulate + broadcast `deployAndSettle`, one at a time. Concurrent
+   * submissions from one relayer would otherwise race for the same account
+   * nonce and all but one would fail after the upstream already did the work.
+   */
+  private submitSerialized(
+    auth: ExactEIP3009Payload & { signature: Hex },
+    terms: OpenerTerms,
+  ): Promise<Hex> {
+    const run = async (): Promise<Hex> => {
+      const { request } = await this.config.publicClient.simulateContract({
+        account: this.config.walletClient.account,
+        address: this.config.factoryAddress,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "deployAndSettle",
+        args: [termsTuple(terms), authorizationTuple(auth)],
+      });
+      return this.config.walletClient.writeContract({
+        ...request,
+        chain: this.config.walletClient.chain ?? null,
+      } as Parameters<typeof this.config.walletClient.writeContract>[0]);
+    };
+    return this.relayerQueue.run(run);
+  }
+
+  /** chain + asset + payer + authorization nonce, or undefined if unparseable. */
+  private ledgerKey(payload: PaymentPayload): string | undefined {
+    const auth = eip3009(payload);
+    const asset = payload.accepted?.asset;
+    if (auth === undefined || typeof asset !== "string") return undefined;
+    return [
+      this.chainId,
+      asset.toLowerCase(),
+      auth.authorization.from.toLowerCase(),
+      auth.authorization.nonce.toLowerCase(),
+    ].join(":");
+  }
+
+  /**
+   * Drops entries whose authorization can no longer be settled by anyone
+   * (past `validBefore` plus a grace). Never drops an in-flight entry.
+   */
+  private pruneLedger(): void {
+    const now = BigInt(this.now());
+    for (const [key, entry] of this.ledger) {
+      if (
+        entry.state !== "in-flight" &&
+        entry.validBefore + LEDGER_GRACE_SECONDS < now
+      ) {
+        this.ledger.delete(key);
+      }
+    }
+  }
+
+  private async awaitSettlement(
+    hash: Hex,
+    auth: ExactEIP3009Payload & { signature: Hex },
+    terms: OpenerTerms,
+    opener: Address,
+    network: Network,
+  ): Promise<SettleResponse> {
+    const payer = getAddress(auth.authorization.from);
+    let receipt;
+    try {
+      receipt = await this.config.publicClient.waitForTransactionReceipt({
+        hash,
+        timeout: this.receiptTimeoutMs,
+      });
+    } catch (error) {
+      // Broadcast but unconfirmed: keep the pending entry so a retry
+      // reconciles against this hash. Never success without a receipt.
+      return failure(
+        OpenerInvalidReason.settlementPending,
+        network,
+        payer,
+        describe(error),
+        hash,
+      );
+    }
+    if (receipt.status !== "success") {
+      return failure(
+        OpenerInvalidReason.transactionReverted,
+        network,
+        payer,
+        "deployAndSettle reverted on-chain",
+        hash,
+      );
+    }
+    const opened = findStreamOpened(
+      receipt.logs,
+      opener,
+      getAddress(this.config.escrowAddress),
+      auth,
+      terms,
+    );
+    if (opened === undefined) {
+      return failure(
+        OpenerInvalidReason.streamEventMismatch,
+        network,
+        payer,
+        "the mined receipt does not show the expected stream",
+        hash,
+      );
+    }
+    return {
+      success: true,
+      transaction: hash,
+      network,
+      payer,
+      amount: auth.authorization.value,
+      extra: {
+        [OPENER_EXTRA_KEY]: {
+          streamId: opened.streamId,
+          opener,
+          escrow: getAddress(this.config.escrowAddress),
+          deposit: auth.authorization.value,
+          ratePerSecond: terms.ratePerSecond.toString(),
+          // A JSON NUMBER: the SDK buyer (payWithX402) validates it as one.
+          expiresAt: Number(opened.expiresAt),
+        },
+      },
+    };
+  }
+
+  /** Every Metrik check plus the stock verifier. Cheapest, most local first. */
+  private async check(
+    payload: PaymentPayload,
+    requirements: PaymentRequirements,
+    context: FacilitatorContext | undefined,
+  ): Promise<
+    | {
+        readonly ok: true;
+        readonly auth: ExactEIP3009Payload & { signature: Hex };
+        readonly terms: OpenerTerms;
+        readonly opener: Address;
+      }
+    | { readonly ok: false; readonly response: VerifyResponse }
+  > {
+    const payer = payerOf(payload);
+    const refuse = (reason: string, message?: string) =>
+      ({ ok: false, response: invalid(reason, message, payer) }) as const;
+
+    if (payload.x402Version !== 2) {
+      return refuse(OpenerInvalidReason.unsupportedVersion);
+    }
+    if (requirements.scheme !== OPENER_SCHEME) {
+      return refuse(OpenerInvalidReason.unsupportedScheme);
+    }
+    if (
+      requirements.network !== this.config.network ||
+      payload.accepted?.network !== this.config.network
+    ) {
+      return refuse(OpenerInvalidReason.unsupportedNetwork);
+    }
+    // The payer signed against `accepted`; settle exactly that, nothing else.
+    if (!deepEqual(payload.accepted, requirements)) {
+      return refuse(OpenerInvalidReason.acceptedMismatch);
+    }
+    const method = requirements.extra?.assetTransferMethod;
+    if (method !== undefined && method !== "eip3009") {
+      return refuse(OpenerInvalidReason.unsupportedAssetTransferMethod);
+    }
+    const auth = eip3009(payload);
+    if (auth === undefined) {
+      return refuse(OpenerInvalidReason.unsupportedAssetTransferMethod);
+    }
+    if (auth.signature === undefined || !isHex(auth.signature)) {
+      return refuse(OpenerInvalidReason.missingSignature);
+    }
+    if (isErc6492Signature(auth.signature)) {
+      return refuse(
+        OpenerInvalidReason.erc6492Unsupported,
+        "ERC-6492 (counterfactual smart wallet) signatures cannot be settled through the stream opener; deploy the wallet first",
+      );
+    }
+    const binding = this.binding;
+    if (binding === undefined) {
+      return refuse(
+        OpenerInvalidReason.verifyError,
+        "facilitator not initialized",
+      );
+    }
+    if (
+      !isAddress(requirements.asset) ||
+      !this.allowlist.has(requirements.asset.toLowerCase()) ||
+      getAddress(requirements.asset) !== binding.usdc
+    ) {
+      return refuse(OpenerInvalidReason.assetNotAllowed);
+    }
+
+    let terms: OpenerTerms;
+    let factory: Address;
+    try {
+      ({ terms, factory } = termsFromExtra(requirements.extra));
+    } catch (error) {
+      return refuse(OpenerInvalidReason.invalidTerms, describe(error));
+    }
+    if (factory !== binding.factory) {
+      return refuse(OpenerInvalidReason.factoryMismatch);
+    }
+
+    let amount: bigint;
+    try {
+      amount = parseUintString(requirements.amount, "amount");
+    } catch (error) {
+      return refuse(OpenerInvalidReason.invalidAmount, describe(error));
+    }
+    if (amount <= 0n) {
+      return refuse(OpenerInvalidReason.invalidAmount, "amount must be > 0");
+    }
+    if (amount < this.minAmount) {
+      return refuse(
+        OpenerInvalidReason.amountBelowMinimum,
+        `amount ${amount} is below this facilitator's minimum ${this.minAmount}`,
+      );
+    }
+    if (amount > maxEarnable(terms)) {
+      return refuse(OpenerInvalidReason.amountExceedsTerms);
+    }
+
+    const predicted = await this.config.publicClient.readContract({
+      address: binding.factory,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "predict",
+      args: [termsTuple(terms)],
+    });
+    if (
+      !isAddress(requirements.payTo) ||
+      getAddress(requirements.payTo) !== getAddress(predicted)
+    ) {
+      return refuse(OpenerInvalidReason.payToMismatch);
+    }
+
+    const listing = await this.config.listingResolver.resolve(terms);
+    if (!listing.ok) {
+      const reason = {
+        "listing-registry-unavailable": OpenerInvalidReason.listingUnavailable,
+        "listing-not-found": OpenerInvalidReason.listingNotFound,
+        "listing-ambiguous": OpenerInvalidReason.listingAmbiguous,
+        "listing-rate-out-of-bounds":
+          OpenerInvalidReason.listingRateOutOfBounds,
+      }[listing.reason];
+      return refuse(reason, listing.message);
+    }
+
+    // Standard exact checks: signature, to == payTo, value == amount, window,
+    // asset contract, and a simulation of the EIP-3009 transfer itself.
+    const stock = await this.stock.verify(payload, requirements, context);
+    if (!stock.isValid) {
+      return { ok: false, response: stock };
+    }
+
+    const signed = auth as ExactEIP3009Payload & { signature: Hex };
+    try {
+      await this.config.publicClient.simulateContract({
+        account: this.config.walletClient.account,
+        address: binding.factory,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "deployAndSettle",
+        args: [termsTuple(terms), authorizationTuple(signed)],
+      });
+    } catch (error) {
+      return refuse(OpenerInvalidReason.simulationFailed, revertReason(error));
+    }
+
+    return { ok: true, auth: signed, terms, opener: getAddress(predicted) };
+  }
+}
+
+function authorizationTuple(auth: ExactEIP3009Payload & { signature: Hex }): {
+  readonly from: Address;
+  readonly value: bigint;
+  readonly validAfter: bigint;
+  readonly validBefore: bigint;
+  readonly nonce: Hex;
+  readonly signature: Hex;
+} {
+  return {
+    from: getAddress(auth.authorization.from),
+    value: BigInt(auth.authorization.value),
+    validAfter: BigInt(auth.authorization.validAfter),
+    validBefore: BigInt(auth.authorization.validBefore),
+    nonce: auth.authorization.nonce,
+    signature: auth.signature,
+  };
+}
+
+/**
+ * Finds the pair of events a genuine opener settlement emits in ONE receipt:
+ * the escrow's `StreamOpened` with `buyer == opener` and exactly these terms,
+ * and the opener's `StreamOpenedFor` binding that stream to this payer, nonce
+ * and amount.
+ */
+function findStreamOpened(
+  logs: readonly Log[],
+  opener: Address,
+  escrow: Address,
+  auth: ExactEIP3009Payload,
+  terms: OpenerTerms,
+): { readonly streamId: Hex; readonly expiresAt: bigint } | undefined {
+  const value = BigInt(auth.authorization.value);
+  const payer = getAddress(auth.authorization.from);
+  const escrowStreams = new Map<string, bigint>();
+  for (const log of logs) {
+    if (getAddress(log.address) !== escrow) continue;
+    try {
+      const decoded = decodeEventLog({
+        abi: streamEscrowV2Abi,
+        data: log.data,
+        topics: log.topics,
+      });
+      if (decoded.eventName !== "StreamOpened") continue;
+      const args = decoded.args as unknown as {
+        streamId: Hex;
+        buyer: Address;
+        operator: Address;
+        serviceRef: Hex;
+        deposit: bigint;
+        ratePerSecond: bigint;
+        expiresAt: bigint;
+      };
+      if (
+        getAddress(args.buyer) === opener &&
+        getAddress(args.operator) === getAddress(terms.operator) &&
+        args.serviceRef.toLowerCase() === terms.serviceRef.toLowerCase() &&
+        args.deposit === value &&
+        args.ratePerSecond === terms.ratePerSecond
+      ) {
+        escrowStreams.set(args.streamId.toLowerCase(), BigInt(args.expiresAt));
+      }
+    } catch {
+      continue;
+    }
+  }
+  for (const log of logs) {
+    if (getAddress(log.address) !== opener) continue;
+    try {
+      const decoded = decodeEventLog({
+        abi: x402StreamOpenerAbi,
+        data: log.data,
+        topics: log.topics,
+      });
+      if (decoded.eventName !== "StreamOpenedFor") continue;
+      const args = decoded.args;
+      const expiresAt = escrowStreams.get(args.streamId.toLowerCase());
+      if (
+        expiresAt !== undefined &&
+        getAddress(args.payer) === payer &&
+        args.authorizationNonce.toLowerCase() ===
+          auth.authorization.nonce.toLowerCase() &&
+        args.deposit === value
+      ) {
+        return { streamId: args.streamId, expiresAt };
+      }
+    } catch {
+      continue;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Reads an opener facilitator marker out of a `/supported` kind's `extra`, or
+ * `undefined` when the facilitator does not advertise opener settlement.
+ */
+export function readOpenerFacilitatorMarker(
+  extra: Record<string, unknown> | undefined,
+): OpenerFacilitatorMarker | undefined {
+  const raw = extra?.[OPENER_EXTRA_KEY];
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const marker = raw as Record<string, unknown>;
+  if (
+    marker.settlement !== "x402-stream-opener" ||
+    typeof marker.factory !== "string" ||
+    !isAddress(marker.factory) ||
+    typeof marker.escrow !== "string" ||
+    !isAddress(marker.escrow) ||
+    typeof marker.usdc !== "string" ||
+    !isAddress(marker.usdc) ||
+    typeof marker.chainId !== "number" ||
+    typeof marker.minAmount !== "string" ||
+    !/^[1-9]\d*$/.test(marker.minAmount) ||
+    typeof marker.receiptTimeoutSeconds !== "number" ||
+    !Number.isInteger(marker.receiptTimeoutSeconds) ||
+    marker.receiptTimeoutSeconds <= 0
+  ) {
+    return undefined;
+  }
+  return {
+    settlement: "x402-stream-opener",
+    factory: getAddress(marker.factory),
+    escrow: getAddress(marker.escrow),
+    usdc: getAddress(marker.usdc),
+    chainId: marker.chainId,
+    minAmount: marker.minAmount,
+    receiptTimeoutSeconds: marker.receiptTimeoutSeconds,
+    ...(marker.refundRelay === true ? { refundRelay: true as const } : {}),
+  };
+}
+
+function eip3009(payload: PaymentPayload): ExactEIP3009Payload | undefined {
+  const inner = payload.payload as unknown;
+  if (typeof inner !== "object" || inner === null) return undefined;
+  const candidate = inner as ExactEvmPayloadV2;
+  if (!isEIP3009Payload(candidate)) return undefined;
+  const authorization = (candidate as ExactEIP3009Payload).authorization;
+  if (
+    typeof authorization !== "object" ||
+    authorization === null ||
+    typeof authorization.from !== "string" ||
+    !isAddress(authorization.from) ||
+    typeof authorization.to !== "string" ||
+    typeof authorization.value !== "string" ||
+    typeof authorization.validAfter !== "string" ||
+    typeof authorization.validBefore !== "string" ||
+    typeof authorization.nonce !== "string" ||
+    !isHex(authorization.nonce) ||
+    authorization.nonce.length !== 66
+  ) {
+    return undefined;
+  }
+  try {
+    parseUintString(authorization.value, "authorization.value");
+    parseUintString(authorization.validAfter, "authorization.validAfter");
+    parseUintString(authorization.validBefore, "authorization.validBefore");
+  } catch {
+    return undefined;
+  }
+  return candidate as ExactEIP3009Payload;
+}
+
+function payerOf(payload: PaymentPayload): string | undefined {
+  const from = (
+    payload.payload as { authorization?: { from?: unknown } } | undefined
+  )?.authorization?.from;
+  return typeof from === "string" && isAddress(from)
+    ? getAddress(from)
+    : undefined;
+}
+
+function invalid(
+  reason: string,
+  message: string | undefined,
+  payer: string | undefined,
+): VerifyResponse {
+  return {
+    isValid: false,
+    invalidReason: reason,
+    ...(message === undefined ? {} : { invalidMessage: message }),
+    ...(payer === undefined ? {} : { payer }),
+  };
+}
+
+function failure(
+  reason: string,
+  network: Network,
+  payer: string | undefined,
+  message: string | undefined,
+  transaction = "",
+): SettleResponse {
+  return {
+    success: false,
+    errorReason: reason,
+    ...(message === undefined ? {} : { errorMessage: message }),
+    transaction,
+    network,
+    ...(payer === undefined ? {} : { payer }),
+  };
+}
+
+function refusal(
+  response: VerifyResponse,
+  network: Network,
+  payer: string | undefined,
+): SettleResponse {
+  return {
+    success: false,
+    errorReason: response.invalidReason ?? OpenerInvalidReason.verifyError,
+    ...(response.invalidMessage === undefined
+      ? {}
+      : { errorMessage: response.invalidMessage }),
+    transaction: "",
+    network,
+    ...(payer === undefined ? {} : { payer }),
+  };
+}
+
+function revertReason(error: unknown): string {
+  if (error instanceof BaseError) {
+    const reverted = error.walk(
+      (cause) => cause instanceof ContractFunctionRevertedError,
+    );
+    if (reverted instanceof ContractFunctionRevertedError) {
+      return (
+        reverted.data?.errorName ?? reverted.reason ?? reverted.shortMessage
+      );
+    }
+    return error.shortMessage;
+  }
+  return describe(error);
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}