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

package/src/mcp/x402-tools.ts

@@ -12,7 +12,13 @@ import {
   verifyMandateOwnerSignature,
   type SignedSpendMandate,
 } from "../mandates/mandate.js";
-import { keccak256, toHex } from "viem";
+import {
+  createPublicClient,
+  http,
+  keccak256,
+  toHex,
+  type PublicClient,
+} from "viem";
 
 import {
   assertOutboundUrlAllowed,
@@ -39,11 +45,11 @@ import type {
  */
 
 export const X402_PAY_TOOL_DESCRIPTION =
-  "Pay an x402 endpoint (HTTP 402 Payment Required, x402 v2 'exact') and return its response. A Metrik x402 seller quotes a payment that opens an escrow STREAM with deposit = price; the seller earns ratePerSecond x VERIFIED seconds, capped at the deposit, and the unearned remainder stays recoverable by this server's wallet. Subject to the agent's spend mandate (price vs per-stream and total caps, rate, duration, operator), checked BEFORE anything is signed. Refunds are NOT automatic: use refund_status and refund with the returned streamId.";
+  "Pay an x402 endpoint (HTTP 402 Payment Required, x402 v2 'exact') and return its response. A Metrik x402 seller quotes a payment that opens an escrow STREAM; the seller earns ratePerSecond x VERIFIED seconds, capped at the deposit, and the unearned remainder stays recoverable by this server's wallet. An UPFRONT ('minimum charge') quote splits the price: upfrontAmount is a NON-REFUNDABLE per-call charge paid to the seller at settlement, and only price - upfrontAmount is escrowed and refundable; when upfrontAmount == price no stream opens at all (streamId null, nothing to refund). Subject to the agent's spend mandate (the WHOLE price vs per-stream and total caps, rate, duration, operator) and a cap on the non-refundable part (maxUpfrontAmountUsdc, default 0.10 USDC), checked BEFORE anything is signed. Refunds are NOT automatic: use refund_status and refund with the returned streamId.";
 export const REFUND_STATUS_TOOL_DESCRIPTION =
-  "Read the refund state of a stream this server paid for over x402, from the seller's gasless refund relay: whether it is running, what is reclaimable, and the next step (close / wait / reclaim). Moves no funds.";
+  "Read the refund state of a stream this server paid for over x402, from the seller's gasless refund relay: whether it is running, what is reclaimable, and the next step (close / wait / reclaim). An upfront-only payment (no stream) has nothing to refund. Moves no funds.";
 export const REFUND_TOOL_DESCRIPTION =
-  "Recover the unearned part of an x402 payment through the seller's gasless refund relay: close=true stops the stream (this wallet signs the opener's Close; the relay pays the gas), reclaim=true sends the permissionless reclaim (the refund always goes to the payer). Nothing is refunded automatically; reclaim waits for the settlement window and may say when to retry.";
+  "Recover the unearned part of an x402 payment through the seller's gasless refund relay: close=true stops the stream (this wallet signs the opener's Close; the relay pays the gas), reclaim=true sends the permissionless reclaim (the refund always goes to the payer). Only the escrowed part can come back: an upfront charge is final, and an upfront-only payment has nothing to refund. Nothing is refunded automatically; reclaim waits for the settlement window and may say when to retry.";
 
 export interface McpX402Options {
   /** The payer: this server's own wallet (must own the server mandate). */
@@ -108,12 +114,17 @@ export interface McpX402Context {
     readonly refundUrl?: string;
     readonly opener?: `0x${string}`;
     readonly x402Reservation?: boolean;
+    /** Not a stream: a settled upfront-only charge (counted spend, nothing to refund). */
+    readonly x402Charge?: "upfront-only";
+    /** The non-refundable part of the payment (the upfront charge), base units. */
+    readonly nonRefundableUsdc?: bigint;
   }) => Promise<void>;
   /** Drop a record (a released reservation). Absent = reservations are kept. */
   readonly removeStream?: (streamId: `0x${string}`) => Promise<void>;
   readonly findStream: (streamId: `0x${string}`) => Promise<{
     readonly refundUrl?: string;
     readonly opener?: `0x${string}`;
+    readonly x402Charge?: "upfront-only";
   } | null>;
   readonly now: () => number;
   readonly ok: (
@@ -167,8 +178,17 @@ const x402PaySchema = {
     .describe(
       "Refuse a quote the seller can fully earn in fewer verified seconds.",
     ),
+  maxUpfrontAmountUsdc: z
+    .string()
+    .regex(/^(0|[1-9]\d*)$/, "a non-negative integer of USDC base units")
+    .optional()
+    .describe(
+      "Cap on the NON-REFUNDABLE per-call part of an upfront-opener quote, base units. Default 100000 (0.10 USDC); 0 refuses any upfront charge.",
+    ),
 } as const;
 
+const ZERO_STREAM_ID = `0x${"00".repeat(32)}` as const;
+
 const refundSchema = {
   streamId: bytes32Schema,
   refundUrl: z
@@ -232,6 +252,11 @@ export function registerX402Tools(
         ...(target.opener === undefined ? {} : { opener: target.opener }),
         ...(target.fetch === undefined ? {} : { fetch: target.fetch }),
         expectedChainId: ctx.x402.network.chain.id,
+        // Chain access is what lets the SDK read the opener's KIND on-chain and
+        // sign an upfront opener's Close under its own EIP-712 domain; without
+        // it, such a Close is refused.
+        publicClient: refundReader(ctx.x402),
+        network: ctx.x402.network,
       });
     });
 
@@ -304,6 +329,9 @@ export function registerX402Tools(
               ...(args.minDurationSeconds === undefined
                 ? {}
                 : { minDurationSeconds: args.minDurationSeconds }),
+              ...(args.maxUpfrontAmountUsdc === undefined
+                ? {}
+                : { maxUpfrontAmount: BigInt(args.maxUpfrontAmountUsdc) }),
               sdkOptions: { ...ctx.x402.sdkOptions, fetch: guardedFetch },
               ...(ctx.x402.chainReader === undefined
                 ? {}
@@ -327,6 +355,9 @@ export function registerX402Tools(
                   mandateId: signedMandate.mandateId as `0x${string}`,
                   opener: quote.payTo,
                   x402Reservation: true,
+                  ...(quote.upfrontAmount === null || quote.upfrontAmount === 0n
+                    ? {}
+                    : { nonRefundableUsdc: quote.upfrontAmount }),
                 });
               },
             });
@@ -340,7 +371,38 @@ export function registerX402Tools(
             });
           }
           const opener = result.metrikStreamOpener;
-          if (result.paid && opener !== null && result.approved !== null) {
+          const upfrontAmount = result.quote?.upfrontAmount ?? null;
+          if (
+            result.paid &&
+            opener !== null &&
+            opener.streamId === null &&
+            result.approved !== null
+          ) {
+            // Upfront-only: there is NO stream to record or refund. The spend
+            // still counts against the mandate (the whole price is gone), so
+            // the reservation is replaced by a permanent, non-stream charge.
+            await ctx.recordStream({
+              streamId: chargeKey(owner, opener.opener, result),
+              buyer: owner,
+              operator: result.approved.operator,
+              serviceRef:
+                result.quote?.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+              budgetUsdc: result.approved.budgetUsdc,
+              ratePerSecondUsdc: result.approved.ratePerSecondUsdc,
+              maxDurationSeconds: result.approved.maxDurationSeconds,
+              openedAtSeconds: nowSeconds,
+              mandateId: signedMandate.mandateId as `0x${string}`,
+              opener: opener.opener,
+              x402Charge: "upfront-only",
+              nonRefundableUsdc: result.approved.budgetUsdc,
+            });
+            await release();
+          } else if (
+            result.paid &&
+            opener !== null &&
+            opener.streamId !== null &&
+            result.approved !== null
+          ) {
             // Replace the reservation with the real stream (same amount).
             await ctx.recordStream({
               streamId: opener.streamId,
@@ -357,6 +419,9 @@ export function registerX402Tools(
                 ? {}
                 : { refundUrl: opener.refundUrl }),
               opener: opener.opener,
+              ...(upfrontAmount === null || upfrontAmount === 0n
+                ? {}
+                : { nonRefundableUsdc: upfrontAmount }),
             });
             await release();
           } else if (!result.paid) {
@@ -386,10 +451,26 @@ export function registerX402Tools(
             ratePerSecondUsdc: opener?.ratePerSecond?.toString() ?? null,
             expiresAt: opener?.expiresAt ?? null,
             minEarnSeconds: result.quote?.minEarnSeconds?.toString() ?? null,
+            openerKind: result.quote?.openerKind ?? null,
+            priceUsdc: result.quote?.amount.toString() ?? null,
+            nonRefundableUsdc: upfrontAmount?.toString() ?? null,
+            refundableUsdc: result.quote?.refundableAmount?.toString() ?? null,
+            upfrontFeeUsdc: opener?.upfrontFee?.toString() ?? null,
+            upfrontOnly: opener?.upfrontOnly ?? false,
             refundIsAutomatic: false,
           };
+          if (opener !== null && opener.streamId === null) {
+            return ctx.ok(
+              `paid ${result.quote?.amount.toString() ?? "?"} USDC base units as an UPFRONT-ONLY charge; HTTP ${result.response.status}. The whole price was a non-refundable per-call charge paid to the seller at settlement: no stream was opened, the payment is final and there is nothing to refund.`,
+              structured,
+            );
+          }
+          const split =
+            upfrontAmount !== null && upfrontAmount > 0n
+              ? ` Of the ${result.quote?.amount.toString() ?? "?"} paid, ${upfrontAmount.toString()} was a NON-REFUNDABLE per-call charge (final); only the ${opener?.deposit?.toString() ?? "?"} escrowed can come back.`
+              : "";
           return ctx.ok(
-            `paid ${opener?.deposit?.toString() ?? "?"} USDC base units into stream ${opener?.streamId ?? "?"}; HTTP ${result.response.status}. The seller earns only for VERIFIED seconds; the unearned remainder is NOT refunded automatically — call refund (or refund_status) with this streamId.`,
+            `paid ${opener?.deposit?.toString() ?? "?"} USDC base units into stream ${opener?.streamId ?? "?"}; HTTP ${result.response.status}.${split} The seller earns only for VERIFIED seconds; the unearned remainder is NOT refunded automatically — call refund (or refund_status) with this streamId.`,
             structured,
           );
         });
@@ -405,9 +486,21 @@ export function registerX402Tools(
   const bind = async (args: {
     streamId: string;
     refundUrl?: string | undefined;
-  }): Promise<RefundClient | { readonly error: string }> => {
+  }): Promise<
+    | RefundClient
+    | { readonly error: string }
+    | { readonly nothingToRefund: string }
+  > => {
     const streamId = args.streamId.toLowerCase() as `0x${string}`;
+    // Stream id 0 is an upfront-only payment: nothing was escrowed. Never
+    // contact a relay or sign anything for it.
+    if (streamId === ZERO_STREAM_ID) {
+      return { nothingToRefund: streamId };
+    }
     const record = await ctx.findStream(streamId);
+    if (record?.x402Charge === "upfront-only") {
+      return { nothingToRefund: streamId };
+    }
     const refundUrl = args.refundUrl ?? record?.refundUrl;
     if (refundUrl === undefined) {
       return {
@@ -449,9 +542,13 @@ export function registerX402Tools(
       try {
         const refunds = await bind(args);
         if ("error" in refunds) return ctx.fail(refunds.error);
+        if ("nothingToRefund" in refunds) return nothingToRefund(ctx, args);
         const status = await refunds.status();
         return ctx.ok(describeStatus(status), serializeStatus(status));
       } catch (error) {
+        if (error instanceof Error && error.name === "NothingToRefundError") {
+          return nothingToRefund(ctx, args);
+        }
         return explainRefundError(ctx, error);
       }
     },
@@ -474,6 +571,7 @@ export function registerX402Tools(
       try {
         const refunds = await bind(args);
         if ("error" in refunds) return ctx.fail(refunds.error);
+        if ("nothingToRefund" in refunds) return nothingToRefund(ctx, args);
         let closeResult: RefundRelayResult | null = null;
         if (args.close === true) {
           // Buyer recovery, authorized on the mandate owner's signature alone
@@ -513,12 +611,53 @@ export function registerX402Tools(
           },
         );
       } catch (error) {
+        if (error instanceof Error && error.name === "NothingToRefundError") {
+          return nothingToRefund(ctx, args);
+        }
         return explainRefundError(ctx, error);
       }
     },
   );
 }
 
+/** Upfront-only payments: a finished, successful answer — not an error. */
+function nothingToRefund(ctx: McpX402Context, args: { streamId: string }) {
+  return ctx.ok(
+    "nothing to refund: this was an upfront-only payment — the whole price was a non-refundable per-call charge paid to the seller at settlement, no stream was opened and nothing was escrowed. Nothing was requested, signed or sent.",
+    {
+      streamId: args.streamId.toLowerCase(),
+      nothingToRefund: true,
+      upfrontOnly: true,
+      refundIsAutomatic: false,
+    },
+  );
+}
+
+/** Registry key of a settled upfront-only charge (not an escrow stream id). */
+function chargeKey(
+  owner: `0x${string}`,
+  opener: `0x${string}`,
+  result: PayX402WithMandateResult,
+): `0x${string}` {
+  return keccak256(
+    toHex(
+      `x402-upfront-charge:${owner}:${opener}:${result.authorization?.nonce ?? crypto.randomUUID()}`,
+    ),
+  );
+}
+
+/** Read-only chain access for the SDK refund client's opener-kind check. */
+function refundReader(options: McpX402Options): PublicClient {
+  return (
+    options.sdkOptions?.publicClient ??
+    (createPublicClient({
+      chain: options.network.chain,
+      transport:
+        options.sdkOptions?.transport ?? http(options.network.rpcUrls[0]),
+    }) as PublicClient)
+  );
+}
+
 function serializeStatus(status: RefundStatus): Record<string, unknown> {
   return {
     streamId: status.streamId,
@@ -561,6 +700,28 @@ async function settleFailure(
     const post = error as X402PostSignatureError;
     if (post.releasable) {
       await state.release();
+    } else if (post.upfrontOnly && post.state === "used") {
+      // Settled as an upfront-only charge: no stream to record, but the spend
+      // is real and stays counted — as a non-stream charge.
+      await ctx.recordStream({
+        streamId: keccak256(
+          toHex(
+            `x402-upfront-charge:${state.owner}:${post.opener}:${post.authorization?.nonce ?? crypto.randomUUID()}`,
+          ),
+        ),
+        buyer: state.owner,
+        operator: post.approved.operator,
+        serviceRef: post.quote.serviceRef ?? (`0x${"00".repeat(32)}` as const),
+        budgetUsdc: post.approved.budgetUsdc,
+        ratePerSecondUsdc: post.approved.ratePerSecondUsdc,
+        maxDurationSeconds: post.approved.maxDurationSeconds,
+        openedAtSeconds: state.nowSeconds,
+        mandateId: state.mandateId,
+        opener: post.opener,
+        x402Charge: "upfront-only",
+        nonRefundableUsdc: post.approved.budgetUsdc,
+      });
+      await state.release();
     } else if (post.streamId !== null) {
       await ctx.recordStream({
         streamId: post.streamId,
@@ -573,6 +734,9 @@ async function settleFailure(
         openedAtSeconds: state.nowSeconds,
         mandateId: state.mandateId,
         opener: post.opener,
+        ...(post.quote.upfrontAmount === null || post.quote.upfrontAmount === 0n
+          ? {}
+          : { nonRefundableUsdc: post.quote.upfrontAmount }),
       });
       await state.release();
     }

package/src/sdk/client.ts

@@ -87,6 +87,11 @@ export interface AgentSdkClient {
   claimable(streamId: `0x${string}`): Promise<bigint>;
   reclaimable(streamId: `0x${string}`): Promise<bigint>;
   claim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
+  /**
+   * StreamEscrowV3 only: redeem the on-chain proven high-water without a proof.
+   * Optional so an existing custom SDK client keeps compiling.
+   */
+  claimProven?(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   close(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   reclaim(streamId: `0x${string}`): Promise<StreamProofTransactionResult>;
   /**
@@ -192,6 +197,26 @@ export class VerifiedStreamAgentClient implements VerifiedStreamAgentOpener {
     return await this.sdkClient.claim(input.streamId);
   }
 
+  /**
+   * Operator-only, StreamEscrowV3 only: redeem the stream's on-chain proven
+   * high-water (`claimProven`) without a fresh proof. Authorized exactly like
+   * {@link claimStream} — it pays the same party from the same escrow, only an
+   * amount already proven against a signed checkpoint root and recorded
+   * on-chain, so it can never pay more than a proof claim could have.
+   */
+  async claimProvenStream(
+    input: MandateAuthorizedStreamActionInput,
+  ): Promise<StreamProofTransactionResult> {
+    const claimProven = this.sdkClient.claimProven?.bind(this.sdkClient);
+    if (claimProven === undefined) {
+      throw new Error(
+        "this SDK client cannot send claimProven (StreamEscrowV3 only)",
+      );
+    }
+    await this.authorizeExistingStreamAction(input);
+    return await claimProven(input.streamId);
+  }
+
   async closeStream(
     input: MandateAuthorizedStreamActionInput,
   ): Promise<StreamProofTransactionResult> {

package/src/x402-buyer/pay.ts

@@ -39,6 +39,15 @@ import {
  * | `maxDurationSeconds`   | `maxDuration` (the stream's window)              |
  * | `allowedOperators`     | `operator` (who the stream pays)                 |
  *
+ * An UPFRONT ("minimum charge") opener quote is mapped the same way, with
+ * `budgetUsdc = price` — the WHOLE payment, of which `upfrontAmount` is
+ * non-refundable (paid to the seller at settlement) and only the rest is
+ * escrowed. So the per-stream and total caps always count the upfront part as
+ * spent, and nothing a refund returns is ever credited back. Its size is also
+ * capped separately, before signing, by the SDK's `maxUpfrontAmount` (default
+ * 0.10 USDC; pass {@link PayX402WithMandateInput.maxUpfrontAmount} to tighten
+ * it, `0n` to refuse every upfront charge).
+ *
  * The check runs inside the SDK's `onQuote` hook — after every SDK protection
  * (scheme, network, USDC domain, EIP-3009 only, registered factory, on-chain
  * `predict`, authorization lifetime) and BEFORE anything is signed — so a
@@ -117,6 +126,12 @@ export interface PayX402WithMandateInput {
   readonly maxRatePerSecond?: bigint;
   /** Refuse a quote the seller can fully earn in fewer verified seconds. */
   readonly minDurationSeconds?: number;
+  /**
+   * Ceiling on the NON-REFUNDABLE upfront part of an upfront-opener quote, base
+   * units (the SDK's `maxUpfrontAmount`). Default the SDK's 0.10 USDC; `0n`
+   * refuses any upfront charge. Never above the price ceiling in effect.
+   */
+  readonly maxUpfrontAmount?: bigint;
   /** Passed through to the SDK (transport, fetch, publicClient, ...). */
   readonly sdkOptions?: Pick<
     PayWithX402Options,
@@ -179,6 +194,12 @@ export class X402PostSignatureError extends Error {
   /** The stream the payment opened, when it could be identified. */
   readonly streamId: `0x${string}` | null;
   readonly opener: `0x${string}`;
+  /**
+   * `true` when the chain shows (or the signed quote implies) an UPFRONT-ONLY
+   * payment: no stream, the whole price was a non-refundable charge, nothing
+   * to recover.
+   */
+  readonly upfrontOnly: boolean;
 
   constructor(context: {
     readonly state: X402PostSignatureState;
@@ -186,11 +207,16 @@ export class X402PostSignatureError extends Error {
     readonly quote: X402QuoteSummary;
     readonly authorization: SignedTransferAuthorization | null;
     readonly streamId: `0x${string}` | null;
+    readonly upfrontOnly?: boolean;
     readonly cause: unknown;
   }) {
+    const upfrontOnly =
+      context.upfrontOnly === true || context.quote.upfrontOnly === true;
     const what =
       context.state === "used"
-        ? `the payment SETTLED (the authorization was used)${context.streamId === null ? ", but its stream could not be identified" : ` into stream ${context.streamId}`}`
+        ? upfrontOnly
+          ? "the payment SETTLED (the authorization was used) as an UPFRONT-ONLY charge: the whole price went to the seller, no stream was opened and there is nothing to refund"
+          : `the payment SETTLED (the authorization was used)${context.streamId === null ? ", but its stream could not be identified" : ` into stream ${context.streamId}`}`
         : context.state === "possibly-used"
           ? "the payment MAY HAVE SETTLED: whether the authorization was used could not be established, so treat it as spent"
           : context.state === "unused-but-valid"
@@ -207,6 +233,7 @@ export class X402PostSignatureError extends Error {
     this.authorization = context.authorization;
     this.streamId = context.streamId;
     this.opener = getAddress(context.quote.payTo);
+    this.upfrontOnly = upfrontOnly;
   }
 
   /** Only an authorization that provably can never move funds frees its reservation. */
@@ -322,6 +349,8 @@ export async function payX402WithMandate(
     mandate.maxRatePerSecondUsdc,
     input.maxRatePerSecond,
   );
+  // A negative maxUpfrontAmount is refused by the SDK (InvalidInputError)
+  // before the seller is contacted.
 
   // 3. The per-quote mandate check, before signing.
   let denial: X402MandateDeniedError | null = null;
@@ -357,6 +386,9 @@ export async function payX402WithMandate(
       network: input.network,
       maxAmount,
       maxRatePerSecond,
+      ...(input.maxUpfrontAmount === undefined
+        ? {}
+        : { maxUpfrontAmount: smaller(input.maxUpfrontAmount, maxAmount) }),
       ...(input.minDurationSeconds === undefined
         ? {}
         : { minDurationSeconds: input.minDurationSeconds }),
@@ -440,6 +472,8 @@ async function classifyPostSignatureFailure(
     typeof sdkError.authorizationUsed === "boolean"
       ? sdkError.authorizationUsed
       : null;
+  let upfrontOnly =
+    (sdkError as { readonly upfrontOnly?: boolean }).upfrontOnly === true;
   let streamId: `0x${string}` | null =
     typeof sdkError.streamId === "string" &&
     /^0x[0-9a-fA-F]{64}$/.test(sdkError.streamId)
@@ -477,16 +511,19 @@ async function classifyPostSignatureFailure(
           publicClient: reader as PublicClient,
         });
         streamId = recovery.streamId;
+        // An upfront-only payment opens no stream: the opener's
+        // UpfrontCharged (streamId 0), read on-chain, proves it was used.
+        if (recovery.upfrontOnly) upfrontOnly = true;
       } catch {
         streamId = null;
       }
-      if (streamId !== null) used = true;
+      if (streamId !== null || upfrontOnly) used = true;
     }
   }
 
   const nowSeconds = BigInt(Math.floor(Date.now() / 1000));
   const state: X402PostSignatureState =
-    streamId !== null || used === true
+    streamId !== null || upfrontOnly || used === true
       ? "used"
       : used === false && authorization !== null
         ? authorization.validBefore <= nowSeconds
@@ -499,6 +536,7 @@ async function classifyPostSignatureFailure(
     quote: context.quote,
     authorization,
     streamId,
+    upfrontOnly,
     cause: context.error,
   });
 }

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

@@ -15,7 +15,10 @@ async function main(): Promise<void> {
   console.error(
     `[metrik-opener-facilitator] listening on port ${server.boundPort} — chain ${binding.chainId}, ` +
       `factory ${binding.factory}, escrow ${binding.escrow}, token ${binding.usdc}, relayer ${binding.relayer}. ` +
-      "Every payment settles into a StreamEscrowV2 stream via deployAndSettle; nothing is ever transferred to payTo directly. " +
+      (binding.upfront === undefined
+        ? "Upfront (minimum-charge) opener: OFF. "
+        : `Upfront (minimum-charge) opener factory ${binding.upfront.factory} (implementation ${binding.upfront.implementation}): ON — its non-refundable upfrontAmount is paid to the seller at settlement, only price - upfrontAmount is escrowed and refundable. `) +
+      "Every payment settles through the opener factory's deployAndSettle (an escrow stream for the metered part); nothing is ever transferred to payTo directly. " +
       (server.refundRelayEnabled
         ? "Gasless refund relay ON at /streams/:streamId (close needs the payer's signature; reclaim is permissionless and pays only payerOf). There is no automatic refund: nothing is sent unless an endpoint is called."
         : "Gasless refund relay OFF (METRIK_OPENER_FACILITATOR_REFUND_RELAY=0): a gateway will refuse to quote through this facilitator."),

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

@@ -7,7 +7,7 @@ import {
 } from "node:http";
 import type { AddressInfo } from "node:net";
 
-import { networkForCaip2 } from "@absol-labs/sdk";
+import { networkForCaip2, networkOpenerFactories } from "@absol-labs/sdk";
 import { x402Facilitator } from "@x402/core/facilitator";
 import type { Network } from "@x402/core/types";
 import {
@@ -470,6 +470,13 @@ export interface OpenerFacilitatorOptions {
   readonly rpcUrl: string;
   readonly relayerPrivateKey: Hex;
   readonly factoryAddress: Address;
+  /**
+   * The `X402UpfrontStreamOpenerFactory` to settle ALSO (same escrow), or
+   * undefined for stream openers only. See {@link resolveUpfrontFactory}.
+   */
+  readonly upfrontFactoryAddress?: Address;
+  /** The implementation the upfront factory must report (the registry's). */
+  readonly upfrontImplementation?: Address;
   readonly escrowAddress: Address;
   readonly assetAllowlist: readonly Address[];
   /** Default: a {@link RegistryListingResolver} on the public registry. */
@@ -528,6 +535,12 @@ export async function buildOpenerFacilitator(
     advertiseRefundRelay: options.refundRelay !== undefined,
     network: options.network,
     factoryAddress: options.factoryAddress,
+    ...(options.upfrontFactoryAddress === undefined
+      ? {}
+      : { upfrontFactoryAddress: options.upfrontFactoryAddress }),
+    ...(options.upfrontImplementation === undefined
+      ? {}
+      : { upfrontImplementation: options.upfrontImplementation }),
     escrowAddress: options.escrowAddress,
     assetAllowlist: options.assetAllowlist,
     publicClient,
@@ -553,6 +566,9 @@ export async function buildOpenerFacilitator(
     refundRelay = new OpenerRefundRelay({
       network: options.network,
       factoryAddress: options.factoryAddress,
+      ...(options.upfrontFactoryAddress === undefined
+        ? {}
+        : { upfrontFactoryAddress: options.upfrontFactoryAddress }),
       escrowAddress: options.escrowAddress,
       oracleUrl: relay.oracleUrl,
       publicClient,
@@ -601,6 +617,10 @@ export interface OpenerFacilitatorEnvConfig {
   readonly authToken: string;
   readonly requireAuthOnVerify: boolean;
   readonly factoryAddress: Address;
+  /** The upfront opener factory also settled, when enabled. */
+  readonly upfrontFactoryAddress?: Address;
+  /** Its expected implementation, when the registry records it. */
+  readonly upfrontImplementation?: Address;
   readonly escrowAddress: Address;
   readonly assetAllowlist: readonly Address[];
   readonly registryUrl: string;
@@ -637,6 +657,12 @@ export interface OpenerRefundRelayEnvConfig {
  *   registry entry; on a network the registry does not know (or one with no
  *   opener factory) each must be given explicitly.
  * - `METRIK_OPENER_FACILITATOR_FACTORY_ADDRESS` — default the network's registered factory.
+ * - `METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS` — the
+ *   `X402UpfrontStreamOpenerFactory` (upfront "minimum charge" listings) settled
+ *   ALONGSIDE the stream factory. Default: the registry's upfront factory for
+ *   the configured escrow, when it records one (Base Sepolia: bound to
+ *   StreamEscrowV3); none otherwise. `off` disables it. It must be bound to the
+ *   same escrow and token, or the facilitator refuses to start.
  * - `METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS` — default the network's registered `StreamEscrowV2`.
  * - `METRIK_OPENER_FACILITATOR_ASSETS` — comma-separated allowlist; default the network's USDC.
  * - `METRIK_OPENER_FACILITATOR_REGISTRY_URL` — default the public listings registry.
@@ -736,6 +762,11 @@ export function parseOpenerFacilitatorEnvConfig(
       "METRIK_OPENER_FACILITATOR_ESCROW_ADDRESS",
     );
   }
+  const upfront = resolveUpfrontFactory(
+    env.METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS,
+    network,
+    escrowAddress,
+  );
   const assetsRaw = env.METRIK_OPENER_FACILITATOR_ASSETS?.trim();
   let assetAllowlist: Address[];
   if (assetsRaw === undefined || assetsRaw.length === 0) {
@@ -805,6 +836,7 @@ export function parseOpenerFacilitatorEnvConfig(
       DEFAULT_SETTLE_RATE_LIMIT_PER_MINUTE,
     ),
     factoryAddress,
+    ...(upfront === undefined ? {} : upfront),
     escrowAddress,
     assetAllowlist,
     registryUrl,
@@ -813,6 +845,68 @@ export function parseOpenerFacilitatorEnvConfig(
   };
 }
 
+/**
+ * The upfront opener factory the facilitator also settles, from
+ * `METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS`: unset = the network
+ * registry's upfront factory OF THE CONFIGURED ESCROW'S deployment (so a
+ * facilitator pinned to a legacy escrow never picks up a factory bound to
+ * another one); `off`/`none`/`0`/`false` = disabled; an address = that factory
+ * (its implementation is pinned only when the registry records it).
+ */
+export function resolveUpfrontFactory(
+  raw: string | undefined,
+  network: Network,
+  escrowAddress: Address,
+):
+  | {
+      readonly upfrontFactoryAddress: Address;
+      readonly upfrontImplementation?: Address;
+    }
+  | undefined {
+  const value = raw?.trim() ?? "";
+  const registered = networkForCaip2(network);
+  const forEscrow =
+    registered === undefined
+      ? undefined
+      : networkOpenerFactories(registered).find(
+          (entry) =>
+            entry.kind === "upfront" &&
+            getAddress(entry.deployment.escrow.address) ===
+              getAddress(escrowAddress),
+        );
+  if (value.length === 0) {
+    if (forEscrow === undefined) return undefined;
+    return {
+      upfrontFactoryAddress: getAddress(forEscrow.address),
+      ...(forEscrow.implementation === null
+        ? {}
+        : { upfrontImplementation: getAddress(forEscrow.implementation) }),
+    };
+  }
+  if (["off", "none", "0", "false", "no"].includes(value.toLowerCase())) {
+    return undefined;
+  }
+  if (!isAddress(value)) {
+    throw new Error(
+      "METRIK_OPENER_FACILITATOR_UPFRONT_FACTORY_ADDRESS must be an EVM address (or off)",
+    );
+  }
+  const known =
+    registered === undefined
+      ? undefined
+      : networkOpenerFactories(registered).find(
+          (entry) =>
+            entry.kind === "upfront" &&
+            getAddress(entry.address) === getAddress(value),
+        );
+  return {
+    upfrontFactoryAddress: getAddress(value),
+    ...(known?.implementation == null
+      ? {}
+      : { upfrontImplementation: getAddress(known.implementation) }),
+  };
+}
+
 function parseRefundRelayEnv(
   env: NodeJS.ProcessEnv,
   network: Network,
@@ -914,6 +1008,12 @@ export async function startOpenerFacilitatorServerFromEnv(
     rpcUrl: config.rpcUrl,
     relayerPrivateKey: config.relayerPrivateKey,
     factoryAddress: config.factoryAddress,
+    ...(config.upfrontFactoryAddress === undefined
+      ? {}
+      : { upfrontFactoryAddress: config.upfrontFactoryAddress }),
+    ...(config.upfrontImplementation === undefined
+      ? {}
+      : { upfrontImplementation: config.upfrontImplementation }),
     escrowAddress: config.escrowAddress,
     assetAllowlist: config.assetAllowlist,
     registryUrl: config.registryUrl,