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

package/src/x402-opener/refund-relay.ts

@@ -1,4 +1,8 @@
-import { streamEscrowV2Abi } from "@absol-labs/shared";
+import {
+  streamEscrowV2Abi,
+  x402UpfrontStreamOpenerAbi,
+  x402UpfrontStreamOpenerFactoryAbi,
+} from "@absol-labs/shared";
 import {
   BaseError,
   ContractFunctionRevertedError,
@@ -23,7 +27,7 @@ import {
 
 import { x402StreamOpenerAbi, x402StreamOpenerFactoryAbi } from "./abi.js";
 import { RelayerQueue } from "./relayer-queue.js";
-import { chainIdFromNetwork } from "./terms.js";
+import { chainIdFromNetwork, type OpenerKind } from "./terms.js";
 import {
   escrowGenerationFor,
   readEscapeHatchReadyAt,
@@ -60,9 +64,18 @@ import {
  *
  * ## Bounded against gas abuse
  *
- * - Only streams whose escrow buyer is an opener of the configured factory
- *   (`factory.isOpener(stream.buyer)`, on-chain) are served; everything else is
- *   `404` before any signature check, oracle call or simulation.
+ * - Only streams whose escrow buyer is an opener of a configured factory
+ *   (`factory.isOpener(stream.buyer)`, on-chain: the stream factory, and the
+ *   upfront factory when configured) are served; everything else is `404`
+ *   before any signature check, oracle call or simulation. Which factory
+ *   claims the opener decides its KIND, and so the EIP-712 domain its payer
+ *   signs under ("Metrik X402StreamOpener" or "Metrik X402UpfrontStreamOpener").
+ * - Stream id 0 is an UPFRONT-ONLY payment (`upfrontAmount == price`): no
+ *   stream exists and nothing was escrowed. Every route answers
+ *   `nothing-to-refund` for it without a chain read, and no close or reclaim is
+ *   ever submitted for it.
+ * - For an upfront opener, only the stream deposit (`price - upfrontAmount`)
+ *   is refundable; the status reports that as `maxRefund`, never the price.
  * - Every precondition the contract would check is read first (status, expiry,
  *   settlement window, reclaimed flag, non-zero refund). A request that would
  *   have no real effect never reaches the relayer.
@@ -84,6 +97,18 @@ import {
 /** EIP-712 domain name/version of `X402StreamOpener`. Checked against the opener's ERC-5267 domain. */
 export const OPENER_EIP712_NAME = "Metrik X402StreamOpener";
 export const OPENER_EIP712_VERSION = "1";
+/** EIP-712 domain name of `X402UpfrontStreamOpener` (same version, same types). */
+export const UPFRONT_OPENER_EIP712_NAME = "Metrik X402UpfrontStreamOpener";
+
+/** The EIP-712 domain name an opener of `kind` signs under. */
+export function openerEip712Name(kind: OpenerKind): string {
+  return kind === "upfront" ? UPFRONT_OPENER_EIP712_NAME : OPENER_EIP712_NAME;
+}
+
+/** True for the all-zero bytes32: an upfront-only payment, no stream. */
+export function isNoStreamId(streamId: string): boolean {
+  return /^0x0{64}$/i.test(streamId);
+}
 
 /** The two payer-signed opener actions. */
 export type OpenerSignedAction = "Close" | "ReclaimUnverified";
@@ -118,6 +143,8 @@ const CHECKPOINT_RETRY_HINT_SECONDS = 30;
  */
 export function openerActionTypedData(input: {
   readonly action: OpenerSignedAction;
+  /** The opener's kind (read on-chain); default `"stream"`. Picks the domain name. */
+  readonly kind?: OpenerKind;
   readonly opener: Address;
   readonly chainId: number;
   readonly streamId: Hex;
@@ -126,7 +153,7 @@ export function openerActionTypedData(input: {
 }) {
   return {
     domain: {
-      name: OPENER_EIP712_NAME,
+      name: openerEip712Name(input.kind ?? "stream"),
       version: OPENER_EIP712_VERSION,
       chainId: input.chainId,
       verifyingContract: getAddress(input.opener),
@@ -178,6 +205,11 @@ export interface OpenerRefundRelayConfig {
   /** CAIP-2 network (`eip155:<chainId>`), as the registry gives it. Must match the RPC's chain id. */
   readonly network: string;
   readonly factoryAddress: Address;
+  /**
+   * The `X402UpfrontStreamOpenerFactory` whose clones are served too (same
+   * escrow, checked by {@link OpenerRefundRelay.init}). Unset = stream openers only.
+   */
+  readonly upfrontFactoryAddress?: Address;
   /** The `StreamEscrowV2` the factory settles into (checked by {@link OpenerRefundRelay.init}). */
   readonly escrowAddress: Address;
   /** Base URL of the Metrik oracle that serves `GET /checkpoint/proof?streamId=`. */
@@ -290,6 +322,9 @@ interface ResolvedStream {
   readonly stream: OpenerStream;
   readonly opener: Address;
   readonly payer: Address;
+  /** Which configured factory's `isOpener` claims `opener` (read on-chain). */
+  readonly kind: OpenerKind;
+  readonly factory: Address;
 }
 
 type OracleProof =
@@ -379,6 +414,7 @@ class MinuteWindows {
 export class OpenerRefundRelay implements RefundRelayHandler {
   private readonly chainId: number;
   private readonly factory: Address;
+  private readonly upfrontFactory: Address | undefined;
   private readonly escrow: Address;
   private readonly oracleUrl: string;
   private readonly queue: RelayerQueue;
@@ -409,6 +445,19 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       throw new Error("factoryAddress and escrowAddress must be EVM addresses");
     }
     this.factory = getAddress(config.factoryAddress);
+    if (
+      config.upfrontFactoryAddress !== undefined &&
+      !isAddress(config.upfrontFactoryAddress)
+    ) {
+      throw new Error("upfrontFactoryAddress must be an EVM address");
+    }
+    this.upfrontFactory =
+      config.upfrontFactoryAddress === undefined
+        ? undefined
+        : getAddress(config.upfrontFactoryAddress);
+    if (this.upfrontFactory === this.factory) {
+      throw new Error("upfrontFactoryAddress must differ from factoryAddress");
+    }
     this.escrow = getAddress(config.escrowAddress);
     const generation =
       config.escrowGeneration ?? escrowGenerationFor(this.chainId, this.escrow);
@@ -487,6 +536,18 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         `refund relay: factory escrow ${factoryEscrow} is not the configured escrow ${this.escrow}`,
       );
     }
+    if (this.upfrontFactory !== undefined) {
+      const upfrontEscrow = await publicClient.readContract({
+        address: this.upfrontFactory,
+        abi: x402UpfrontStreamOpenerFactoryAbi,
+        functionName: "escrow",
+      });
+      if (getAddress(upfrontEscrow) !== this.escrow) {
+        throw new Error(
+          `refund relay: upfront factory escrow ${upfrontEscrow} is not the configured escrow ${this.escrow}`,
+        );
+      }
+    }
     this.escapeGraceSeconds = BigInt(
       await publicClient.readContract({
         address: this.escrow,
@@ -501,6 +562,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   async status(rawStreamId: string): Promise<RefundRelayResponse> {
     const streamId = parseStreamId(rawStreamId);
     if (streamId === undefined) return invalidStreamId();
+    if (isNoStreamId(streamId)) return nothingToRefund(404);
     const cached = this.fresh(this.statusCache, streamId);
     if (cached !== undefined) return cached.response;
     const response = await this.computeStatus(streamId);
@@ -517,12 +579,15 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     try {
       const resolved = await this.resolve(rawStreamId);
       if ("status" in resolved) return resolved;
-      const { streamId, stream, opener, payer } = resolved;
+      const { streamId, stream, opener, payer, kind, factory } = resolved;
       const grace = this.grace();
-      const [now, nonce, latestCheckedAt] = await Promise.all([
+      const [now, nonce, latestCheckedAt, upfrontTerms] = await Promise.all([
         this.chainNow(),
         this.readNonce(opener, payer),
         this.readLatestCheckedAt(),
+        kind === "upfront"
+          ? this.readUpfrontTerms(opener)
+          : Promise.resolve(undefined),
       ]);
       const closed = stream.status === 1;
       const stopAt = stopTime(stream);
@@ -571,6 +636,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
           typedData: jsonTypedData(
             openerActionTypedData({
               action: "Close",
+              kind,
               opener,
               chainId: this.chainId,
               streamId,
@@ -617,6 +683,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
           typedData: jsonTypedData(
             openerActionTypedData({
               action: "ReclaimUnverified",
+              kind,
               opener,
               chainId: this.chainId,
               streamId,
@@ -643,12 +710,24 @@ export class OpenerRefundRelay implements RefundRelayHandler {
           streamId,
           chainId: this.chainId,
           escrow: this.escrow,
-          factory: this.factory,
+          factory,
+          openerKind: kind,
           opener,
           payer,
           operator: stream.operator,
           serviceRef: stream.serviceRef,
           deposit: stream.deposit.toString(),
+          // The most any refund of this payment can return: the escrowed
+          // deposit. For an upfront opener that is price - upfrontAmount; the
+          // upfront part was paid to the seller at settlement and is final.
+          maxRefund: stream.deposit.toString(),
+          ...(upfrontTerms === undefined
+            ? {}
+            : {
+                price: upfrontTerms.price.toString(),
+                upfrontAmount: upfrontTerms.upfrontAmount.toString(),
+                upfrontNote: `${upfrontTerms.upfrontAmount.toString()} of the ${upfrontTerms.price.toString()} paid was a non-refundable per-call charge, paid to the seller at settlement; at most the ${stream.deposit.toString()} escrowed can be refunded.`,
+              }),
           ratePerSecond: stream.ratePerSecond.toString(),
           claimedCumulative: stream.claimedCumulative.toString(),
           openedAt: Number(stream.openedAt),
@@ -687,6 +766,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   ): Promise<RefundRelayResponse> {
     const streamId = parseStreamId(rawStreamId);
     if (streamId === undefined) return invalidStreamId();
+    if (isNoStreamId(streamId)) return nothingToRefund(409);
     const signed = parseSignedBody(body);
     if ("status" in signed) return signed;
     const key = ledgerKey("close", streamId);
@@ -695,7 +775,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     try {
       const resolved = await this.resolve(streamId);
       if ("status" in resolved) return resolved;
-      const { stream, opener, payer } = resolved;
+      const { stream, opener, payer, kind } = resolved;
       const now = await this.chainNow();
       if (stream.status === 1) {
         return fail(409, "already-closed", "the stream is already closed", {
@@ -712,6 +792,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       }
       const refused = await this.verifyPayerSignature(
         "Close",
+        kind,
         streamId,
         opener,
         payer,
@@ -740,6 +821,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   async reclaim(rawStreamId: string): Promise<RefundRelayResponse> {
     const streamId = parseStreamId(rawStreamId);
     if (streamId === undefined) return invalidStreamId();
+    if (isNoStreamId(streamId)) return nothingToRefund(409);
     const key = ledgerKey("reclaim", streamId);
     const early = await this.precheck(key, "reclaim");
     if (early !== undefined) return early;
@@ -832,6 +914,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   ): Promise<RefundRelayResponse> {
     const streamId = parseStreamId(rawStreamId);
     if (streamId === undefined) return invalidStreamId();
+    if (isNoStreamId(streamId)) return nothingToRefund(409);
     const signed = parseSignedBody(body);
     if ("status" in signed) return signed;
     const key = ledgerKey("reclaim", streamId);
@@ -840,7 +923,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     try {
       const resolved = await this.resolve(streamId);
       if ("status" in resolved) return resolved;
-      const { stream, opener, payer } = resolved;
+      const { stream, opener, payer, kind } = resolved;
       if (stream.reclaimed) return alreadyReclaimed();
       const now = await this.chainNow();
       const escapeAt = await this.escapeHatchAt(streamId, stream);
@@ -868,6 +951,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       }
       const refused = await this.verifyPayerSignature(
         "ReclaimUnverified",
+        kind,
         streamId,
         opener,
         payer,
@@ -1236,13 +1320,31 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     }
     if (!isAddress(stream.buyer)) return notFound();
     const buyer = getAddress(stream.buyer);
-    const isOpener = await publicClient.readContract({
-      address: this.factory,
-      abi: x402StreamOpenerFactoryAbi,
-      functionName: "isOpener",
-      args: [buyer],
-    });
-    if (isOpener !== true) return notFound();
+    // The kind is whichever CONFIGURED factory's isOpener claims the buyer,
+    // read on-chain — never inferred from the address, code or the request.
+    const [isStreamOpener, isUpfrontOpener] = await Promise.all([
+      publicClient.readContract({
+        address: this.factory,
+        abi: x402StreamOpenerFactoryAbi,
+        functionName: "isOpener",
+        args: [buyer],
+      }),
+      this.upfrontFactory === undefined
+        ? Promise.resolve(false)
+        : publicClient.readContract({
+            address: this.upfrontFactory,
+            abi: x402UpfrontStreamOpenerFactoryAbi,
+            functionName: "isOpener",
+            args: [buyer],
+          }),
+    ]);
+    if ((isStreamOpener === true) === (isUpfrontOpener === true)) {
+      // Neither (not our opener) — or both, which CREATE2 makes impossible.
+      return notFound();
+    }
+    const kind: OpenerKind = isUpfrontOpener === true ? "upfront" : "stream";
+    const factory =
+      kind === "upfront" ? (this.upfrontFactory as Address) : this.factory;
     const payer = await publicClient.readContract({
       address: buyer,
       abi: x402StreamOpenerAbi,
@@ -1254,6 +1356,8 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       streamId,
       opener: buyer,
       payer: getAddress(payer),
+      kind,
+      factory,
       stream: {
         buyer,
         operator: getAddress(stream.operator),
@@ -1274,6 +1378,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
   /** Off-chain check of a payer-signed opener action. `undefined` = valid. */
   private async verifyPayerSignature(
     action: OpenerSignedAction,
+    kind: OpenerKind,
     streamId: Hex,
     opener: Address,
     payer: Address,
@@ -1322,7 +1427,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
       readonly bigint[],
     ];
     if (
-      name !== OPENER_EIP712_NAME ||
+      name !== openerEip712Name(kind) ||
       version !== OPENER_EIP712_VERSION ||
       BigInt(chainId) !== BigInt(this.chainId) ||
       getAddress(verifyingContract) !== opener
@@ -1340,6 +1445,7 @@ export class OpenerRefundRelay implements RefundRelayHandler {
         address: payer,
         ...openerActionTypedData({
           action,
+          kind,
           opener,
           chainId: this.chainId,
           streamId,
@@ -1380,6 +1486,21 @@ export class OpenerRefundRelay implements RefundRelayHandler {
     );
   }
 
+  /** An upfront opener's immutable terms (`price`, `upfrontAmount`). */
+  private async readUpfrontTerms(
+    opener: Address,
+  ): Promise<{ readonly price: bigint; readonly upfrontAmount: bigint }> {
+    const terms = (await this.config.publicClient.readContract({
+      address: opener,
+      abi: x402UpfrontStreamOpenerAbi,
+      functionName: "terms",
+    })) as unknown as { price: bigint; upfrontAmount: bigint };
+    return {
+      price: BigInt(terms.price),
+      upfrontAmount: BigInt(terms.upfrontAmount),
+    };
+  }
+
   private async readLatestCheckedAt(): Promise<bigint> {
     return BigInt(
       await this.config.publicClient.readContract({
@@ -1672,7 +1793,16 @@ function notFound(): RefundRelayResponse {
   return fail(
     404,
     "not-found",
-    "no stream opened through this facilitator's X402StreamOpenerFactory has that id",
+    "no stream opened through this facilitator's opener factories has that id",
+  );
+}
+
+/** Stream id 0: an upfront-only payment. Never read, closed or reclaimed. */
+function nothingToRefund(status: 404 | 409): RefundRelayResponse {
+  return fail(
+    status,
+    "nothing-to-refund",
+    "stream id 0 is an upfront-only payment (upfrontAmount == price): the whole price was paid to the seller at settlement, no stream was opened, nothing was escrowed, and there is nothing to close or reclaim",
   );
 }