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

package/src/discovery/rate-band.ts

@@ -0,0 +1,172 @@
+import { formatUnits } from "viem";
+
+import {
+  rateOutsideBounds,
+  SignedRateBoundsError,
+  verifySignedRateBounds,
+  type SignedRateBounds,
+} from "../gateway/signed-rate-bounds.js";
+
+/**
+ * The buyer-side twin of the gateway's signed-rate check.
+ *
+ * `StreamEscrowV2.openStream` accepts any non-zero `ratePerSecond`; the band a
+ * seller will actually SERVE lives in its operator-signed descriptor
+ * (`commercial.minRatePerSecond` / `maxRatePerSecond`), and the seller's
+ * capability gateway answers every request on an out-of-band stream with
+ * `403 stream-rate-out-of-bounds`. Opening such a stream locks the buyer's
+ * deposit in a stream that can never be served, so every buyer surface that
+ * takes a caller-chosen rate checks it against the SAME band, with the SAME
+ * verification ({@link verifySignedRateBounds}), before anything is broadcast.
+ *
+ * Nothing here is a second signature implementation: the bounds come only out
+ * of `verifySignedRateBounds`, which re-derives the serviceRef from the signed
+ * content and recovers the operator's EIP-712 signature.
+ */
+
+/** A listing as discovery hands it over: the serviceRef and its signed record. */
+export interface RateBandListing {
+  readonly serviceRef: string;
+  readonly signed: unknown;
+}
+
+/**
+ * The operator-signed rate band of a verified listing.
+ *
+ * - `null`: the listing is a legacy service BINDING, which carries no
+ *   commercial terms, so the operator signed no band and there is nothing to
+ *   enforce (the gateway enforces none either).
+ * - a {@link SignedRateBounds}: the descriptor verified. Either bound may still
+ *   be `null` when the operator signed only one side, or none.
+ *
+ * Throws {@link SignedRateBoundsError} when the record IS a descriptor but does
+ * not verify, or verifies for a different serviceRef than the listing claims.
+ * Callers must treat that as a refusal: a band that cannot be verified is not a
+ * band that can be assumed absent.
+ */
+export async function listingRateBand(
+  listing: RateBandListing,
+): Promise<SignedRateBounds | null> {
+  const signed = listing.signed;
+  if (
+    typeof signed !== "object" ||
+    signed === null ||
+    !("descriptor" in signed)
+  ) {
+    return null;
+  }
+  const bounds = await verifySignedRateBounds(signed);
+  if (bounds.serviceRef !== listing.serviceRef.toLowerCase()) {
+    throw new SignedRateBoundsError(
+      `the signed descriptor verifies for serviceRef ${bounds.serviceRef}, not the listed ${listing.serviceRef}`,
+    );
+  }
+  return bounds;
+}
+
+/** `0.0001` for `100n` — USDC has 6 decimals. */
+function usdc(atomic: bigint): string {
+  return formatUnits(atomic, 6);
+}
+
+/**
+ * The signed band in both units, e.g. `100..10000 atomic/s (0.0001..0.01
+ * USDC/s)`. A one-sided band reads `at least 100 atomic/s (…)` /
+ * `at most 10000 atomic/s (…)`.
+ */
+export function describeRateBand(bounds: SignedRateBounds): string {
+  const { minRatePerSecond: min, maxRatePerSecond: max } = bounds;
+  if (min !== null && max !== null) {
+    return `${min}..${max} atomic/s (${usdc(min)}..${usdc(max)} USDC/s)`;
+  }
+  if (min !== null) {
+    return `at least ${min} atomic/s (${usdc(min)} USDC/s)`;
+  }
+  if (max !== null) {
+    return `at most ${max} atomic/s (${usdc(max)} USDC/s)`;
+  }
+  return "any rate (the operator signed no bounds)";
+}
+
+/**
+ * `undefined` when `rate` is inside the operator-signed band (bounds are
+ * inclusive, exactly as the gateway applies them), otherwise an actionable
+ * refusal naming the band in atomic units and USDC. `rateLabel` is how the
+ * caller supplied the rate (`--rate`, `ratePerSecondUsdc`).
+ */
+export function rateBandRefusal(
+  rate: bigint,
+  bounds: SignedRateBounds,
+  rateLabel: string,
+): string | undefined {
+  const outside = rateOutsideBounds(rate, bounds);
+  if (outside === undefined) return undefined;
+  return `the operator signed rates ${describeRateBand(bounds)}; ${rateLabel} ${rate} (${usdc(rate)} USDC/s) would be refused by the service's gateway (${outside}), so the stream could never be served. Nothing was broadcast.`;
+}
+
+/**
+ * Outcome of {@link checkListedRateBand}: `ok: false` is a refusal, and its
+ * `message` is safe to hand straight back to the caller.
+ */
+export type ListedRateBandCheck =
+  | {
+      readonly ok: true;
+      /** `unlisted`: no verified listing, so no operator-signed band exists. */
+      readonly band: "in-band" | "no-band-signed" | "unlisted";
+    }
+  | { readonly ok: false; readonly message: string };
+
+/**
+ * Discover the serviceRef's verified listing(s) and check `rate` against every
+ * operator-signed band among them, for a surface that has no listing in hand.
+ *
+ * Fail closed: a registry that cannot be read means a signed band may exist and
+ * is unknown, so it is a refusal — never a pass. A serviceRef with no verified
+ * listing has no signed band to violate, and is allowed (these surfaces never
+ * required a listing to hire).
+ */
+export async function checkListedRateBand(
+  discover: () => Promise<readonly RateBandListing[]>,
+  serviceRef: string,
+  rate: bigint,
+  rateLabel: string,
+): Promise<ListedRateBandCheck> {
+  let listings: readonly RateBandListing[];
+  try {
+    listings = await discover();
+  } catch (error) {
+    return {
+      ok: false,
+      message: `refusing to hire: the service registry could not be read (${error instanceof Error ? error.message : String(error)}), so the operator-signed rate band for ${serviceRef} cannot be checked and the stream might never be served. Nothing was spent — retry when the registry answers.`,
+    };
+  }
+  const wanted = serviceRef.toLowerCase();
+  const matches = listings.filter(
+    (listing) => listing.serviceRef.toLowerCase() === wanted,
+  );
+  if (matches.length === 0) return { ok: true, band: "unlisted" };
+  let signedAny = false;
+  for (const listing of matches) {
+    let bounds: SignedRateBounds | null;
+    try {
+      bounds = await listingRateBand(listing);
+    } catch (error) {
+      if (error instanceof SignedRateBoundsError) {
+        return {
+          ok: false,
+          message: `refusing to hire: the listing's operator-signed rate band could not be verified (${error.message}). Nothing was spent.`,
+        };
+      }
+      throw error;
+    }
+    if (bounds === null) continue;
+    signedAny = true;
+    const refusal = rateBandRefusal(rate, bounds, rateLabel);
+    if (refusal !== undefined) {
+      return { ok: false, message: `refusing to hire: ${refusal}` };
+    }
+  }
+  return { ok: true, band: signedAny ? "in-band" : "no-band-signed" };
+}
+
+export { SignedRateBoundsError };

package/src/escrow-generation.ts

@@ -0,0 +1,135 @@
+import { findDeployment } from "@absol-labs/sdk";
+import type { Address, Hex } from "viem";
+
+/**
+ * Escrow-generation-specific rules, driven by the SDK network registry's
+ * `escrow.generation` (metrik-agent#121).
+ *
+ * Today the registry knows only `v2` (`StreamEscrowV2`). `StreamEscrowV3`
+ * changes one rule the agent reasons about: the buyer's no-proof escape hatch.
+ *
+ * - **V2**: `reclaimUnverified` opens at `expiresAt + escapeGraceSeconds`.
+ *   Closing early does NOT bring it forward.
+ * - **V3**: it opens at `min(expiresAt, closedAt) + escapeGraceSeconds`, and the
+ *   escrow exposes `escapeHatchReadyAt(bytes32)` to read it directly. Where a
+ *   chain read is available it is preferred over re-deriving the formula.
+ *
+ * An unknown generation is refused, never guessed: a wrong readiness answer
+ * either sends a buyer a guaranteed revert or tells them to wait when they need
+ * not. (V3 also restricts `recordProven` to the stream's operator or an active
+ * oracle signer; no agent or relay path calls it on a buyer's behalf.)
+ */
+
+/** Escrow generations whose escape-hatch rule this package implements. */
+export type KnownEscrowGeneration = "v2" | "v3";
+
+export class UnsupportedEscrowGenerationError extends Error {
+  readonly generation: string;
+
+  constructor(generation: string) {
+    super(
+      `escrow generation "${generation}" is not one this package knows the escape-hatch rule for (known: v2, v3)`,
+    );
+    this.name = "UnsupportedEscrowGenerationError";
+    this.generation = generation;
+  }
+}
+
+function known(generation: string): KnownEscrowGeneration {
+  if (generation === "v2" || generation === "v3") return generation;
+  throw new UnsupportedEscrowGenerationError(generation);
+}
+
+/**
+ * The generation of `escrow` on `chainId`, from the network registry. An escrow
+ * the registry does not record is treated as V2 — the generation every
+ * unregistered, explicitly configured Metrik deployment speaks today.
+ */
+export function escrowGenerationFor(
+  chainId: number,
+  escrow: Address,
+): KnownEscrowGeneration {
+  return known(
+    // The generation of THIS deployment (current or legacy), not of the
+    // network's current escrow.
+    findDeployment(chainId, escrow)?.deployment.escrow.generation ?? "v2",
+  );
+}
+
+/**
+ * The second the no-proof escape hatch opens, by formula. `closedAt` is `0`
+ * while the stream is open.
+ */
+export function escapeHatchReadyAtFormula(
+  generation: string,
+  stream: { readonly expiresAt: bigint; readonly closedAt: bigint },
+  graceSeconds: bigint,
+): bigint {
+  switch (known(generation)) {
+    case "v2":
+      return stream.expiresAt + graceSeconds;
+    case "v3": {
+      const stop =
+        stream.closedAt > 0n && stream.closedAt < stream.expiresAt
+          ? stream.closedAt
+          : stream.expiresAt;
+      return stop + graceSeconds;
+    }
+  }
+}
+
+/**
+ * `StreamEscrowV3.escapeHatchReadyAt(bytes32)`. A one-function fragment until
+ * the SDK ships the V3 ABI; replace it with the SDK's export then.
+ */
+export const streamEscrowV3EscapeHatchAbi = [
+  {
+    type: "function",
+    name: "escapeHatchReadyAt",
+    stateMutability: "view",
+    inputs: [{ name: "streamId", type: "bytes32" }],
+    outputs: [{ name: "", type: "uint256" }],
+  },
+] as const;
+
+/** The minimal read surface {@link readEscapeHatchReadyAt} needs. */
+export interface EscapeHatchReader {
+  readContract(args: {
+    readonly address: Address;
+    readonly abi: typeof streamEscrowV3EscapeHatchAbi;
+    readonly functionName: "escapeHatchReadyAt";
+    readonly args: readonly [Hex];
+  }): Promise<bigint>;
+}
+
+/**
+ * The escape-hatch second for one stream: V3 reads the escrow's own view (and
+ * falls back to the V3 formula if that read fails); V2 uses its formula.
+ */
+export async function readEscapeHatchReadyAt(input: {
+  readonly generation: string;
+  readonly reader: EscapeHatchReader;
+  readonly escrow: Address;
+  readonly streamId: Hex;
+  readonly stream: { readonly expiresAt: bigint; readonly closedAt: bigint };
+  readonly graceSeconds: bigint;
+}): Promise<bigint> {
+  const generation = known(input.generation);
+  if (generation === "v3") {
+    try {
+      return await input.reader.readContract({
+        address: input.escrow,
+        abi: streamEscrowV3EscapeHatchAbi,
+        functionName: "escapeHatchReadyAt",
+        args: [input.streamId],
+      });
+    } catch {
+      // Fall through to the V3 formula: the same rule the view implements.
+    }
+  }
+  return escapeHatchReadyAtFormula(
+    generation,
+    input.stream,
+    input.graceSeconds,
+  );
+}

package/src/frameworks/agentkit.ts

@@ -2,6 +2,7 @@ import "reflect-metadata";
 
 import type {
   HireComputeResult,
+  MetrikNetwork,
   StreamProofClientConfig,
 } from "@absol-labs/sdk";
 import {
@@ -19,7 +20,13 @@ import {
   type DiscoverServicesOptions,
   type ServiceListing,
 } from "../discovery/registry.js";
+import { checkListedRateBand } from "../discovery/rate-band.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
+import {
+  defaultNetwork,
+  describeAllowedNetworks,
+  requireNetworkForChainId,
+} from "../network.js";
 import {
   isCheckpointStream,
   MandateDeniedError,
@@ -34,10 +41,17 @@ import {
 } from "../sdk/client.js";
 
 /**
- * Base Sepolia is the only settlement network Metrik supports today (Model A,
- * single-chain USDC on Base). Every action fails closed on any other network.
+ * The default settlement chain id: the registry's default network. A provider
+ * may be configured for any REGISTERED TESTNET network instead; every action
+ * fails closed on a network the registry does not know, on a mainnet, and on a
+ * wallet whose network differs from the configured one.
  */
-export const METRIK_BASE_SEPOLIA_CHAIN_ID = 84532;
+export const METRIK_AGENTKIT_DEFAULT_CHAIN_ID: number =
+  defaultNetwork().chain.id;
+
+/** @deprecated Use {@link METRIK_AGENTKIT_DEFAULT_CHAIN_ID}; this is the registry's default network, read from the SDK registry. */
+export const METRIK_BASE_SEPOLIA_CHAIN_ID: number =
+  METRIK_AGENTKIT_DEFAULT_CHAIN_ID;
 
 const addressSchema = z
   .string()
@@ -159,7 +173,7 @@ export interface MetrikActionProviderConfig {
    * agent's construction — the LLM never supplies or edits it.
    */
   readonly signedMandate: SignedSpendMandate;
-  /** Settlement chain id. Defaults to Base Sepolia (84532); any other value fails closed. */
+  /** Settlement chain id. Defaults to the registry's default network; a chain the registry does not know as a testnet fails closed. */
   readonly chainId?: number;
   /** Injected Metrik client (test path). Mutually exclusive with `sdkConfig`. */
   readonly agentClient?: MetrikAgentKitClient;
@@ -232,6 +246,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
   readonly #resolver: Partial<MetrikMandateStateResolver>;
   readonly #now: () => number;
   readonly #chainId: number;
+  readonly #network: MetrikNetwork;
   readonly #discover: (
     opts?: DiscoverServicesOptions,
   ) => Promise<ServiceListing[]>;
@@ -239,11 +254,17 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
   constructor(config: MetrikActionProviderConfig) {
     super("metrik", []);
 
-    this.#chainId = config.chainId ?? METRIK_BASE_SEPOLIA_CHAIN_ID;
-    if (this.#chainId !== METRIK_BASE_SEPOLIA_CHAIN_ID) {
-      // Fail closed: Model A settles only on Base Sepolia today.
+    this.#chainId = config.chainId ?? METRIK_AGENTKIT_DEFAULT_CHAIN_ID;
+    try {
+      this.#network = requireNetworkForChainId(
+        this.#chainId,
+        { testnetOnly: true },
+        "chainId",
+      );
+    } catch (error) {
+      // Fail closed: only a registered testnet network settles.
       throw new MetrikActionProviderConfigError(
-        `unsupported chainId ${this.#chainId}: Metrik settles only on Base Sepolia (${METRIK_BASE_SEPOLIA_CHAIN_ID})`,
+        `unsupported chainId ${this.#chainId}: Metrik settles only on registered testnet networks (${describeAllowedNetworks({ testnetOnly: true })}) — ${error instanceof Error ? error.message : String(error)}`,
       );
     }
 
@@ -361,6 +382,19 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
       throw new MandateDeniedError(decision.reason ?? "mandate-expired");
     }
 
+    // The rate must sit inside the band the operator SIGNED, or the seller's
+    // gateway refuses every request on the stream while the deposit stays
+    // escrowed. Fails closed when the registry cannot be read.
+    const band = await checkListedRateBand(
+      () => this.#discover(),
+      serviceRef,
+      ratePerSecondUsdc,
+      "ratePerSecondUsdc",
+    );
+    if (!band.ok) {
+      throw new Error(band.message);
+    }
+
     const result = await this.#client.openVerifiedStream({
       operator,
       serviceRef,
@@ -375,7 +409,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
 
     const urlLine = args.publicUrl ? ` Endpoint: ${args.publicUrl}.` : "";
     return (
-      `Hired verified service via Metrik. Stream ${result.streamId} opened on Base Sepolia (escrow ${result.handle.escrow}). ` +
+      `Hired verified service via Metrik. Stream ${result.streamId} opened on ${this.#network.name} (escrow ${result.handle.escrow}). ` +
       `Escrowed ${formatUsdc(budgetUsdc)} USDC at ${formatUsdc(ratePerSecondUsdc)} USDC/sec to operator ${operator} for service ${serviceRef}, ` +
       `max ${maxDurationSeconds}s. Payment accrues only for oracle-verified delivery; unspent USDC is reclaimable.${urlLine} ` +
       `tx=${result.txHash}${result.approveTxHash ? ` approve=${result.approveTxHash}` : ""}`
@@ -457,7 +491,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
   }
 
   supportsNetwork(network: Network): boolean {
-    // Fail closed: EVM Base Sepolia only.
+    // Fail closed: the configured EVM network only.
     return (
       network.protocolFamily === "evm" &&
       network.chainId === String(this.#chainId)
@@ -468,7 +502,7 @@ export class MetrikActionProvider extends ActionProvider<WalletProvider> {
     const network = walletProvider.getNetwork();
     if (!this.supportsNetwork(network)) {
       throw new MetrikActionProviderConfigError(
-        `unsupported network ${network.protocolFamily}:${network.chainId ?? "unknown"}: Metrik requires Base Sepolia (evm:${this.#chainId})`,
+        `unsupported network ${network.protocolFamily}:${network.chainId ?? "unknown"}: Metrik requires ${this.#network.name} (evm:${this.#chainId})`,
       );
     }
   }

package/src/frameworks/eliza.ts

@@ -13,6 +13,7 @@ import {
   type DiscoverServicesOptions,
   type ServiceListing,
 } from "../discovery/registry.js";
+import { checkListedRateBand } from "../discovery/rate-band.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
   isCheckpointStream,
@@ -23,12 +24,14 @@ import {
   type StreamStatusView,
   type VerifiedStreamAgentOpener,
 } from "../sdk/client.js";
+import { defaultNetwork } from "../network.js";
 
 /**
- * Base Sepolia is the only settlement network Metrik supports today (Model A,
- * single-chain USDC on Base).
+ * The settlement chain id the Eliza plugin's examples and defaults use: the
+ * registry's default network, read from the `@absol-labs/sdk` network registry.
  */
-export const METRIK_ELIZA_SETTLEMENT_CHAIN_ID = 84532;
+export const METRIK_ELIZA_SETTLEMENT_CHAIN_ID: number =
+  defaultNetwork().chain.id;
 
 const addressSchema = z
   .string()
@@ -195,7 +198,12 @@ export function createMetrikElizaPlugin(
       "Mandate-gated Metrik actions for hiring, monitoring, reclaiming, and closing verified service streams on Base. x402 proves the payment, Metrik proves the delivery.",
     actions: [
       createDiscoverAction(options.discoverServices ?? defaultDiscoverServices),
-      createHireAction(options.agentClient, resolver, now),
+      createHireAction(
+        options.agentClient,
+        resolver,
+        now,
+        options.discoverServices ?? defaultDiscoverServices,
+      ),
       createStatusAction(options.agentClient),
       createReclaimAction(options.agentClient, resolver, now),
       createCloseAction(options.agentClient, resolver, now),
@@ -277,6 +285,7 @@ function createHireAction(
   agentClient: MetrikElizaClient,
   resolver: MetrikElizaMandateStateResolver,
   now: () => number,
+  discover: (opts?: DiscoverServicesOptions) => Promise<ServiceListing[]>,
 ): Action {
   return {
     name: "HIRE_VERIFIED_SERVICE",
@@ -328,6 +337,19 @@ function createHireAction(
           );
         }
 
+        // The rate must sit inside the band the operator SIGNED, or the
+        // seller's gateway refuses every request on the stream while the
+        // deposit stays escrowed. Fails closed when the registry cannot be read.
+        const band = await checkListedRateBand(
+          () => discover(),
+          input.serviceRef,
+          BigInt(input.ratePerSecondUsdc),
+          "ratePerSecondUsdc",
+        );
+        if (!band.ok) {
+          return await failureResult(band.message, callback);
+        }
+
         const result = await agentClient.openVerifiedStream({
           operator: input.operator as `0x${string}`,
           serviceRef: input.serviceRef as `0x${string}`,
@@ -507,7 +529,7 @@ function createExamples(action: MetrikElizaActionName): ActionExample[][] {
   const exampleMandate = {
     mandateId: `0x${"55".repeat(32)}`,
     owner: "0x1111111111111111111111111111111111111111",
-    chainId: 84532,
+    chainId: METRIK_ELIZA_SETTLEMENT_CHAIN_ID,
     issuedAt: 1_900_000_000,
     mandate: {
       maxPerStreamUsdc: "100000000",

package/src/frameworks/langchain.ts

@@ -7,6 +7,7 @@ import {
   type DiscoverServicesOptions,
   type ServiceListing,
 } from "../discovery/registry.js";
+import { checkListedRateBand } from "../discovery/rate-band.js";
 import { checkMandate, type SignedSpendMandate } from "../mandates/mandate.js";
 import {
   isCheckpointStream,
@@ -206,6 +207,19 @@ export function createLangChainVerifiedStreamTools(
           throw new Error(`mandate denied: ${decision.reason ?? "unknown"}`);
         }
 
+        // The rate must sit inside the band the operator SIGNED, or the
+        // seller's gateway refuses every request on the stream while the
+        // deposit stays escrowed. Fails closed when the registry cannot be read.
+        const band = await checkListedRateBand(
+          () => discoverImpl(),
+          input.serviceRef,
+          BigInt(input.ratePerSecondUsdc),
+          "ratePerSecondUsdc",
+        );
+        if (!band.ok) {
+          throw new Error(band.message);
+        }
+
         const result = await options.agentClient.openVerifiedStream({
           operator: input.operator as `0x${string}`,
           serviceRef: input.serviceRef as `0x${string}`,