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

package/src/cli/commands/refund.ts

@@ -0,0 +1,277 @@
+import type {
+  RefundClient,
+  RefundRelayResult,
+  RefundStatus,
+  X402PayerSigner,
+} from "@absol-labs/sdk/x402";
+
+import { verifyMandateOwnerSignature } from "../../mandates/mandate.js";
+import { booleanFlag, integerFlag, stringFlag } from "../args.js";
+import { formatUsdc } from "../amounts.js";
+import { assertTestnetRpc, parseBytes32 } from "../config.js";
+import type { CliX402 } from "../deps.js";
+import { CliError, configError, usageError } from "../errors.js";
+import { signRecoveryMandate } from "../mandate.js";
+import { isPrivyWalletSource, resolveCliWallet } from "../wallet.js";
+import type { CommandContext, CommandSpec } from "../context.js";
+
+/** Environment fallback for `--refund-url`. */
+export const REFUND_URL_ENV = "METRIK_AGENT_REFUND_URL";
+
+const DEFAULT_ATTEMPTS = 5;
+const DEFAULT_MAX_WAIT_SECONDS = 60;
+
+export const refundCommand: CommandSpec = {
+  name: "refund",
+  summary:
+    "Recover the unearned part of an x402 payment through the gasless refund relay",
+  usage:
+    "metrik refund <streamId> --refund-url <url> [--close] [--reclaim] [--attempts 5] [--max-wait 60]",
+  flags: ["refund-url", "close", "reclaim", "attempts", "max-wait"],
+  // `--close` signs the payer's EIP-712 Close (off-chain); the RELAY broadcasts
+  // and pays the gas. `--reclaim` needs no wallet at all: `opener.reclaim` is
+  // permissionless and always pays `payerOf(streamId)`.
+  signs: false,
+  requiresKey: false,
+  async run(context: CommandContext): Promise<void> {
+    const { args, config, env, out, deps } = context;
+    if (deps.x402 === undefined) {
+      throw new CliError(
+        "this CLI build has no x402 dependency wired (CliDependencies.x402)",
+        { exitCode: 4 },
+      );
+    }
+    const x402: CliX402 = deps.x402;
+    const [streamIdArg] = args.positionals;
+    if (streamIdArg === undefined) {
+      throw usageError("metrik refund requires a <streamId>");
+    }
+    const streamId = parseBytes32(streamIdArg, "<streamId>");
+    const refundUrl = resolveRefundUrl(
+      stringFlag(args, "refund-url") ?? env[REFUND_URL_ENV],
+      streamId,
+    );
+    const doClose = booleanFlag(args, "close");
+    const doReclaim = booleanFlag(args, "reclaim");
+    const attempts = integerFlag(args, "attempts") ?? DEFAULT_ATTEMPTS;
+    const maxWait = integerFlag(args, "max-wait") ?? DEFAULT_MAX_WAIT_SECONDS;
+    if (attempts < 1) throw usageError("--attempts must be at least 1");
+
+    const read = deps.createReadClient(config);
+    await assertTestnetRpc(config, () => read.getChainId());
+    // Bind the relay to the stream AS THE CHAIN SEES IT: the opener comes from
+    // `factory.isOpener(buyer)` on-chain, never from the relay's answer.
+    const stream = await read.getStreamV2(streamId);
+    const opener = stream.opener ?? null;
+    if (opener === null) {
+      throw configError(
+        `stream ${streamId} was not opened by an x402 opener, so the refund relay does not serve it`,
+        `the buyer is ${stream.buyer}, an ordinary wallet: use \`metrik close ${streamId}\` and \`metrik reclaim ${streamId}\` with that wallet.`,
+      );
+    }
+
+    const refunds = await x402.refundClient(config, {
+      refundUrl,
+      streamId,
+      opener,
+      maxAttempts: attempts,
+      maxDelayMs: maxWait * 1_000,
+    });
+
+    let closeResult: RefundRelayResult | null = null;
+    if (doClose) {
+      const wallet = await resolveCliWallet(env, {
+        purpose: "capability",
+        note: out.note,
+        rpcUrl: config.rpcUrl,
+      });
+      if (isPrivyWalletSource(wallet.source)) {
+        throw configError(
+          "metrik refund --close cannot sign with a Privy wallet",
+          "the payer signs the opener's EIP-712 Close, which the Privy broker's typed-data policy does not allow. Use the key that paid.",
+        );
+      }
+      // Buyer recovery: authorized on the mandate OWNER's signature alone, like
+      // `metrik close` — never on caps or expiry, so nothing can strand the
+      // payer's own money. The SDK then refuses a signer that is not
+      // `payerOf(streamId)` before anything is signed for the relay.
+      const mandate = await signRecoveryMandate(wallet.account, config.chainId);
+      const decision = await verifyMandateOwnerSignature(mandate);
+      if (!decision.allowed) {
+        throw new CliError(`mandate denied: ${decision.reason}`, {
+          exitCode: 3,
+        });
+      }
+      closeResult = await relay(() =>
+        refunds.close({
+          signer: wallet.account as unknown as X402PayerSigner,
+        }),
+      );
+      out.note(
+        `close relayed in ${closeResult.transaction}${closeResult.verified ? " (receipt verified on-chain)" : ""}`,
+      );
+    }
+
+    let reclaimResult: RefundRelayResult | null = null;
+    if (doReclaim) {
+      reclaimResult = await relay(() => refunds.reclaim());
+    }
+
+    const status = await relay(() => refunds.status());
+    out.result({
+      streamId,
+      opener,
+      payer: status.payer,
+      status: status.status,
+      reclaimed: status.reclaimed,
+      reclaimable: status.reclaimable,
+      next: status.next,
+      close:
+        closeResult === null
+          ? null
+          : {
+              transaction: closeResult.transaction,
+              verified: closeResult.verified,
+            },
+      reclaim:
+        reclaimResult === null
+          ? null
+          : {
+              transaction: reclaimResult.transaction,
+              amount: reclaimResult.amount,
+              verified: reclaimResult.verified,
+            },
+      refundIsAutomatic: false,
+    });
+    out.print(`x402 stream ${streamId}`);
+    out.table(statusRows(status, closeResult, reclaimResult));
+    out.print("");
+    out.print(nextStep(status, streamId, refundUrl));
+  },
+};
+
+/**
+ * Accepts the relay's full stream URL, a `{streamId}` template, or the relay's
+ * base origin (`https://relay.example` -> `https://relay.example/streams/<id>`).
+ */
+export function resolveRefundUrl(
+  raw: string | undefined,
+  streamId: `0x${string}`,
+): string {
+  if (raw === undefined || raw.trim().length === 0) {
+    throw usageError(
+      `metrik refund needs the seller's refund relay: pass --refund-url (printed by \`metrik pay\`) or set ${REFUND_URL_ENV}`,
+    );
+  }
+  const value = raw.trim();
+  if (value.includes("{streamId}")) return value;
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw usageError(
+      `--refund-url must be an absolute http(s) URL (got "${value}")`,
+    );
+  }
+  if (/\/streams\/0x[0-9a-fA-F]{64}\/?$/.test(url.pathname)) return value;
+  url.pathname = `${url.pathname.replace(/\/+$/, "")}/streams/${streamId}`;
+  return url.toString();
+}
+
+async function relay<T>(task: () => Promise<T>): Promise<T> {
+  try {
+    return await task();
+  } catch (error) {
+    throw explainRefundFailure(error);
+  }
+}
+
+export function explainRefundFailure(error: unknown): unknown {
+  if (!(error instanceof Error)) return error;
+  switch (error.name) {
+    case "RefundNotReadyError": {
+      const retryAt = (error as { retryAt?: number | null }).retryAt;
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint:
+          retryAt === undefined || retryAt === null
+            ? "the relay is not ready to reclaim yet (the settlement window is open). Re-run later with --reclaim."
+            : `the relay can reclaim from ${new Date(retryAt * 1000).toISOString()}. Re-run then with --reclaim (or raise --max-wait to wait here).`,
+        cause: error,
+      });
+    }
+    case "RefundRelayError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: `relay refusal${(error as { code?: string }).code === undefined ? "" : ` (${(error as { code?: string }).code})`}. The payer can always recover on-chain without the relay: \`metrik close\` (as the payer, needs gas) and \`metrik reclaim\` (anyone).`,
+        cause: error,
+      });
+    case "NotStreamPayerError":
+      return new CliError(error.message, {
+        exitCode: 3,
+        hint: "only the address that paid (payerOf(streamId)) can sign the close. Nothing was signed.",
+        cause: error,
+      });
+    default:
+      return error;
+  }
+}
+
+function statusRows(
+  status: RefundStatus,
+  closeResult: RefundRelayResult | null,
+  reclaimResult: RefundRelayResult | null,
+): (readonly [string, string])[] {
+  const rows: (readonly [string, string])[] = [
+    [
+      "status",
+      status.reclaimed ? `${status.status} (reclaimed)` : status.status,
+    ],
+    ["payer", status.payer],
+    ["opener", status.opener],
+    [
+      "reclaimable",
+      status.reclaimable === null ? "-" : formatUsdc(status.reclaimable),
+    ],
+    ["next", status.next.action],
+  ];
+  if (closeResult !== null) {
+    rows.push([
+      "close tx",
+      `${closeResult.transaction}${closeResult.verified ? " (verified)" : " (relay-reported)"}`,
+    ]);
+  }
+  if (reclaimResult !== null) {
+    rows.push([
+      "reclaim tx",
+      `${reclaimResult.transaction}${reclaimResult.verified ? " (verified)" : " (relay-reported)"}`,
+    ]);
+    if (reclaimResult.amount !== null) {
+      rows.push(["refunded to payer", formatUsdc(reclaimResult.amount)]);
+    }
+  }
+  return rows;
+}
+
+function nextStep(
+  status: RefundStatus,
+  streamId: `0x${string}`,
+  refundUrl: string,
+): string {
+  if (status.reclaimed) {
+    return "Reclaimed: the unearned remainder was returned to the payer.";
+  }
+  const base = `metrik refund ${streamId} --refund-url ${refundUrl}`;
+  switch (status.next.action) {
+    case "close":
+      return `Refunds are NOT automatic. The stream is still running: stop it with  ${base} --close --reclaim`;
+    case "reclaim":
+      return `Refunds are NOT automatic. Reclaim the unearned remainder with  ${base} --reclaim`;
+    case "wait":
+      return `Refunds are NOT automatic, and the settlement window is still open${status.next.retryAt === undefined ? "" : ` until ${new Date(status.next.retryAt * 1000).toISOString()}`}. Then run  ${base} --reclaim`;
+    default:
+      return `Refunds are NOT automatic. The relay says: ${status.next.message ?? status.next.action}.`;
+  }
+}
+
+export type { RefundClient };

package/src/cli/commands/status.ts

@@ -7,6 +7,7 @@ import {
   streamReportRows,
 } from "../status.js";
 import type { CommandContext, CommandSpec } from "../context.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 export const statusCommand: CommandSpec = {
   name: "status",
@@ -28,7 +29,12 @@ export const statusCommand: CommandSpec = {
     // diverge from index 5 onward, so a wrong-chain read does not revert — it
     // silently decodes something else into fields with the right names.
     await assertTestnetRpc(config, () => read.getChainId());
-    const report = await readStreamReport(read, streamId, deps.nowSeconds());
+    const report = await readStreamReport(
+      read,
+      streamId,
+      deps.nowSeconds(),
+      escrowGenerationFor(config.chainId, config.escrow),
+    );
 
     out.result(streamReportJson(report));
     // Who attests, before the numbers. Printed on stderr so it survives `--json`
@@ -40,6 +46,16 @@ export const statusCommand: CommandSpec = {
     if (disclosure !== null) out.note(disclosure);
     out.print(`Stream ${streamId}`);
     out.table(streamReportRows(report));
+    const opener = report.stream.opener ?? null;
+    if (opener !== null) {
+      out.print("");
+      out.print(
+        `Bought over x402: the escrow accepts close/reclaim only from the opener ${opener}. ` +
+          `\`metrik close ${streamId}\` (signed by the payer ${report.stream.payer}) routes through it; ` +
+          `\`metrik reclaim ${streamId}\` sends the permissionless opener.reclaim, and the refund always goes to the payer. ` +
+          "A payer with no gas can use the seller's relay instead: `metrik refund <streamId> --refund-url <url> --close --reclaim`. Nothing refunds automatically.",
+      );
+    }
     if (report.settlement.pending) {
       out.print("");
       out.print(

package/src/cli/commands/streams.ts

@@ -1,11 +1,11 @@
-import { BASE_SEPOLIA_ESCROW_V2 } from "@absol-labs/sdk";
 import { getAddress, isAddress } from "viem";
 
 import { integerFlag, stringFlag } from "../args.js";
 import { formatUsdc } from "../amounts.js";
 import {
-  BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
   assertTestnetRpc,
+  escrowDeployBlock,
+  type CliConfig,
 } from "../config.js";
 import { CliError, configError, usageError } from "../errors.js";
 import { escrowScanRange } from "../scan-range.js";
@@ -32,7 +32,7 @@ const SCAN_CONCURRENCY = 6;
 /**
  * Attempts per window before it is reported as unscanned. A public RPC answers
  * a burst of `eth_getLogs` with an occasional 429 — measured against
- * `sepolia.base.org`, 2 of 212 windows on a full-history scan — and a transient
+ * the network's public RPC, 2 of 212 windows on a full-history scan — and a transient
  * rate-limit is NOT a window that cannot be scanned. Declaring it one would
  * make the "this scan is incomplete" warning routine, and a warning that fires
  * on every healthy run is a warning nobody reads on the run that matters.
@@ -71,7 +71,7 @@ export const streamsCommand: CommandSpec = {
     // else into fields with the right names.
     await assertTestnetRpc(config, () => read.getChainId());
 
-    const anchor = resolveAnchorBlock(args, config.escrow);
+    const anchor = resolveAnchorBlock(args, config);
     const head = await read.blockNumber();
     const range = escrowScanRange(head, anchor.block);
 
@@ -234,7 +234,7 @@ async function resolveScanAddress(
   if (wallet === null) {
     throw configError(
       "metrik streams needs a wallet to know whose streams to list",
-      `pass --address 0x… to list any address's streams without one, or set ${PRIVATE_KEY_ENV} (or the CDP variables).`,
+      `pass --address 0x… to list any address's streams without one, or set ${PRIVATE_KEY_ENV} (or the CDP or Privy variables).`,
     );
   }
   return wallet.account.address;
@@ -251,25 +251,21 @@ async function resolveScanAddress(
  */
 function resolveAnchorBlock(
   args: CommandContext["args"],
-  escrow: `0x${string}`,
+  config: CliConfig,
 ): { readonly block: bigint; readonly canary: bigint | null } {
   const override = integerFlag(args, "from-block");
-  const isKnownEscrow =
-    escrow.toLowerCase() === BASE_SEPOLIA_ESCROW_V2.toLowerCase();
+  const deployBlock = escrowDeployBlock(config);
 
   if (override !== undefined) {
     return { block: BigInt(override), canary: null };
   }
-  if (!isKnownEscrow) {
+  if (deployBlock === undefined) {
     throw configError(
-      `no scan anchor is known for escrow ${escrow}`,
-      "the scan is anchored at the escrow's deploy block, and this CLI only ships that block for its default Base Sepolia escrow. Pass --from-block <deploy block> for a different escrow.",
+      `no scan anchor is known for escrow ${config.escrow}`,
+      `the scan is anchored at the escrow's deploy block, and the network registry only records it for ${config.network.name}'s registered escrow (${config.network.escrow.address}). Pass --from-block <deploy block> for a different escrow.`,
     );
   }
-  return {
-    block: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
-    canary: BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK,
-  };
+  return { block: deployBlock, canary: deployBlock };
 }
 
 /**

package/src/cli/commands/watch.ts

@@ -7,6 +7,7 @@ import {
   streamReportRows,
 } from "../status.js";
 import type { CommandContext, CommandSpec } from "../context.js";
+import { escrowGenerationFor } from "../../escrow-generation.js";
 
 const DEFAULT_INTERVAL_SECONDS = 15;
 
@@ -43,7 +44,12 @@ export const watchCommand: CommandSpec = {
 
       let report;
       try {
-        report = await readStreamReport(read, streamId, deps.nowSeconds());
+        report = await readStreamReport(
+          read,
+          streamId,
+          deps.nowSeconds(),
+          escrowGenerationFor(config.chainId, config.escrow),
+        );
       } catch (error) {
         // A transient RPC blip must not end a long watch.
         out.note(`read failed, retrying: ${describeError(error)}`);

package/src/cli/config.ts

@@ -1,76 +1,97 @@
-import {
-  BASE_SEPOLIA_ESCROW_V2,
-  BASE_SEPOLIA_USDC,
-  DEFAULT_ORACLE_BASE_URL,
-  DEFAULT_PUBLIC_REGISTRY_URL,
-} from "@absol-labs/sdk";
-import { isAddress, getAddress } from "viem";
-import { baseSepolia } from "viem/chains";
+import type { MetrikNetwork } from "@absol-labs/sdk";
+import { isAddress, getAddress, type Chain } from "viem";
 
+import {
+  allowedNetworks,
+  describeAllowedNetworks,
+  registeredDeployment,
+  METRIK_NETWORK_ENV,
+  resolveAgentNetwork,
+  UnsupportedNetworkError,
+} from "../network.js";
 import { CliError, configError, usageError } from "./errors.js";
 import { stringFlag, integerFlag, type ParsedArgs } from "./args.js";
 
 /**
- * TESTNET ONLY — the single allowlist this CLI will settle against.
+ * TESTNET ONLY — the CLI settles only on registered networks the SDK registry
+ * marks `testnet: true`.
  *
  * Metrik's escrow moves real USDC the moment it is pointed at a mainnet chain,
  * and this CLI signs with a raw private key read from the environment. So the
- * chain is an allowlist, not a default: any other chain id is refused outright,
- * with no override flag. There is deliberately no `--allow-mainnet` — an escape
- * hatch that re-enables real funds would defeat the guarantee, and a mainnet
- * deployment is not something a flag can conjure (there is none).
+ * chain is an allowlist, not a default: a chain the registry does not know, or
+ * one it knows as a mainnet, is refused outright, with no override flag. There
+ * is deliberately no `--allow-mainnet` — an escape hatch that re-enables real
+ * funds would defeat the guarantee.
  *
- * The allowlist is enforced TWICE: once against the configured/declared chain
- * id, and again against the chain id the RPC endpoint actually reports before
- * any fund-moving command signs anything (see `assertTestnetRpc`). The second
- * check is what stops `--chain-id 84532 --rpc-url <a mainnet RPC>`.
+ * The allowlist is enforced TWICE: once against the configured/declared network,
+ * and again against the chain id the RPC endpoint actually reports before any
+ * fund-moving command signs anything (see `assertTestnetRpc`). The second check
+ * is what stops a testnet `--chain-id` paired with a mainnet `--rpc-url`.
  */
-export const TESTNET_CHAIN_IDS: readonly number[] = [baseSepolia.id];
+export const CLI_NETWORK_POLICY = { testnetOnly: true } as const;
+
+/** Chain ids of every registered testnet this CLI will settle against. */
+export function testnetChainIds(): number[] {
+  return allowedNetworks(CLI_NETWORK_POLICY).map((network) => network.chain.id);
+}
 
 /**
- * The block `BASE_SEPOLIA_ESCROW_V2` was deployed at — the anchor of every
- * escrow log scan, because the contract has no history before it.
- *
- * Verified against Base Sepolia on 2026-09-17: `eth_getLogs` for this single
- * block returns 6 escrow logs (the deployment's own events). History is
- * immutable, so that is a stable known answer forever, which is what lets the
- * same block serve as the log-retention canary in `metrik streams`.
- *
- * It is tied to that ONE address. A run pointed at a different `--escrow` has
- * no anchor and must be given `--from-block`, rather than silently scanning
- * from a block that means nothing for it.
+ * @deprecated Snapshot of {@link testnetChainIds} at import time. A network
+ * registered later is not in it; call `testnetChainIds()` instead.
  */
-export const BASE_SEPOLIA_ESCROW_V2_DEPLOY_BLOCK = 45_892_018n;
+export const TESTNET_CHAIN_IDS: readonly number[] = testnetChainIds();
 
 export interface CliConfig {
-  readonly chain: typeof baseSepolia;
+  /** The registered network this run settles on (from the SDK registry). */
+  readonly network: MetrikNetwork;
+  readonly chain: Chain;
   readonly chainId: number;
   readonly rpcUrl: string;
   readonly escrow: `0x${string}`;
   readonly usdc: `0x${string}`;
   readonly oracleBaseUrl: string;
   readonly registryUrl: string;
+  /**
+   * Set ONLY for an `--escrow` the registry does not record, from the explicit
+   * `--escrow-generation`: the SDK then opts out of its code-hash pin
+   * (`allowUnregisteredEscrow`). A registered escrow's generation comes from
+   * the registry.
+   */
+  readonly unregisteredEscrowGeneration?: "v2" | "v3";
+}
+
+/**
+ * The block the configured escrow was deployed at — the anchor of every escrow
+ * log scan — or `undefined` when the escrow is not the network's registered
+ * escrow (a run pointed at a different `--escrow` has no anchor and must be
+ * given `--from-block`, rather than silently scanning from a block that means
+ * nothing for it).
+ */
+export function escrowDeployBlock(config: CliConfig): bigint | undefined {
+  return registeredDeployment(config.network, config.escrow)?.escrow
+    .deployBlock;
 }
 
 /**
- * Resolves settlement configuration from flags, then env, then the baked-in
- * Base Sepolia defaults — so `metrik discover` works with nothing configured at
+ * Resolves settlement configuration from flags, then env, then the network's
+ * registry defaults — so `metrik discover` works with nothing configured at
  * all, while every value stays overridable.
+ *
+ * The network is selected by `--network` / `METRIK_NETWORK` (registry id,
+ * chain id or CAIP-2 id) or by `--chain-id` / `METRIK_AGENT_CHAIN_ID`; giving
+ * both is allowed only when they agree.
  */
 export function resolveConfig(
   args: ParsedArgs,
   env: NodeJS.ProcessEnv,
 ): CliConfig {
-  const chainId =
-    integerFlag(args, "chain-id") ??
-    parseEnvChainId(env.METRIK_AGENT_CHAIN_ID) ??
-    baseSepolia.id;
-  assertTestnetChainId(chainId, "the configured chain id");
+  const network = resolveCliNetwork(args, env);
+  const chainId = network.chain.id;
 
   const rpcUrl =
     stringFlag(args, "rpc-url") ??
     env.METRIK_AGENT_RPC_URL ??
-    baseSepolia.rpcUrls.default.http[0];
+    network.rpcUrls[0];
   if (rpcUrl === undefined || !isHttpUrl(rpcUrl)) {
     throw configError(
       `RPC URL must be an http(s) URL (got "${rpcUrl ?? "undefined"}")`,
@@ -78,35 +99,101 @@ export function resolveConfig(
     );
   }
 
+  const escrow = resolveAddress(
+    stringFlag(args, "escrow") ?? env.METRIK_AGENT_ESCROW,
+    network.escrow.address,
+    "escrow",
+  );
+  const declared = (
+    stringFlag(args, "escrow-generation") ?? env.METRIK_AGENT_ESCROW_GENERATION
+  )
+    ?.trim()
+    .toLowerCase();
+  if (declared !== undefined && declared !== "v2" && declared !== "v3") {
+    throw configError(
+      `--escrow-generation must be "v2" or "v3" (got "${declared}")`,
+    );
+  }
+  const deployment = registeredDeployment(network, escrow);
+  if (deployment === undefined && declared === undefined) {
+    throw configError(
+      `escrow ${escrow} is not a registered deployment of ${network.name}`,
+      `the SDK pins registered escrows by code hash; for your own deployment pass --escrow-generation v2|v3 (it then only checks the interface, which any contract can fake). Registered: ${[network.escrow, ...network.legacy.map((d) => d.escrow)].map((e) => `${e.address} (${e.generation})`).join(", ")}.`,
+    );
+  }
+  if (
+    deployment !== undefined &&
+    declared !== undefined &&
+    declared !== deployment.escrow.generation
+  ) {
+    throw configError(
+      `--escrow-generation ${declared} contradicts the registry: ${escrow} is the ${deployment.escrow.generation} escrow`,
+    );
+  }
+
   return {
-    chain: baseSepolia,
+    network,
+    chain: network.chain,
     chainId,
     rpcUrl,
-    escrow: resolveAddress(
-      stringFlag(args, "escrow") ?? env.METRIK_AGENT_ESCROW,
-      BASE_SEPOLIA_ESCROW_V2,
-      "escrow",
-    ),
+    escrow,
+    ...(deployment === undefined
+      ? { unregisteredEscrowGeneration: declared as "v2" | "v3" }
+      : {}),
     usdc: resolveAddress(
       stringFlag(args, "usdc") ?? env.METRIK_AGENT_USDC,
-      BASE_SEPOLIA_USDC,
+      network.usdc.address,
       "usdc",
     ),
     oracleBaseUrl: resolveHttpUrl(
       stringFlag(args, "oracle-url") ?? env.METRIK_AGENT_ORACLE_URL,
-      DEFAULT_ORACLE_BASE_URL,
+      network.oracleBaseUrl,
       "oracle-url",
     ),
     registryUrl: resolveHttpUrl(
       stringFlag(args, "registry-url") ?? env.METRIK_AGENT_REGISTRY_URL,
-      DEFAULT_PUBLIC_REGISTRY_URL,
+      network.publicRegistryUrl ?? `${network.oracleBaseUrl}/listings`,
       "registry-url",
     ),
   };
 }
 
+function resolveCliNetwork(
+  args: ParsedArgs,
+  env: NodeJS.ProcessEnv,
+): MetrikNetwork {
+  const chainId =
+    integerFlag(args, "chain-id") ?? parseEnvChainId(env.METRIK_AGENT_CHAIN_ID);
+  const selector = stringFlag(args, "network") ?? env[METRIK_NETWORK_ENV];
+  if (chainId !== undefined)
+    assertTestnetChainId(chainId, "the configured chain id");
+  let network: MetrikNetwork;
+  try {
+    network = resolveAgentNetwork(
+      selector !== undefined && selector.trim().length > 0 ? selector : chainId,
+      CLI_NETWORK_POLICY,
+    );
+  } catch (error) {
+    if (error instanceof UnsupportedNetworkError) {
+      throw configError(
+        `refusing to run against network "${error.selector}": it is not a supported testnet`,
+        `${error.message}. There is no override flag.`,
+      );
+    }
+    throw error;
+  }
+  if (chainId !== undefined && chainId !== network.chain.id) {
+    throw configError(
+      `--chain-id ${chainId} does not match --network ${network.id} (chain ${network.chain.id})`,
+      "give one of them, or make them agree.",
+    );
+  }
+  return network;
+}
 /** Flags every command accepts for settlement configuration. */
 export const CONFIG_FLAGS: readonly string[] = [
+  "network",
+  "escrow-generation",
   "chain-id",
   "rpc-url",
   "escrow",
@@ -119,12 +206,12 @@ export const CONFIG_FLAGS: readonly string[] = [
 export const GLOBAL_FLAGS: readonly string[] = ["json", "help"];
 
 export function assertTestnetChainId(chainId: number, source: string): void {
-  if (TESTNET_CHAIN_IDS.includes(chainId)) return;
+  if (testnetChainIds().includes(chainId)) return;
   throw configError(
     `refusing to run against chain ${chainId}: ${source} is not a supported testnet`,
-    `this CLI signs with a raw private key and settles real value, so it is testnet-only. Supported: ${TESTNET_CHAIN_IDS.join(
-      ", ",
-    )} (Base Sepolia). There is no override flag.`,
+    `this CLI signs with a raw private key and settles real value, so it is testnet-only. Supported (registered testnets): ${describeAllowedNetworks(
+      CLI_NETWORK_POLICY,
+    )}. There is no override flag.`,
   );
 }