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

package/src/x402-opener/scheme.ts

@@ -1,4 +1,8 @@
-import { streamEscrowV2Abi } from "@absol-labs/shared";
+import {
+  streamEscrowV2Abi,
+  x402UpfrontStreamOpenerAbi,
+  x402UpfrontStreamOpenerFactoryAbi,
+} from "@absol-labs/shared";
 import type {
   FacilitatorContext,
   Network,
@@ -39,15 +43,30 @@ import type { OperatorSignedListingResolver } from "./listing-resolver.js";
 import { RelayerQueue } from "./relayer-queue.js";
 import {
   chainIdFromNetwork,
+  assertValidUpfrontTerms,
   maxEarnable,
   OPENER_EXTRA_KEY,
   OPENER_SCHEME,
+  OPENER_TERMS_VERSION,
   parseUintString,
   termsFromExtra,
   termsTuple,
+  upfrontRefundable,
+  upfrontTermsTuple,
+  type OpenerKind,
   type OpenerTerms,
+  type UpfrontOpenerTerms,
 } from "./terms.js";
 
+/**
+ * What one checked payment settles: the factory's kind and its terms. An
+ * `"upfront"` payment carries the 6-field terms (price + non-refundable
+ * upfrontAmount); a `"stream"` payment the 4-field ones.
+ */
+export type OpenerSettlementPlan =
+  | { readonly kind: "stream"; readonly terms: OpenerTerms }
+  | { readonly kind: "upfront"; readonly terms: UpfrontOpenerTerms };
+
 /**
  * `MetrikOpenerExactScheme` — an x402 v2 `exact` facilitator scheme that
  * settles every payment INTO a `StreamEscrowV2` stream through the ownerless
@@ -104,6 +123,20 @@ import {
  *
  * Relayer submissions (simulate + write) are serialized so concurrent payers
  * never race for the relayer's account nonce.
+ *
+ * ## The upfront ("minimum charge") opener kind
+ *
+ * With `upfrontFactoryAddress` set, a quote may also name the
+ * `X402UpfrontStreamOpenerFactory` (metrik-contracts#54). Its 6-field terms
+ * add `price` and a non-refundable `upfrontAmount`; the kind is decided by
+ * WHICH configured factory the quote names, never by the wire fields. Verify
+ * additionally requires the factory's own `validateTerms` rules,
+ * `price - upfrontAmount <= rate * maxDuration`, `amount == price` and
+ * `payTo == upfrontFactory.predict(terms)`, and simulates the 6-tuple
+ * `deployAndSettle`. Settle succeeds only on a receipt that shows exactly the
+ * signed split (see {@link MetrikOpenerExactScheme.upfrontSettlement}); an
+ * upfront-only payment (`upfrontAmount == price`) opens no stream and is
+ * reported with `streamId: null`.
  */
 
 /** Reasons this scheme adds to the stock `exact` ones. All fail closed. */
@@ -156,6 +189,19 @@ export interface MetrikOpenerExactSchemeConfig {
   readonly network: Network;
   /** The deployed `X402StreamOpenerFactory`. */
   readonly factoryAddress: Address;
+  /**
+   * The deployed `X402UpfrontStreamOpenerFactory` (metrik-contracts#54), bound
+   * to the SAME escrow. When set, upfront ("minimum charge") payments are
+   * accepted too and `/supported` advertises it as `upfrontOpener`. Unset = the
+   * stream factory only (the pre-upfront behaviour).
+   */
+  readonly upfrontFactoryAddress?: Address;
+  /**
+   * The implementation `upfrontFactoryAddress` must report
+   * (`factory.implementation()`), e.g. the registry's. Checked by
+   * {@link MetrikOpenerExactScheme.init} when given.
+   */
+  readonly upfrontImplementation?: Address;
   /** The `StreamEscrowV2` the factory must point at (checked by {@link init}). */
   readonly escrowAddress: Address;
   /** Settlement tokens this facilitator accepts. Must contain `factory.usdc()`. */
@@ -211,7 +257,7 @@ type LedgerEntry =
       readonly payload: PaymentPayload;
       readonly requirements: PaymentRequirements;
       readonly auth: ExactEIP3009Payload & { signature: Hex };
-      readonly terms: OpenerTerms;
+      readonly plan: OpenerSettlementPlan;
       readonly opener: Address;
     }
   | {
@@ -227,6 +273,19 @@ export interface OpenerFacilitatorBinding {
   readonly escrow: Address;
   readonly usdc: Address;
   readonly relayer: Address;
+  /** The upfront factory, when configured (same escrow and token). */
+  readonly upfront?: {
+    readonly factory: Address;
+    readonly implementation: Address;
+  };
+}
+
+/** The upfront opener kind advertised in the `/supported` marker. */
+export interface UpfrontOpenerMarker {
+  readonly factory: Address;
+  readonly implementation: Address;
+  readonly escrow: Address;
+  readonly termsVersion: typeof OPENER_TERMS_VERSION.upfront;
 }
 
 /**
@@ -251,6 +310,12 @@ export interface OpenerFacilitatorMarker {
    * Absent (read as false) otherwise.
    */
   readonly refundRelay?: true;
+  /**
+   * Present when this facilitator also settles the UPFRONT ("minimum charge")
+   * opener kind. `factory` above stays the stream factory, so a gateway that
+   * predates the upfront kind reads the marker exactly as before.
+   */
+  readonly upfrontOpener?: UpfrontOpenerMarker;
 }
 
 export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
@@ -276,6 +341,22 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
     if (!isAddress(config.escrowAddress)) {
       throw new Error("escrowAddress must be an EVM address");
     }
+    if (
+      config.upfrontFactoryAddress !== undefined &&
+      (!isAddress(config.upfrontFactoryAddress) ||
+        getAddress(config.upfrontFactoryAddress) ===
+          getAddress(config.factoryAddress))
+    ) {
+      throw new Error(
+        "upfrontFactoryAddress must be an EVM address other than factoryAddress",
+      );
+    }
+    if (
+      config.upfrontImplementation !== undefined &&
+      !isAddress(config.upfrontImplementation)
+    ) {
+      throw new Error("upfrontImplementation must be an EVM address");
+    }
     if (config.assetAllowlist.length === 0) {
       throw new Error("assetAllowlist must not be empty");
     }
@@ -372,12 +453,65 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
         `factory settlement token ${factoryUsdc} is not on the asset allowlist`,
       );
     }
+    let upfront: OpenerFacilitatorBinding["upfront"];
+    if (this.config.upfrontFactoryAddress !== undefined) {
+      const upfrontFactory = getAddress(this.config.upfrontFactoryAddress);
+      const upfrontCode = await publicClient.getCode({
+        address: upfrontFactory,
+      });
+      if (upfrontCode === undefined || upfrontCode === "0x") {
+        throw new Error(
+          `no contract at upfront factory address ${upfrontFactory}`,
+        );
+      }
+      const [upEscrow, upUsdc, upImplementation] = await Promise.all([
+        publicClient.readContract({
+          address: upfrontFactory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "escrow",
+        }),
+        publicClient.readContract({
+          address: upfrontFactory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "usdc",
+        }),
+        publicClient.readContract({
+          address: upfrontFactory,
+          abi: x402UpfrontStreamOpenerFactoryAbi,
+          functionName: "implementation",
+        }),
+      ]);
+      if (getAddress(upEscrow) !== getAddress(escrowAddress)) {
+        throw new Error(
+          `upfront factory escrow ${upEscrow} is not the configured escrow ${escrowAddress}`,
+        );
+      }
+      if (getAddress(upUsdc) !== getAddress(factoryUsdc)) {
+        throw new Error(
+          `upfront factory token ${upUsdc} is not the stream factory's ${factoryUsdc}`,
+        );
+      }
+      if (
+        this.config.upfrontImplementation !== undefined &&
+        getAddress(upImplementation) !==
+          getAddress(this.config.upfrontImplementation)
+      ) {
+        throw new Error(
+          `upfront factory implementation ${upImplementation} is not the expected ${this.config.upfrontImplementation}`,
+        );
+      }
+      upfront = {
+        factory: upfrontFactory,
+        implementation: getAddress(upImplementation),
+      };
+    }
     this.binding = {
       chainId: this.chainId,
       factory: getAddress(factoryAddress),
       escrow: getAddress(factoryEscrow),
       usdc: getAddress(factoryUsdc),
       relayer: this.config.walletClient.account.address,
+      ...(upfront === undefined ? {} : { upfront }),
     };
     return this.binding;
   }
@@ -399,6 +533,16 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
       ...(this.config.advertiseRefundRelay === true
         ? { refundRelay: true as const }
         : {}),
+      ...(binding.upfront === undefined
+        ? {}
+        : {
+            upfrontOpener: {
+              factory: binding.upfront.factory,
+              implementation: binding.upfront.implementation,
+              escrow: binding.escrow,
+              termsVersion: OPENER_TERMS_VERSION.upfront,
+            },
+          }),
     };
     return { [OPENER_EXTRA_KEY]: marker };
   }
@@ -500,7 +644,7 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
           await this.awaitSettlement(
             existing.hash,
             existing.auth,
-            existing.terms,
+            existing.plan,
             existing.opener,
             network,
           ),
@@ -536,10 +680,10 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
         return refusal(checked.response, network, payer);
       }
 
-      const { auth, terms, opener } = checked;
+      const { auth, plan, opener } = checked;
       let hash: Hex;
       try {
-        hash = await this.submitSerialized(auth, terms);
+        hash = await this.submitSerialized(auth, plan);
       } catch (error) {
         this.ledger.delete(key);
         return failure(
@@ -555,8 +699,8 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
         payload,
         requirements,
         validBefore,
-        await this.awaitSettlement(hash, auth, terms, opener, network),
-        { auth, terms, opener },
+        await this.awaitSettlement(hash, auth, plan, opener, network),
+        { auth, plan, opener },
       );
     } catch (error) {
       // Unknown state after a possible broadcast: keep the authorization
@@ -585,7 +729,7 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
     result: SettleResponse,
     context: {
       readonly auth: ExactEIP3009Payload & { signature: Hex };
-      readonly terms: OpenerTerms;
+      readonly plan: OpenerSettlementPlan;
       readonly opener: Address;
     },
   ): SettleResponse {
@@ -606,7 +750,7 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
         payload,
         requirements,
         auth: context.auth,
-        terms: context.terms,
+        plan: context.plan,
         opener: context.opener,
       });
       return result;
@@ -633,16 +777,10 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
    */
   private submitSerialized(
     auth: ExactEIP3009Payload & { signature: Hex },
-    terms: OpenerTerms,
+    plan: OpenerSettlementPlan,
   ): 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)],
-      });
+      const { request } = await this.simulateDeployAndSettle(auth, plan);
       return this.config.walletClient.writeContract({
         ...request,
         chain: this.config.walletClient.chain ?? null,
@@ -680,10 +818,41 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
     }
   }
 
+  /**
+   * `eth_call` (simulate) `deployAndSettle` on the factory of the plan's kind:
+   * the 4-tuple stream factory, or the 6-tuple upfront factory.
+   */
+  private async simulateDeployAndSettle(
+    auth: ExactEIP3009Payload & { signature: Hex },
+    plan: OpenerSettlementPlan,
+  ) {
+    const { publicClient, walletClient } = this.config;
+    if (plan.kind === "upfront") {
+      const factory = this.binding?.upfront?.factory;
+      if (factory === undefined) {
+        throw new Error("the upfront opener factory is not configured");
+      }
+      return await publicClient.simulateContract({
+        account: walletClient.account,
+        address: factory,
+        abi: x402UpfrontStreamOpenerFactoryAbi,
+        functionName: "deployAndSettle",
+        args: [upfrontTermsTuple(plan.terms), authorizationTuple(auth)],
+      });
+    }
+    return await publicClient.simulateContract({
+      account: walletClient.account,
+      address: this.config.factoryAddress,
+      abi: x402StreamOpenerFactoryAbi,
+      functionName: "deployAndSettle",
+      args: [termsTuple(plan.terms), authorizationTuple(auth)],
+    });
+  }
+
   private async awaitSettlement(
     hash: Hex,
     auth: ExactEIP3009Payload & { signature: Hex },
-    terms: OpenerTerms,
+    plan: OpenerSettlementPlan,
     opener: Address,
     network: Network,
   ): Promise<SettleResponse> {
@@ -714,12 +883,24 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
         hash,
       );
     }
+    if (plan.kind === "upfront") {
+      return this.upfrontSettlement(
+        receipt.logs,
+        hash,
+        auth,
+        plan.terms,
+        opener,
+        network,
+      );
+    }
+    const terms = plan.terms;
     const opened = findStreamOpened(
       receipt.logs,
       opener,
       getAddress(this.config.escrowAddress),
       auth,
       terms,
+      BigInt(auth.authorization.value),
     );
     if (opened === undefined) {
       return failure(
@@ -750,6 +931,104 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
     };
   }
 
+  /**
+   * The success response of a mined UPFRONT settlement, or a mismatch failure.
+   * The receipt must show exactly what the signed terms imply:
+   *
+   * - `upfrontAmount > 0`: the opener's `UpfrontCharged` for this payer, nonce
+   *   and operator, for exactly `upfrontAmount`, naming the stream it opened
+   *   (or `bytes32(0)` when none was);
+   * - `price > upfrontAmount`: the escrow's `StreamOpened` (buyer = opener) and
+   *   the opener's `StreamOpenedFor` with `deposit = price - upfrontAmount`;
+   * - `upfrontAmount == price` (upfront-only): NO stream at all. Success, with
+   *   `streamId: null`: nothing was escrowed and there is nothing to refund.
+   *
+   * The reported `upfrontAmount` / `upfrontFee` are read from `UpfrontCharged`.
+   */
+  /** @internal */
+  private upfrontSettlement(
+    logs: readonly Log[],
+    hash: Hex,
+    auth: ExactEIP3009Payload & { signature: Hex },
+    terms: UpfrontOpenerTerms,
+    opener: Address,
+    network: Network,
+  ): SettleResponse {
+    const payer = getAddress(auth.authorization.from);
+    const escrow = getAddress(this.config.escrowAddress);
+    const refundable = upfrontRefundable(terms);
+    const mismatch = (why: string) =>
+      failure(
+        OpenerInvalidReason.streamEventMismatch,
+        network,
+        payer,
+        `the mined receipt does not show the expected upfront settlement: ${why}`,
+        hash,
+      );
+    const charged = findUpfrontCharged(logs, opener, auth, terms);
+    if (terms.upfrontAmount > 0n && charged === undefined) {
+      return mismatch(`no UpfrontCharged for ${terms.upfrontAmount}`);
+    }
+    if (terms.upfrontAmount === 0n && charged !== undefined) {
+      return mismatch("an UpfrontCharged for terms without an upfront part");
+    }
+    let streamId: Hex | null = null;
+    let expiresAt: bigint | null = null;
+    if (refundable > 0n) {
+      const opened = findStreamOpened(
+        logs,
+        opener,
+        escrow,
+        auth,
+        terms,
+        refundable,
+      );
+      if (opened === undefined) {
+        return mismatch(`no stream with deposit ${refundable}`);
+      }
+      if (
+        charged !== undefined &&
+        charged.streamId.toLowerCase() !== opened.streamId.toLowerCase()
+      ) {
+        return mismatch("UpfrontCharged names another stream");
+      }
+      streamId = opened.streamId;
+      expiresAt = opened.expiresAt;
+    } else {
+      // Upfront-only: the opener must have opened nothing.
+      if (charged === undefined || !/^0x0{64}$/i.test(charged.streamId)) {
+        return mismatch("an upfront-only payment must report streamId 0");
+      }
+      if (
+        findStreamOpened(logs, opener, escrow, auth, terms, undefined) !==
+        undefined
+      ) {
+        return mismatch("an upfront-only payment opened a stream");
+      }
+    }
+    return {
+      success: true,
+      transaction: hash,
+      network,
+      payer,
+      amount: auth.authorization.value,
+      extra: {
+        [OPENER_EXTRA_KEY]: {
+          // `null` (not bytes32(0)) for an upfront-only payment: no stream.
+          streamId,
+          opener,
+          escrow,
+          // The refundable, metered part — the most any refund can return.
+          deposit: refundable.toString(),
+          ratePerSecond: terms.ratePerSecond.toString(),
+          ...(expiresAt === null ? {} : { expiresAt: Number(expiresAt) }),
+          upfrontAmount: (charged?.amount ?? 0n).toString(),
+          upfrontFee: (charged?.fee ?? 0n).toString(),
+        },
+      },
+    };
+  }
+
   /** Every Metrik check plus the stock verifier. Cheapest, most local first. */
   private async check(
     payload: PaymentPayload,
@@ -759,7 +1038,7 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
     | {
         readonly ok: true;
         readonly auth: ExactEIP3009Payload & { signature: Hex };
-        readonly terms: OpenerTerms;
+        readonly plan: OpenerSettlementPlan;
         readonly opener: Address;
       }
     | { readonly ok: false; readonly response: VerifyResponse }
@@ -816,16 +1095,59 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
       return refuse(OpenerInvalidReason.assetNotAllowed);
     }
 
-    let terms: OpenerTerms;
-    let factory: Address;
+    let parsed: ReturnType<typeof termsFromExtra>;
     try {
-      ({ terms, factory } = termsFromExtra(requirements.extra));
+      parsed = termsFromExtra(requirements.extra);
     } catch (error) {
       return refuse(OpenerInvalidReason.invalidTerms, describe(error));
     }
-    if (factory !== binding.factory) {
+    const { terms, factory } = parsed;
+    // Only a factory this facilitator is bound to (and proved in init) is
+    // ever settled; its kind decides the terms shape — never the wire fields.
+    let kind: OpenerKind;
+    if (factory === binding.factory) {
+      kind = "stream";
+    } else if (
+      binding.upfront !== undefined &&
+      factory === binding.upfront.factory
+    ) {
+      kind = "upfront";
+    } else {
       return refuse(OpenerInvalidReason.factoryMismatch);
     }
+    if (
+      parsed.termsVersion !== undefined &&
+      parsed.termsVersion !== OPENER_TERMS_VERSION[kind]
+    ) {
+      return refuse(
+        OpenerInvalidReason.invalidTerms,
+        `termsVersion ${parsed.termsVersion} does not match the ${kind} opener factory (${OPENER_TERMS_VERSION[kind]})`,
+      );
+    }
+    let plan: OpenerSettlementPlan;
+    if (kind === "upfront") {
+      if (parsed.upfront === undefined) {
+        return refuse(
+          OpenerInvalidReason.invalidTerms,
+          "the upfront opener factory needs price and upfrontAmount in the terms",
+        );
+      }
+      const upfrontTerms: UpfrontOpenerTerms = { ...terms, ...parsed.upfront };
+      try {
+        assertValidUpfrontTerms(upfrontTerms);
+      } catch (error) {
+        return refuse(OpenerInvalidReason.invalidTerms, describe(error));
+      }
+      plan = { kind, terms: upfrontTerms };
+    } else {
+      if (parsed.upfront !== undefined) {
+        return refuse(
+          OpenerInvalidReason.invalidTerms,
+          "price/upfrontAmount are not terms of the stream opener factory (its payTo does not commit to them)",
+        );
+      }
+      plan = { kind, terms };
+    }
 
     let amount: bigint;
     try {
@@ -842,16 +1164,41 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
         `amount ${amount} is below this facilitator's minimum ${this.minAmount}`,
       );
     }
-    if (amount > maxEarnable(terms)) {
+    if (plan.kind === "upfront") {
+      // The opener accepts exactly its price; anything else reverts on-chain.
+      if (amount !== plan.terms.price) {
+        return refuse(
+          OpenerInvalidReason.invalidAmount,
+          `amount ${amount} is not the upfront opener's fixed price ${plan.terms.price}`,
+        );
+      }
+    } else 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)],
-    });
+    let predicted: Address;
+    try {
+      predicted =
+        plan.kind === "upfront"
+          ? await this.config.publicClient.readContract({
+              address: binding.upfront?.factory as Address,
+              abi: x402UpfrontStreamOpenerFactoryAbi,
+              functionName: "predict",
+              args: [upfrontTermsTuple(plan.terms)],
+            })
+          : await this.config.publicClient.readContract({
+              address: binding.factory,
+              abi: x402StreamOpenerFactoryAbi,
+              functionName: "predict",
+              args: [termsTuple(terms)],
+            });
+    } catch (error) {
+      // predict reverts InvalidTerms for terms no transaction can deploy.
+      if (revertReason(error) === "InvalidTerms") {
+        return refuse(OpenerInvalidReason.invalidTerms, "InvalidTerms");
+      }
+      throw error;
+    }
     if (
       !isAddress(requirements.payTo) ||
       getAddress(requirements.payTo) !== getAddress(predicted)
@@ -880,18 +1227,12 @@ export class MetrikOpenerExactScheme implements SchemeNetworkFacilitator {
 
     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)],
-      });
+      await this.simulateDeployAndSettle(signed, plan);
     } catch (error) {
       return refuse(OpenerInvalidReason.simulationFailed, revertReason(error));
     }
 
-    return { ok: true, auth: signed, terms, opener: getAddress(predicted) };
+    return { ok: true, auth: signed, plan, opener: getAddress(predicted) };
   }
 }
 
@@ -925,8 +1266,9 @@ function findStreamOpened(
   escrow: Address,
   auth: ExactEIP3009Payload,
   terms: OpenerTerms,
+  /** Expected stream deposit; `undefined` matches ANY deposit (an absence check). */
+  deposit: bigint | undefined,
 ): { 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) {
@@ -951,7 +1293,7 @@ function findStreamOpened(
         getAddress(args.buyer) === opener &&
         getAddress(args.operator) === getAddress(terms.operator) &&
         args.serviceRef.toLowerCase() === terms.serviceRef.toLowerCase() &&
-        args.deposit === value &&
+        (deposit === undefined || args.deposit === deposit) &&
         args.ratePerSecond === terms.ratePerSecond
       ) {
         escrowStreams.set(args.streamId.toLowerCase(), BigInt(args.expiresAt));
@@ -976,7 +1318,7 @@ function findStreamOpened(
         getAddress(args.payer) === payer &&
         args.authorizationNonce.toLowerCase() ===
           auth.authorization.nonce.toLowerCase() &&
-        args.deposit === value
+        (deposit === undefined || args.deposit === deposit)
       ) {
         return { streamId: args.streamId, expiresAt };
       }
@@ -987,6 +1329,54 @@ function findStreamOpened(
   return undefined;
 }
 
+/**
+ * The opener's `UpfrontCharged` for this payer, authorization nonce and
+ * operator, for exactly the terms' `upfrontAmount` (its `fee` is the protocol
+ * fee taken out of it). `undefined` when the receipt carries none.
+ */
+function findUpfrontCharged(
+  logs: readonly Log[],
+  opener: Address,
+  auth: ExactEIP3009Payload,
+  terms: UpfrontOpenerTerms,
+):
+  | { readonly streamId: Hex; readonly amount: bigint; readonly fee: bigint }
+  | undefined {
+  const payer = getAddress(auth.authorization.from);
+  for (const log of logs) {
+    if (getAddress(log.address) !== opener) continue;
+    try {
+      const decoded = decodeEventLog({
+        abi: x402UpfrontStreamOpenerAbi,
+        data: log.data,
+        topics: log.topics,
+      });
+      if (decoded.eventName !== "UpfrontCharged") continue;
+      const args = decoded.args as unknown as {
+        authorizationNonce: Hex;
+        payer: Address;
+        operator: Address;
+        amount: bigint;
+        fee: bigint;
+        streamId: Hex;
+      };
+      if (
+        getAddress(args.payer) === payer &&
+        args.authorizationNonce.toLowerCase() ===
+          auth.authorization.nonce.toLowerCase() &&
+        getAddress(args.operator) === getAddress(terms.operator) &&
+        args.amount === terms.upfrontAmount &&
+        args.fee <= args.amount
+      ) {
+        return { streamId: args.streamId, amount: args.amount, fee: args.fee };
+      }
+    } 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.
@@ -1023,6 +1413,34 @@ export function readOpenerFacilitatorMarker(
     minAmount: marker.minAmount,
     receiptTimeoutSeconds: marker.receiptTimeoutSeconds,
     ...(marker.refundRelay === true ? { refundRelay: true as const } : {}),
+    ...(readUpfrontMarker(marker.upfrontOpener) ?? {}),
+  };
+}
+
+/** The optional `upfrontOpener` entry of a marker; a malformed one is ignored (absent). */
+function readUpfrontMarker(
+  raw: unknown,
+): { readonly upfrontOpener: UpfrontOpenerMarker } | undefined {
+  if (typeof raw !== "object" || raw === null) return undefined;
+  const entry = raw as Record<string, unknown>;
+  if (
+    typeof entry.factory !== "string" ||
+    !isAddress(entry.factory) ||
+    typeof entry.implementation !== "string" ||
+    !isAddress(entry.implementation) ||
+    typeof entry.escrow !== "string" ||
+    !isAddress(entry.escrow) ||
+    entry.termsVersion !== OPENER_TERMS_VERSION.upfront
+  ) {
+    return undefined;
+  }
+  return {
+    upfrontOpener: {
+      factory: getAddress(entry.factory),
+      implementation: getAddress(entry.implementation),
+      escrow: getAddress(entry.escrow),
+      termsVersion: OPENER_TERMS_VERSION.upfront,
+    },
   };
 }