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

package/src/cli/listings.ts

@@ -18,6 +18,30 @@ export async function resolveListing(
   serviceRef: `0x${string}`,
   options: { readonly required: boolean },
 ): Promise<ServiceListing | null> {
+  return (await resolveListingRecord(context, serviceRef, options)).listing;
+}
+
+/**
+ * What {@link resolveListing} found, including the verified signed record of a
+ * matching row even when that row is not usable as a listing (no signed
+ * invocation URL) — `open` still has to read the operator-signed rate band off
+ * it — and whether the registry was unreachable (the only case in which a
+ * signed band may exist and be unknown).
+ */
+export interface ListingRecordResolution {
+  readonly listing: ServiceListing | null;
+  readonly record: {
+    readonly serviceRef: string;
+    readonly signed: ServiceListing["signed"];
+  } | null;
+  readonly registryUnreachable: boolean;
+}
+
+export async function resolveListingRecord(
+  context: CommandContext,
+  serviceRef: `0x${string}`,
+  options: { readonly required: boolean },
+): Promise<ListingRecordResolution> {
   const { config, out, deps } = context;
   let services;
   try {
@@ -32,7 +56,7 @@ export async function resolveListing(
       out.note(
         `warning: the registry at ${config.registryUrl} is unreachable; continuing without a verified listing.`,
       );
-      return null;
+      return { listing: null, record: null, registryUnreachable: true };
     }
     throw new CliError(
       `the service registry at ${config.registryUrl} could not be read`,
@@ -45,7 +69,9 @@ export async function resolveListing(
     (service) => service.serviceRef.toLowerCase() === wanted,
   );
   if (match === undefined) {
-    if (!options.required) return null;
+    if (!options.required) {
+      return { listing: null, record: null, registryUnreachable: false };
+    }
     throw new CliError(
       `no verified listing in the registry matches serviceRef ${serviceRef}`,
       {
@@ -54,8 +80,11 @@ export async function resolveListing(
       },
     );
   }
+  const record = { serviceRef: match.serviceRef, signed: match.signed };
   if (match.accessUrl === null) {
-    if (!options.required) return null;
+    if (!options.required) {
+      return { listing: null, record, registryUnreachable: false };
+    }
     throw new CliError(
       `listing ${serviceRef} carries no signed invocation URL`,
       {
@@ -66,12 +95,16 @@ export async function resolveListing(
   }
 
   return {
-    serviceRef: match.serviceRef,
-    operator: match.operator,
-    publicUrl: match.publicUrl,
-    access: match.access,
-    accessUrl: match.accessUrl,
-    signed: match.signed,
-    category: match.category,
+    listing: {
+      serviceRef: match.serviceRef,
+      operator: match.operator,
+      publicUrl: match.publicUrl,
+      access: match.access,
+      accessUrl: match.accessUrl,
+      signed: match.signed,
+      category: match.category,
+    },
+    record,
+    registryUnreachable: false,
   };
 }

package/src/cli/preflight.ts

@@ -1,14 +1,10 @@
+import type { MetrikNetwork } from "@absol-labs/sdk";
+
+import { gasFundingHint, usdcFundingHint } from "../network.js";
 import { formatUsdc } from "./amounts.js";
 import { CliError } from "./errors.js";
 import type { CliReadClient } from "./deps.js";
 
-/** Where a Base Sepolia test wallet gets its gas. */
-export const BASE_SEPOLIA_FAUCET_URL =
-  "https://www.alchemy.com/faucets/base-sepolia";
-
-/** Where a Base Sepolia test wallet gets the USDC it escrows. */
-export const CIRCLE_USDC_FAUCET_URL = "https://faucet.circle.com";
-
 /**
  * Refuse to broadcast from a wallet that cannot pay for gas.
  *
@@ -16,20 +12,29 @@ export const CIRCLE_USDC_FAUCET_URL = "https://faucet.circle.com";
  * phrasing — `USDC approve transaction failed: Execution reverted with reason:
  * gas required exceeds allowance (0)` — which reads like a USDC allowance
  * problem and sends the reader looking at approvals. The actual fact is "this
- * address holds no ETH", and it is knowable with one read before anything is
+ * address holds no gas", and it is knowable with one read before anything is
  * signed.
  *
+ * The gas token is read from the network's registry metadata, never assumed to
+ * be ETH. Where gas IS the settlement token (`gasToken.isSettlementToken`),
+ * there is only one balance: the USDC balance is the gas balance, so that is
+ * the one read.
+ *
  * Deliberately only a ZERO check, not an estimate: predicting the gas a hire
- * will cost means simulating it, and a wallet with a little ETH that still runs
+ * will cost means simulating it, and a wallet with a little gas that still runs
  * short should get the real revert rather than a guess from this CLI.
  */
 export async function assertCanPayGas(
   read: CliReadClient,
   address: `0x${string}`,
+  network: MetrikNetwork,
 ): Promise<void> {
+  const gasIsUsdc = network.gasToken.isSettlementToken;
   let balance: bigint;
   try {
-    balance = await read.nativeBalance(address);
+    balance = gasIsUsdc
+      ? await read.usdcBalance(address)
+      : await read.nativeBalance(address);
   } catch {
     // A balance read is a courtesy, not a gate. If the RPC will not answer it,
     // let the command proceed and fail with the real error.
@@ -38,10 +43,12 @@ export async function assertCanPayGas(
   if (balance > 0n) return;
 
   throw new CliError(
-    `wallet ${address} has 0 ETH on Base Sepolia, so it cannot pay for gas`,
+    `wallet ${address} has 0 ${network.gasToken.symbol} on ${network.name}, so it cannot pay for gas`,
     {
       exitCode: 3,
-      hint: `fund it at ${BASE_SEPOLIA_FAUCET_URL}, then re-run. (Gas is ETH; the stream itself is escrowed in USDC, which is a separate balance.)`,
+      hint: gasIsUsdc
+        ? `${gasFundingHint(network)}, then re-run. (On ${network.name} gas is paid in USDC, the same balance a stream is escrowed from.)`
+        : `${gasFundingHint(network)}, then re-run. (Gas is ${network.gasToken.symbol}; the stream itself is escrowed in USDC, which is a separate balance.)`,
     },
   );
 }
@@ -49,12 +56,16 @@ export async function assertCanPayGas(
 /**
  * Refuse to broadcast a hire the wallet cannot fund.
  *
- * The sibling of `assertCanPayGas`, for the OTHER balance. Gas is ETH and the
- * deposit is USDC: they are separate balances on separate tokens, so a wallet
- * that passes the gas check can still hold no USDC at all. Without this the
- * `open` path sends the USDC approval FIRST — which succeeds, because approving
- * an amount you do not hold is legal — and then reverts inside `transferFrom`,
- * having already spent gas to learn something that was one `balanceOf` away.
+ * The sibling of `assertCanPayGas`, for the OTHER balance. On a network whose
+ * gas token is not USDC, gas and deposit are separate balances on separate
+ * tokens, so a wallet that passes the gas check can still hold no USDC at all.
+ * Without this the `open` path sends the USDC approval FIRST — which succeeds,
+ * because approving an amount you do not hold is legal — and then reverts
+ * inside `transferFrom`, having already spent gas to learn something that was
+ * one `balanceOf` away.
+ *
+ * Where gas IS USDC there is one balance, and it must cover the deposit AND
+ * leave something for gas, so the check is strict (`balance > budget`).
  *
  * Deliberately NOT an allowance check. The CLI's own open path grants the
  * bounded approval it needs (`approveTxHash` in the result), so a missing
@@ -66,7 +77,9 @@ export async function assertCanFundStream(
   read: CliReadClient,
   address: `0x${string}`,
   budgetUsdc: bigint,
+  network: MetrikNetwork,
 ): Promise<void> {
+  const gasIsUsdc = network.gasToken.isSettlementToken;
   let balance: bigint;
   try {
     balance = await read.usdcBalance(address);
@@ -76,13 +89,15 @@ export async function assertCanFundStream(
     // the real error surface.
     return;
   }
-  if (balance >= budgetUsdc) return;
+  if (gasIsUsdc ? balance > budgetUsdc : balance >= budgetUsdc) return;
 
   throw new CliError(
-    `wallet ${address} holds ${formatUsdc(balance)} but --budget is ${formatUsdc(budgetUsdc)}`,
+    `wallet ${address} holds ${formatUsdc(balance)} but --budget is ${formatUsdc(budgetUsdc)}${gasIsUsdc ? " (plus gas, which is also USDC here)" : ""}`,
     {
       exitCode: 3,
-      hint: `the deposit is escrowed in USDC — fund the wallet at ${CIRCLE_USDC_FAUCET_URL} (Base Sepolia), then re-run. (Gas is a separate ETH balance.)`,
+      hint: gasIsUsdc
+        ? `the deposit and the gas are both USDC on ${network.name} — ${usdcFundingHint(network)}, then re-run.`
+        : `the deposit is escrowed in USDC — ${usdcFundingHint(network)}, then re-run. (Gas is a separate ${network.gasToken.symbol} balance.)`,
     },
   );
 }

package/src/cli/privy.ts

@@ -18,6 +18,8 @@ import {
   type AutonomousWalletRecord,
 } from "../wallet/autonomous-wallet.js";
 import { createPrivySessionProvider } from "../wallet/privy-session-provider.js";
+import { PRIVY_BROKER_CHAIN_ID } from "../wallet/privy-session-broker.js";
+import { defaultNetwork } from "../network.js";
 import {
   createPrivyEmbeddedAccount,
   type PrivyEip1193Provider,
@@ -357,12 +359,12 @@ async function embeddedAccount(
       appId,
       address,
       provider,
-      chainId: 84532,
+      chainId: PRIVY_BROKER_CHAIN_ID,
     });
   } catch (error) {
     throw configError(
       `the Privy wallet could not be prepared: ${describe(error)}`,
-      `check ${PRIVY_ENV_VARS.join(", ")}. Metrik Privy wallets are Base Sepolia (84532) only.`,
+      `check ${PRIVY_ENV_VARS.join(", ")}. Metrik Privy wallets are on the broker's network only (${defaultNetwork().name}, chain ${PRIVY_BROKER_CHAIN_ID}).`,
     );
   }
 }

package/src/cli/reclaimability.ts

@@ -0,0 +1,154 @@
+import type { StreamV2 } from "@absol-labs/sdk";
+
+import { formatDuration } from "./amounts.js";
+import { formatTimestamp, readChainNow } from "./escape-hatch.js";
+import { settlementCoverage } from "./status.js";
+import type { CliReadClient } from "./deps.js";
+
+/**
+ * Why a proof-based reclaim cannot go through right now, read from chain state
+ * rather than decoded out of a revert.
+ *
+ * `metrik reclaim` used to learn this only by sending the simulation and
+ * reading what came back. That works exactly as well as the endpoint's revert
+ * data does, and on the public Base Sepolia RPC it frequently does not work at
+ * all: an already-reclaimed stream, a stream that is still running, and a
+ * stream whose stop time is not checkpointed yet ALL came back as
+ *
+ *     reclaim simulation failed: Execution reverted for an unknown reason.
+ *
+ * Three different situations, three completely different next actions — you
+ * already have the money / close it first / wait ~20 seconds — and one message
+ * that distinguishes none of them. Worse, the retry loop keys off the same
+ * undecoded revert, so the wait that this command advertises never engaged.
+ *
+ * Every one of these conditions is a pure function of state the CLI already
+ * reads elsewhere (`getStreamV2`, `latestCheckpointCheckedAt`, the chain clock,
+ * and {@link settlementCoverage}, which `metrik status` has always used to
+ * decide the same question). So the condition is named from that state, before
+ * a transaction is built, the way `reclaim-unverified` has always named
+ * "already reclaimed". No revert data required.
+ */
+export type ReclaimBlocker =
+  /** `AlreadyReclaimed()` / `NothingToReclaim()`: the money is already back. */
+  | { readonly kind: "reclaimed" }
+  /** `StreamNotReclaimable()`: neither closed nor expired, so the clock runs. */
+  | {
+      readonly kind: "running";
+      readonly expiresAt: number;
+      readonly secondsRemaining: number;
+    }
+  /**
+   * `SettlementWindowOpen()`: the stream has stopped but no checkpoint reaches
+   * its stop time yet. The ONLY one of the three that is a wait rather than a
+   * refusal — the oracle publishes roughly every 15-22s.
+   */
+  | {
+      readonly kind: "awaiting-checkpoint";
+      readonly stopAt: number;
+      readonly coveredUpTo: number | null;
+    };
+
+/**
+ * The blocker implied by this state, or `null` when nothing in the state blocks
+ * a reclaim. Pure, so every branch is testable without an RPC — the same reason
+ * {@link settlementCoverage} is.
+ *
+ * Order matters and follows the escrow: a reclaimed stream is terminal, a
+ * running stream cannot be reclaimed at any settlement state, and only then
+ * does checkpoint coverage decide.
+ */
+export function classifyReclaimBlocker(
+  stream: Pick<StreamV2, "status" | "closedAt" | "expiresAt" | "reclaimed">,
+  latestCheckpointCheckedAt: number | null,
+  nowSeconds: number,
+): ReclaimBlocker | null {
+  if (stream.reclaimed) return { kind: "reclaimed" };
+  if (stream.status !== "closed" && nowSeconds < stream.expiresAt) {
+    return {
+      kind: "running",
+      expiresAt: stream.expiresAt,
+      secondsRemaining: stream.expiresAt - nowSeconds,
+    };
+  }
+  const coverage = settlementCoverage(
+    stream,
+    latestCheckpointCheckedAt,
+    nowSeconds,
+  );
+  if (coverage.pending && coverage.stopAt !== null) {
+    return {
+      kind: "awaiting-checkpoint",
+      stopAt: coverage.stopAt,
+      coveredUpTo: coverage.coveredUpTo,
+    };
+  }
+  return null;
+}
+
+/**
+ * Read the state the classifier needs and name the blocker.
+ *
+ * **Fails open.** A read that does not answer returns `null` — "nothing known
+ * to block this" — never a refusal. Refusing to return a buyer's money because
+ * a load-balanced endpoint would not answer a view call is the one outcome this
+ * command must never produce; the transaction itself remains the authority.
+ */
+export async function readReclaimBlocker(
+  read: Pick<
+    CliReadClient,
+    "getStreamV2" | "latestCheckpointCheckedAt" | "latestBlockTimestamp"
+  >,
+  streamId: `0x${string}`,
+  fallbackNowSeconds: number,
+): Promise<ReclaimBlocker | null> {
+  const stream = await read.getStreamV2(streamId).catch(() => null);
+  if (stream === null) return null;
+  const now = await readChainNow(read, fallbackNowSeconds);
+  const latestCheckpointCheckedAt = await read
+    .latestCheckpointCheckedAt()
+    .catch(() => null);
+  return classifyReclaimBlocker(stream, latestCheckpointCheckedAt, now.seconds);
+}
+
+/**
+ * The refusal for a blocker that will not clear on its own, as message + hint.
+ *
+ * `awaiting-checkpoint` has no entry here on purpose: it clears by itself, so
+ * it is narrated by {@link describeAwaitingCheckpoint} and waited out, never
+ * raised as an error.
+ */
+export function describeTerminalBlocker(
+  blocker: ReclaimBlocker,
+  streamId: `0x${string}`,
+): { readonly message: string; readonly hint: string } | null {
+  if (blocker.kind === "reclaimed") {
+    return {
+      message:
+        "this stream has already been reclaimed — there is nothing left to take back",
+      hint: `check where it went:  metrik status ${streamId}`,
+    };
+  }
+  if (blocker.kind === "running") {
+    return {
+      message: `the stream is still running, so there is nothing to reclaim yet — the meter stops at ${formatTimestamp(
+        blocker.expiresAt,
+      )}, in ${formatDuration(blocker.secondsRemaining)}`,
+      hint: `stop the clock first — \`metrik close ${streamId}\`, or re-run this command with --close-first — or wait for it to expire. (If you closed it moments ago, the RPC endpoint may not have caught up yet: re-run this command.)`,
+    };
+  }
+  return null;
+}
+
+/** The wait, named: what stopped, how far the oracle has published. */
+export function describeAwaitingCheckpoint(
+  blocker: Extract<ReclaimBlocker, { kind: "awaiting-checkpoint" }>,
+): string {
+  const covered =
+    blocker.coveredUpTo === null
+      ? "how far the oracle has published could not be read"
+      : `the oracle has published only to ${formatTimestamp(blocker.coveredUpTo)}`;
+  return `the stream stopped at ${formatTimestamp(
+    blocker.stopAt,
+  )} and ${covered}. Reclaim reverts until a checkpoint reaches the stop time — the oracle publishes roughly every 15-22s, so this waits.`;
+}

package/src/cli/run.ts

@@ -1,16 +1,27 @@
-import { assertKnownFlags, booleanFlag, parseArgs } from "./args.js";
+import {
+  assertKnownFlags,
+  booleanFlag,
+  jsonOutputRequested,
+  parseArgs,
+} from "./args.js";
 import {
   CONFIG_FLAGS,
   GLOBAL_FLAGS,
-  TESTNET_CHAIN_IDS,
+  CLI_NETWORK_POLICY,
   resolveConfig,
 } from "./config.js";
+import { describeAllowedNetworks } from "../network.js";
 import { CliError, describeError, usageError } from "./errors.js";
 import { createPrinter, type CliStreams } from "./output.js";
 import { startHeartbeat } from "./progress.js";
 import { defaultCliDependencies, type CliDependencies } from "./deps.js";
 import { packageVersion } from "./version.js";
-import { CDP_ENV_VARS, PRIVATE_KEY_ENV } from "./wallet.js";
+import {
+  CDP_ENV_VARS,
+  PRIVATE_KEY_ENV,
+  PRIVY_SESSION_ENV_VARS,
+  PRIVY_WALLET_KEY_ENV,
+} from "./wallet.js";
 import type { CommandSpec } from "./context.js";
 
 import { claimCommand } from "./commands/claim.js";
@@ -19,15 +30,39 @@ import { discoverCommand } from "./commands/discover.js";
 import { invokeCommand } from "./commands/invoke.js";
 import { mcpCommand } from "./commands/mcp.js";
 import { openCommand } from "./commands/open.js";
+import { payCommand } from "./commands/pay.js";
 import { reclaimCommand } from "./commands/reclaim.js";
+import { refundCommand } from "./commands/refund.js";
 import { reclaimUnverifiedCommand } from "./commands/reclaim-unverified.js";
 import { statusCommand } from "./commands/status.js";
 import { streamsCommand } from "./commands/streams.js";
 import { watchCommand } from "./commands/watch.js";
 
+/**
+ * Every wallet source, named in the order they are resolved. Privy shipped in
+ * 0.11.0 as resolution step 3 and worked, but appeared in no user-facing text
+ * at all — so the only way to learn the CLI could use it was to read the
+ * source or the docs. An external reviewer running the published package
+ * concluded it did not exist.
+ */
+const WALLET_SOURCES =
+  `${PRIVATE_KEY_ENV}, ${CDP_ENV_VARS.join(" + ")}, ` +
+  `or ${PRIVY_WALLET_KEY_ENV} (Privy; or a broker session via ${PRIVY_SESSION_ENV_VARS.join(" + ")}).`;
+
+/**
+ * Said in the help, not only discovered at runtime. `claim` is the OPERATOR's
+ * side and a Privy broker policy allowlists BUYER actions only, so a Privy
+ * wallet cannot sign one — the broker refuses, and the client cannot raise its
+ * own ceiling. The command already warns when it runs; someone choosing a
+ * wallet needs it before that.
+ */
+const PRIVY_CLAIM_NOTE =
+  "`metrik claim` does NOT work on a Privy wallet: the broker's transaction allowlist is buyer-only. Claim with the operator's own key.";
+
 /**
  * The command surface, in the order the product loop runs:
- * discover -> open -> invoke -> watch/status -> close -> reclaim, then the
+ * discover -> open (or pay, over x402) -> invoke -> watch/status -> close ->
+ * reclaim (or refund, through an x402 seller's gasless relay), then the
  * operator's own redemption (`claim`) and the buyer's last-resort exit
  * (`reclaim-unverified`). `streams` (which of them are mine?) sits inside that
  * loop; `mcp` (run the same loop from an MCP host) sits after it.
@@ -35,12 +70,14 @@ import { watchCommand } from "./commands/watch.js";
 export const COMMANDS: readonly CommandSpec[] = [
   discoverCommand,
   openCommand,
+  payCommand,
   statusCommand,
   streamsCommand,
   watchCommand,
   invokeCommand,
   closeCommand,
   reclaimCommand,
+  refundCommand,
   reclaimUnverifiedCommand,
   claimCommand,
   mcpCommand,
@@ -69,7 +106,7 @@ export async function runCli(options: RunCliOptions): Promise<number> {
   let json = false;
   try {
     const args = parseArgs(options.argv);
-    json = booleanFlag(args, "json");
+    json = jsonOutputRequested(args);
     const out = createPrinter(streams, json);
 
     // `--version` is checked before the bare-invocation help branch: `metrik
@@ -160,12 +197,13 @@ export function renderHelp(commandName?: string): string {
       ...(command.signs
         ? [
             "",
-            `Broadcasts a transaction. Requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+            `Broadcasts a transaction. Requires a wallet in the environment: ${WALLET_SOURCES}`,
+            ...(command.name === "claim" ? [PRIVY_CLAIM_NOTE] : []),
           ]
         : command.requiresKey === true
           ? [
               "",
-              `Broadcasts nothing, but signs an off-chain EIP-712 capability, so it requires a wallet in the environment: ${PRIVATE_KEY_ENV}, or ${CDP_ENV_VARS.join(" + ")}.`,
+              `Broadcasts nothing, but signs an off-chain EIP-712 capability, so it requires a wallet in the environment: ${WALLET_SOURCES}`,
             ]
           : []),
     ].join("\n");
@@ -194,16 +232,21 @@ export function renderHelp(commandName?: string): string {
     "  --json          machine-readable output on stdout",
     "  --help          this text, or `metrik <command> --help`",
     "",
-    "Settlement flags (all default to Metrik's Base Sepolia deployment):",
-    "  --chain-id  --rpc-url  --escrow  --usdc  --oracle-url  --registry-url",
+    "Settlement flags (all default to the selected network's registry entry):",
+    "  --network  --chain-id  --rpc-url  --escrow  --usdc  --oracle-url  --registry-url",
+    "  --network takes a registry id, chain id or CAIP-2 id (env METRIK_NETWORK).",
     "",
     "Wallet (read from the environment only; never accepted as a flag):",
-    `  ${PRIVATE_KEY_ENV}  a Base Sepolia test key. Checked first.`,
+    `  ${PRIVATE_KEY_ENV}  a testnet key. Checked first.`,
     `  ${CDP_ENV_VARS.join(", ")}`,
     "    a Coinbase CDP Server Wallet v2 account. Used when no private key is set.",
+    `  ${PRIVY_WALLET_KEY_ENV}`,
+    "    a Privy wallet you provisioned, reached through a broker. Checked third.",
+    `    A broker session instead: ${PRIVY_SESSION_ENV_VARS.join(", ")}.`,
+    `    ${PRIVY_CLAIM_NOTE}`,
     "  A credential on the command line lands in shell history; these never are.",
     "",
-    `TESTNET ONLY: this CLI refuses any chain outside ${TESTNET_CHAIN_IDS.join(", ")} (Base Sepolia),`,
+    `TESTNET ONLY: this CLI refuses any chain outside the registered testnets: ${describeAllowedNetworks(CLI_NETWORK_POLICY)},`,
     "and re-checks the chain id the RPC actually serves before signing. There is no override.",
   ].join("\n");
 }

package/src/cli/scan-range.ts

@@ -19,14 +19,14 @@
  * `buyer` and `operator` are INDEXED on `StreamOpened`, so a per-wallet scan is
  * a server-side topic filter whose response is tiny regardless of range. What
  * public RPCs cap is the per-call BLOCK RANGE, and a topic filter does not lift
- * it: `sepolia.base.org` answers a wider range with `-32614 "eth_getLogs is
+ * it: the public RPC answers a wider range with `-32614 "eth_getLogs is
  * limited to a 10,000 range"`. So the page size is the cap, not a guess below
  * it.
  */
 
 /**
  * getLogs page size. The window is `chunk + 1` blocks (bounds inclusive), so
- * 9 999 is the largest page `sepolia.base.org` accepts.
+ * 9 999 is the largest page the public RPC accepts.
  */
 export const LOG_SCAN_CHUNK = 9_999n;
 

package/src/cli/status.ts

@@ -126,6 +126,8 @@ export async function readStreamReport(
   read: CliReadClient,
   streamId: `0x${string}`,
   nowSeconds: number,
+  /** The escrow's generation (decides the escape-hatch rule). Default `v2`. */
+  escrowGeneration = "v2",
 ): Promise<StreamReport> {
   const stream = await read.getStreamV2(streamId);
 
@@ -164,6 +166,7 @@ export async function readStreamReport(
       stream,
       await read.escapeGraceSeconds(),
       now.seconds,
+      escrowGeneration,
     );
   } catch {
     escapeHatch = null;
@@ -208,6 +211,11 @@ export function streamReportJson(report: StreamReport): unknown {
     status: stream.status,
     reclaimed: stream.reclaimed,
     buyer: stream.buyer,
+    // An x402 stream's `buyer` is the X402StreamOpener contract, not the
+    // person who paid; `payer` is who any refund goes to.
+    opener: stream.opener ?? null,
+    payer: stream.payer ?? stream.buyer,
+    boughtVia: (stream.opener ?? null) === null ? "wallet" : "x402-opener",
     operator: stream.operator,
     serviceRef: stream.serviceRef,
     deposit: stream.deposit,
@@ -275,7 +283,12 @@ export function streamReportRows(
       "status",
       stream.reclaimed ? `${stream.status} (reclaimed)` : stream.status,
     ],
-    ["buyer", stream.buyer],
+    ...(stream.opener === null || stream.opener === undefined
+      ? ([["buyer", stream.buyer]] as const)
+      : ([
+          ["buyer", `${stream.buyer} (x402 opener contract)`],
+          ["payer", `${stream.payer} (refunds go here)`],
+        ] as const)),
     ["operator", stream.operator],
     ["serviceRef", stream.serviceRef],
     ["deposit", formatUsdc(stream.deposit)],

package/src/cli/wallet.ts

@@ -24,7 +24,7 @@ import {
  *
  * ## Resolution order (first match wins, checked in this order)
  *
- *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw Base Sepolia test key.
+ *  1. `METRIK_AGENT_PRIVATE_KEY` — a raw testnet key.
  *  2. The `CDP_*` / `METRIK_AGENT_CDP_*` quartet — a Coinbase CDP Server Wallet
  *     v2 account, resolved through this package's own `resolveAgentWallet()`.
  *  3. The `METRIK_AGENT_PRIVY_*` variables — a Privy wallet reached through a
@@ -123,7 +123,7 @@ export interface CliWallet {
 }
 
 const WALLET_HINT =
-  `export ${PRIVATE_KEY_ENV}=0x… (a funded Base Sepolia test key), configure a Coinbase CDP wallet with ` +
+  `export ${PRIVATE_KEY_ENV}=0x… (a funded testnet key), configure a Coinbase CDP wallet with ` +
   `${CDP_ENV_VARS.join(", ")}, or configure a Privy wallet with ${PRIVY_WALLET_KEY_ENV} (agent-owned) or ` +
   `${PRIVY_SESSION_ENV_VARS.join(", ")} (broker session). All are read from the environment only — never pass a credential as a command-line flag.`;