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

package/src/x402-opener/terms.ts

@@ -0,0 +1,300 @@
+import { getAddress, isAddress, isHex, type Address, type Hex } from "viem";
+
+/**
+ * Shared vocabulary of the x402 v2 escrow-opener path (metrik-agent#116).
+ *
+ * A standard x402 v2 `exact` payment (an EIP-3009 `transferWithAuthorization`)
+ * is settled through the ownerless `X402StreamOpenerFactory`
+ * (metrik-contracts#48): the x402 `payTo` is the CREATE2 address of the opener
+ * for one immutable set of stream {@link OpenerTerms}, so the payer's signature
+ * (which binds `to`) commits to those terms, and the opener turns the payment
+ * into an ordinary `StreamEscrowV2` stream with `deposit = amount`.
+ *
+ * This module has no network or package side effects: it is the pure,
+ * dependency-free part shared by the facilitator and the gateway.
+ */
+
+/** Scheme name. The standard x402 `exact` scheme, nothing Metrik-specific. */
+export const OPENER_SCHEME = "exact" as const;
+
+/*
+ * Network, USDC, escrow, factory and oracle defaults are NOT constants here:
+ * they come from the `@absol-labs/sdk` network registry (see `../network.ts`),
+ * so a new deployment is a registry change, never an edit to this module.
+ */
+
+/** Public docs for the x402 opener path, linked from the 402. */
+export const DEFAULT_OPENER_DOCS_URL =
+  "https://github.com/Absol-Labs/metrik-agent/blob/main/docs/x402.md";
+
+/** Longest informational link accepted in `extra.metrikStreamOpener`. */
+const MAX_LINK_LENGTH = 2048;
+
+/**
+ * Key under `PaymentRequirements.extra` that carries the opener terms. The
+ * facilitator reads the terms ONLY from here, recomputes the opener address
+ * on-chain and requires it to equal `payTo`, so a tampered value can never
+ * redirect funds: it just fails verification.
+ */
+export const OPENER_EXTRA_KEY = "metrikStreamOpener" as const;
+
+/** `uint64` ceiling for `maxDuration`. */
+const MAX_UINT64 = (1n << 64n) - 1n;
+
+/** Immutable per-listing stream terms, mirroring the Solidity `Terms` struct. */
+export interface OpenerTerms {
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  /** USDC base units per second. */
+  readonly ratePerSecond: bigint;
+  /** Seconds. */
+  readonly maxDuration: bigint;
+}
+
+/** JSON-safe projection of {@link OpenerTerms} plus the factory that prices them. */
+export interface OpenerTermsExtra {
+  readonly factory: Address;
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly ratePerSecond: string;
+  readonly maxDuration: string;
+  /**
+   * Informational only (metrik-agent#119): where the payer gets unearned money
+   * back without ETH, as a template containing `{streamId}`. Never used for
+   * settlement; the facilitator validates it is an http(s) link and ignores it.
+   */
+  readonly refundUrl?: string;
+  /** Informational only: docs for this payment path. */
+  readonly docsUrl?: string;
+}
+
+/** True for an absolute http(s) URL of sane length. */
+export function isHttpLink(value: unknown): value is string {
+  if (typeof value !== "string" || value.length > MAX_LINK_LENGTH) return false;
+  try {
+    const url = new URL(value);
+    return url.protocol === "https:" || url.protocol === "http:";
+  } catch {
+    return false;
+  }
+}
+
+export class InvalidOpenerTermsError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "InvalidOpenerTermsError";
+  }
+}
+
+/** Parses a non-negative base-10 integer string. Throws on anything else. */
+export function parseUintString(value: unknown, field: string): bigint {
+  if (typeof value !== "string" || !/^(0|[1-9]\d*)$/.test(value)) {
+    throw new InvalidOpenerTermsError(
+      `${field} must be a base-10 integer string without sign or leading zeros`,
+    );
+  }
+  return BigInt(value);
+}
+
+/**
+ * Validates terms the way the factory's `deploy` does (non-zero operator, rate
+ * and duration, `maxDuration` within `uint64`) plus the shape checks the
+ * contract cannot do for us (32-byte serviceRef).
+ */
+export function assertValidTerms(terms: OpenerTerms): void {
+  if (!isAddress(terms.operator, { strict: false })) {
+    throw new InvalidOpenerTermsError("operator must be an EVM address");
+  }
+  if (/^0x0{40}$/i.test(terms.operator)) {
+    throw new InvalidOpenerTermsError("operator must not be the zero address");
+  }
+  if (
+    !isHex(terms.serviceRef, { strict: true }) ||
+    terms.serviceRef.length !== 66
+  ) {
+    throw new InvalidOpenerTermsError("serviceRef must be a 32-byte hex value");
+  }
+  if (terms.ratePerSecond <= 0n) {
+    throw new InvalidOpenerTermsError("ratePerSecond must be > 0");
+  }
+  if (terms.maxDuration <= 0n || terms.maxDuration > MAX_UINT64) {
+    throw new InvalidOpenerTermsError(
+      "maxDuration must be > 0 and fit in uint64",
+    );
+  }
+}
+
+/** The largest deposit a stream on these terms can ever earn out: `rate * maxDuration`. */
+export function maxEarnable(terms: OpenerTerms): bigint {
+  return terms.ratePerSecond * terms.maxDuration;
+}
+
+/**
+ * The price (= stream deposit) must be positive and must not exceed what the
+ * stream can ever accrue. A deposit above `rate * maxDuration` would lock money
+ * the seller can never earn, reclaimable only by a second buyer action.
+ */
+export function assertValidPrice(price: bigint, terms: OpenerTerms): void {
+  if (price <= 0n) {
+    throw new InvalidOpenerTermsError("price must be > 0");
+  }
+  if (price > maxEarnable(terms)) {
+    throw new InvalidOpenerTermsError(
+      `price ${price} exceeds ratePerSecond * maxDuration (${maxEarnable(terms)})`,
+    );
+  }
+}
+
+export function termsToExtra(
+  factory: Address,
+  terms: OpenerTerms,
+): OpenerTermsExtra {
+  return {
+    factory: getAddress(factory),
+    operator: getAddress(terms.operator),
+    serviceRef: terms.serviceRef.toLowerCase() as Hex,
+    ratePerSecond: terms.ratePerSecond.toString(),
+    maxDuration: terms.maxDuration.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.
+ */
+export function termsFromExtra(extra: unknown): {
+  readonly factory: Address;
+  readonly terms: OpenerTerms;
+} {
+  if (typeof extra !== "object" || extra === null) {
+    throw new InvalidOpenerTermsError("requirements.extra is missing");
+  }
+  const raw = (extra as Record<string, unknown>)[OPENER_EXTRA_KEY];
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new InvalidOpenerTermsError(
+      `requirements.extra.${OPENER_EXTRA_KEY} is missing`,
+    );
+  }
+  const record = raw as Record<string, unknown>;
+  const allowed = new Set([
+    "factory",
+    "operator",
+    "serviceRef",
+    "ratePerSecond",
+    "maxDuration",
+    "refundUrl",
+    "docsUrl",
+  ]);
+  for (const key of Object.keys(record)) {
+    if (!allowed.has(key)) {
+      throw new InvalidOpenerTermsError(
+        `unknown key ${key} in requirements.extra.${OPENER_EXTRA_KEY}`,
+      );
+    }
+  }
+  for (const link of ["refundUrl", "docsUrl"] as const) {
+    if (record[link] !== undefined && !isHttpLink(record[link])) {
+      throw new InvalidOpenerTermsError(
+        `${link} in requirements.extra.${OPENER_EXTRA_KEY} must be an http(s) URL`,
+      );
+    }
+  }
+  const { factory, operator, serviceRef } = record;
+  if (typeof factory !== "string" || !isAddress(factory, { strict: false })) {
+    throw new InvalidOpenerTermsError("factory must be an EVM address");
+  }
+  if (typeof operator !== "string" || !isAddress(operator, { strict: false })) {
+    throw new InvalidOpenerTermsError("operator must be an EVM address");
+  }
+  if (typeof serviceRef !== "string") {
+    throw new InvalidOpenerTermsError("serviceRef must be a string");
+  }
+  const terms: OpenerTerms = {
+    operator: getAddress(operator),
+    serviceRef: serviceRef as Hex,
+    ratePerSecond: parseUintString(record.ratePerSecond, "ratePerSecond"),
+    maxDuration: parseUintString(record.maxDuration, "maxDuration"),
+  };
+  assertValidTerms(terms);
+  return { factory: getAddress(factory), terms };
+}
+
+/** Chain id encoded in an `eip155:<id>` CAIP-2 identifier. Throws otherwise. */
+export function chainIdFromNetwork(network: string): number {
+  const match = /^eip155:([1-9]\d*)$/.exec(network);
+  if (match === null) {
+    throw new InvalidOpenerTermsError(
+      `network must be an eip155 CAIP-2 identifier, got ${network}`,
+    );
+  }
+  const chainId = Number(match[1]);
+  if (!Number.isSafeInteger(chainId)) {
+    throw new InvalidOpenerTermsError(`unsupported chain id in ${network}`);
+  }
+  return chainId;
+}
+
+/** Solidity-tuple view of terms for viem contract calls. */
+export function termsTuple(terms: OpenerTerms): {
+  readonly operator: Address;
+  readonly serviceRef: Hex;
+  readonly ratePerSecond: bigint;
+  readonly maxDuration: bigint;
+} {
+  return {
+    operator: getAddress(terms.operator),
+    serviceRef: terms.serviceRef,
+    ratePerSecond: terms.ratePerSecond,
+    maxDuration: terms.maxDuration,
+  };
+}
+
+/** A bazaar-shaped `{info: {input, output?}, schema?}` declaration. */
+export interface X402SchemaDeclaration {
+  readonly info: {
+    readonly input: { readonly type: "http" } & Record<string, unknown>;
+    readonly output?: Record<string, unknown>;
+  };
+  readonly schema?: Record<string, unknown>;
+}
+
+/** Largest accepted schema declaration, serialized bytes. */
+export const MAX_SCHEMA_DECLARATION_BYTES = 16 * 1024;
+
+/** Validates a bazaar-shaped schema declaration. Throws on anything else. */
+export function assertSchemaDeclaration(
+  value: unknown,
+): asserts value is X402SchemaDeclaration {
+  if (JSON.stringify(value ?? null).length > MAX_SCHEMA_DECLARATION_BYTES) {
+    throw new Error(
+      `the schema declaration exceeds ${MAX_SCHEMA_DECLARATION_BYTES} bytes`,
+    );
+  }
+  const record = value as Record<string, unknown> | null;
+  const info = record?.info as Record<string, unknown> | undefined;
+  const input = info?.input as Record<string, unknown> | undefined;
+  if (
+    typeof record !== "object" ||
+    record === null ||
+    Array.isArray(record) ||
+    typeof info !== "object" ||
+    info === null ||
+    typeof input !== "object" ||
+    input === null ||
+    input.type !== "http" ||
+    (info.output !== undefined &&
+      (typeof info.output !== "object" || info.output === null)) ||
+    (record.schema !== undefined &&
+      (typeof record.schema !== "object" || record.schema === null))
+  ) {
+    throw new Error(
+      'the schema declaration must be {info: {input: {type: "http", ...}, output?}, schema?}',
+    );
+  }
+  for (const key of Object.keys(record)) {
+    if (key !== "info" && key !== "schema") {
+      throw new Error(`unknown key ${key} in the schema declaration`);
+    }
+  }
+}