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

package/src/x402-opener/terms.ts

@@ -1,3 +1,7 @@
+import {
+  InvalidUpfrontTermsError,
+  validateUpfrontTerms,
+} from "@absol-labs/shared";
 import { getAddress, isAddress, isHex, type Address, type Hex } from "viem";
 
 /**
@@ -51,6 +55,96 @@ export interface OpenerTerms {
   readonly maxDuration: bigint;
 }
 
+/**
+ * Which opener contract a factory deploys: `"stream"` (`X402StreamOpener`,
+ * 4-field terms, the whole payment funds a stream) or `"upfront"`
+ * (`X402UpfrontStreamOpener`, 6-field terms: a fixed `price` whose
+ * non-refundable `upfrontAmount` is paid to the seller at settlement and whose
+ * remainder funds a stream). Decided by WHICH configured factory a quote names,
+ * never by the wire fields alone.
+ */
+export type OpenerKind = "stream" | "upfront";
+
+/** `termsVersion` of each opener kind's `extra.metrikStreamOpener` (as the SDK checks it). */
+export const OPENER_TERMS_VERSION = {
+  stream: "stream-1",
+  upfront: "upfront-1",
+} as const satisfies Record<OpenerKind, string>;
+
+/**
+ * The 6-field terms of an `X402UpfrontStreamOpener` (metrik-contracts#54),
+ * mirroring the Solidity struct. Every field is committed by the `payTo`.
+ */
+export interface UpfrontOpenerTerms extends OpenerTerms {
+  /** The exact x402 amount: the opener accepts this value and nothing else. */
+  readonly price: bigint;
+  /** NON-REFUNDABLE part paid to the seller (net of the protocol fee) at settlement. `<= price`. */
+  readonly upfrontAmount: bigint;
+}
+
+/** The refundable, metered part of an upfront opener's price (the stream deposit). */
+export function upfrontRefundable(terms: UpfrontOpenerTerms): bigint {
+  return terms.price - terms.upfrontAmount;
+}
+
+/** True when an upfront opener opens no stream at all (`upfrontAmount == price`). */
+export function isUpfrontOnly(terms: UpfrontOpenerTerms): boolean {
+  return terms.price > 0n && terms.upfrontAmount === terms.price;
+}
+
+/**
+ * The upfront terms a gateway may quote: exactly the factory's
+ * `validateTerms` (via `@absol-labs/shared`'s `validateUpfrontTerms`, so a
+ * `payTo` no transaction can deploy is never quoted), a fixed non-zero price,
+ * and a metered part (`price - upfrontAmount`) the stream can actually earn
+ * (`<= ratePerSecond * maxDuration`) — the SDK buyer refuses anything else.
+ */
+export function assertValidUpfrontTerms(terms: UpfrontOpenerTerms): void {
+  assertValidTerms(terms);
+  try {
+    validateUpfrontTerms({
+      operator: getAddress(terms.operator),
+      serviceRef: terms.serviceRef.toLowerCase() as Hex,
+      ratePerSecond: terms.ratePerSecond,
+      maxDuration: terms.maxDuration,
+      price: terms.price,
+      upfrontAmount: terms.upfrontAmount,
+    });
+  } catch (error) {
+    throw new InvalidOpenerTermsError(
+      error instanceof InvalidUpfrontTermsError || error instanceof Error
+        ? error.message
+        : String(error),
+    );
+  }
+  if (terms.price <= 0n) {
+    throw new InvalidOpenerTermsError(
+      "an upfront opener needs a fixed price > 0",
+    );
+  }
+  if (upfrontRefundable(terms) > maxEarnable(terms)) {
+    throw new InvalidOpenerTermsError(
+      `the metered part ${upfrontRefundable(terms)} (price - upfrontAmount) exceeds ratePerSecond * maxDuration (${maxEarnable(terms)})`,
+    );
+  }
+}
+
+/** Solidity-tuple view of 6-field upfront terms for viem contract calls. */
+export function upfrontTermsTuple(terms: UpfrontOpenerTerms): {
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly ratePerSecond: bigint;
+  readonly maxDuration: bigint;
+  readonly price: bigint;
+  readonly upfrontAmount: bigint;
+} {
+  return {
+    ...termsTuple(terms),
+    price: terms.price,
+    upfrontAmount: terms.upfrontAmount,
+  };
+}
+
 /** JSON-safe projection of {@link OpenerTerms} plus the factory that prices them. */
 export interface OpenerTermsExtra {
   readonly factory: Address;
@@ -58,6 +152,12 @@ export interface OpenerTermsExtra {
   readonly serviceRef: Hex;
   readonly ratePerSecond: string;
   readonly maxDuration: string;
+  /** Upfront openers only: the exact price (base units). */
+  readonly price?: string;
+  /** Upfront openers only: the non-refundable per-call part (base units). */
+  readonly upfrontAmount?: string;
+  /** `stream-1` / `upfront-1`; optional, must match the factory's kind when present. */
+  readonly termsVersion?: string;
   /**
    * Informational only (metrik-agent#119): where the payer gets unearned money
    * back without ETH, as a template containing `{streamId}`. Never used for
@@ -158,14 +258,38 @@ export function termsToExtra(
   };
 }
 
+/** The 402 `extra.metrikStreamOpener` terms of an upfront opener quote. */
+export function upfrontTermsToExtra(
+  factory: Address,
+  terms: UpfrontOpenerTerms,
+): OpenerTermsExtra {
+  return {
+    factory: getAddress(factory),
+    termsVersion: OPENER_TERMS_VERSION.upfront,
+    operator: getAddress(terms.operator),
+    serviceRef: terms.serviceRef.toLowerCase() as Hex,
+    ratePerSecond: terms.ratePerSecond.toString(),
+    maxDuration: terms.maxDuration.toString(),
+    price: terms.price.toString(),
+    upfrontAmount: terms.upfrontAmount.toString(),
+  };
+}
+
 /**
  * Reads opener terms from an untrusted `PaymentRequirements.extra`. Every field
  * is re-validated; unknown keys under the opener object are rejected so the
- * wire shape cannot drift silently.
+ * wire shape cannot drift silently. `price` / `upfrontAmount` are returned as
+ * `upfront` when present (both or neither); whether they are REQUIRED or
+ * FORBIDDEN depends on the factory's kind, which only the caller knows.
  */
 export function termsFromExtra(extra: unknown): {
   readonly factory: Address;
   readonly terms: OpenerTerms;
+  readonly upfront?: {
+    readonly price: bigint;
+    readonly upfrontAmount: bigint;
+  };
+  readonly termsVersion?: string;
 } {
   if (typeof extra !== "object" || extra === null) {
     throw new InvalidOpenerTermsError("requirements.extra is missing");
@@ -183,6 +307,9 @@ export function termsFromExtra(extra: unknown): {
     "serviceRef",
     "ratePerSecond",
     "maxDuration",
+    "price",
+    "upfrontAmount",
+    "termsVersion",
     "refundUrl",
     "docsUrl",
   ]);
@@ -217,7 +344,33 @@ export function termsFromExtra(extra: unknown): {
     maxDuration: parseUintString(record.maxDuration, "maxDuration"),
   };
   assertValidTerms(terms);
-  return { factory: getAddress(factory), terms };
+  const termsVersion = record.termsVersion;
+  if (
+    termsVersion !== undefined &&
+    (typeof termsVersion !== "string" || termsVersion.length > 64)
+  ) {
+    throw new InvalidOpenerTermsError("termsVersion must be a short string");
+  }
+  if ((record.price === undefined) !== (record.upfrontAmount === undefined)) {
+    throw new InvalidOpenerTermsError(
+      "price and upfrontAmount must be given together (an upfront opener's terms) or not at all",
+    );
+  }
+  const upfront =
+    record.price === undefined
+      ? undefined
+      : {
+          price: parseUintString(record.price, "price"),
+          upfrontAmount: parseUintString(record.upfrontAmount, "upfrontAmount"),
+        };
+  return {
+    factory: getAddress(factory),
+    terms,
+    ...(upfront === undefined ? {} : { upfront }),
+    ...(termsVersion === undefined
+      ? {}
+      : { termsVersion: termsVersion as string }),
+  };
 }
 
 /** Chain id encoded in an `eip155:<id>` CAIP-2 identifier. Throws otherwise. */