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

package/src/cli/deps.ts

@@ -8,7 +8,7 @@ import {
   type StreamV2,
   type StreamProofTransactionResult,
 } from "@absol-labs/sdk";
-import { erc20Abi, getAbiItem, http, type LocalAccount } from "viem";
+import { erc20Abi, getAbiItem, http, type Transport } from "viem";
 
 import {
   discoverServicesDetailed,
@@ -30,8 +30,15 @@ import {
   type ReclaimAuthorizedStreamInput,
   type ReclaimVerifiedStreamResult,
 } from "../sdk/client.js";
+import type { SignedSpendMandate } from "../mandates/mandate.js";
+import type {
+  PayX402WithMandateInput,
+  PayX402WithMandateResult,
+} from "../x402-buyer/pay.js";
+import type { RefundClient } from "@absol-labs/sdk/x402";
 
 import type { CliConfig } from "./config.js";
+import type { CliSignerAccount } from "./wallet.js";
 import { RPC_RETRY_COUNT, RPC_TIMEOUT_MS, withReadTimeout } from "./timeout.js";
 
 /**
@@ -149,17 +156,39 @@ export interface OpenedStream {
   readonly blockNumber: bigint;
 }
 
+/**
+ * A fund-moving call, with the mandate made EXPLICITLY optional.
+ *
+ * `null` is not "no authorization" — it is "this wallet's ceiling is enforced
+ * by a broker policy the client cannot reach or raise, so a locally self-signed
+ * mandate would be the agent attesting to its own limits on top of a stronger
+ * limit". The CLI substitutes the real ceiling instead; see
+ * `./spend-policy.ts`, which also explains why re-adding the mandate here would
+ * be a regression rather than a tidy-up.
+ *
+ * A key-holding wallet (private key, CDP) always passes a real mandate, and its
+ * path through `VerifiedStreamAgentClient` is unchanged.
+ */
+type MandateOptional<T extends { readonly signedMandate: SignedSpendMandate }> =
+  Omit<T, "signedMandate"> & {
+    readonly signedMandate: SignedSpendMandate | null;
+  };
+
+export type CliOpenStreamInput = MandateOptional<OpenVerifiedStreamInput>;
+export type CliStreamActionInput =
+  MandateOptional<MandateAuthorizedStreamActionInput>;
+export type CliReclaimStreamInput =
+  MandateOptional<ReclaimAuthorizedStreamInput>;
+
 export interface CliWriteClient {
   /** Build + best-effort simulate the hire WITHOUT broadcasting (`--dry-run`). */
   buildHireTx(input: HireComputeInput): Promise<HireTxPreview>;
-  openVerifiedStream(
-    input: OpenVerifiedStreamInput,
-  ): Promise<HireComputeResult>;
+  openVerifiedStream(input: CliOpenStreamInput): Promise<HireComputeResult>;
   closeStream(
-    input: MandateAuthorizedStreamActionInput,
+    input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
   reclaimStream(
-    input: ReclaimAuthorizedStreamInput,
+    input: CliReclaimStreamInput,
   ): Promise<ReclaimVerifiedStreamResult>;
   /**
    * The no-proof escape hatch. Separate from {@link reclaimStream} because it is
@@ -167,14 +196,53 @@ export interface CliWriteClient {
    * — see `VerifiedStreamAgentClient.reclaimUnverifiedStream`.
    */
   reclaimUnverifiedStream(
-    input: MandateAuthorizedStreamActionInput,
+    input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
   /** Operator-only: redeem the verified-earned balance for a stream. */
   claimStream(
-    input: MandateAuthorizedStreamActionInput,
+    input: CliStreamActionInput,
   ): Promise<StreamProofTransactionResult>;
 }
 
+/**
+ * Per-wallet write-path overrides.
+ *
+ * `transport` exists for exactly one reason: a Privy wallet has no local
+ * `signTransaction`. Its EIP-1193 provider performs `eth_sendTransaction`
+ * itself, so the provider must BE the wallet client's transport rather than the
+ * plain `http(--rpc-url)` every local signer uses. Left unset — which is every
+ * private-key and CDP run — the transport is unchanged, byte for byte.
+ */
+export interface CreateWriteClientOptions {
+  readonly transport?: Transport;
+}
+
+/**
+ * The buyer side of x402 (`metrik pay` / `metrik refund`). Behind the injectable
+ * surface like every other side effect, and loaded lazily by default so a CLI
+ * run that never pays over x402 never imports `@x402/*`.
+ */
+export interface CliX402 {
+  /** Mandate-gated `payWithX402` (see `../x402-buyer/pay.ts`). */
+  readonly pay: (
+    input: PayX402WithMandateInput,
+  ) => Promise<PayX402WithMandateResult>;
+  /**
+   * The SDK's `refundClient`, bound to ONE stream and verifying every relay
+   * "success" against the chain this CLI is configured for.
+   */
+  readonly refundClient: (
+    config: CliConfig,
+    target: {
+      readonly refundUrl: string;
+      readonly streamId: `0x${string}`;
+      readonly opener?: `0x${string}`;
+      readonly maxAttempts?: number;
+      readonly maxDelayMs?: number;
+    },
+  ) => Promise<RefundClient>;
+}
+
 export interface CliDependencies {
   readonly createReadClient: (config: CliConfig) => CliReadClient;
   /**
@@ -185,7 +253,8 @@ export interface CliDependencies {
    */
   readonly createWriteClient: (
     config: CliConfig,
-    account: LocalAccount | null,
+    account: CliSignerAccount | null,
+    options?: CreateWriteClientOptions,
   ) => CliWriteClient;
   readonly discover: (
     options: DiscoverServicesOptions,
@@ -198,6 +267,8 @@ export interface CliDependencies {
   readonly createInvokeStreamReader: (config: CliConfig) => InvokeStreamReader;
   readonly nowSeconds: () => number;
   readonly sleep: (ms: number) => Promise<void>;
+  /** Optional so an embedder's existing dependency object keeps compiling. */
+  readonly x402?: CliX402;
 }
 
 /**
@@ -218,21 +289,38 @@ const STREAM_OPENED_EVENT = getAbiItem({
  * with nothing on screen. Bounding it here bounds every read and every
  * simulation the SDK performs, in one place.
  */
-function rpcTransport(config: CliConfig) {
+export function rpcTransport(config: CliConfig) {
   return http(config.rpcUrl, {
     timeout: RPC_TIMEOUT_MS,
     retryCount: RPC_RETRY_COUNT,
   });
 }
 
+/**
+ * An `--escrow` the registry does not record was declared with
+ * `--escrow-generation`: the only case the SDK may skip its code-hash pin.
+ */
+function unregisteredEscrowOptions(config: CliConfig): {
+  readonly allowUnregisteredEscrow?: true;
+  readonly escrowGeneration?: "v2" | "v3";
+} {
+  return config.unregisteredEscrowGeneration === undefined
+    ? {}
+    : {
+        allowUnregisteredEscrow: true,
+        escrowGeneration: config.unregisteredEscrowGeneration,
+      };
+}
+
 /** Shared `MetrikClient` construction: one escrow, declared as V2 on both keys. */
 function createMetrikClient(
   config: CliConfig,
-  account?: LocalAccount,
+  account?: CliSignerAccount,
+  transport?: Transport,
 ): MetrikClient {
   return new MetrikClient({
     chain: config.chain,
-    transport: rpcTransport(config),
+    transport: transport ?? rpcTransport(config),
     escrow: config.escrow,
     // Declared on BOTH keys: without `escrowV2` the SDK routes reads and
     // settlement through the legacy V1 ABI, which reverts against
@@ -242,6 +330,7 @@ function createMetrikClient(
     usdc: config.usdc,
     oracleBaseUrl: config.oracleBaseUrl,
     settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+    ...unregisteredEscrowOptions(config),
     ...(account === undefined ? {} : { account }),
   });
 }
@@ -365,15 +454,19 @@ export const defaultCliDependencies: CliDependencies = {
       },
     };
   },
-  createWriteClient(config, account) {
+  createWriteClient(config, account, options) {
+    // A Privy wallet's provider IS the transport (see CreateWriteClientOptions);
+    // every other wallet keeps the plain bounded HTTP transport.
+    const transport = options?.transport ?? rpcTransport(config);
     const clientConfig = {
       chain: config.chain,
-      transport: rpcTransport(config),
+      transport,
       escrow: config.escrow,
       escrowV2: config.escrow,
       usdc: config.usdc,
       oracleBaseUrl: config.oracleBaseUrl,
       settlementTarget: { chainId: config.chainId, escrow: config.escrow },
+      ...unregisteredEscrowOptions(config),
       ...(account === null ? {} : { account }),
     };
     // The mandate-gated agent client owns every fund-moving call; the raw SDK
@@ -382,26 +475,61 @@ export const defaultCliDependencies: CliDependencies = {
     const agentClient = new VerifiedStreamAgentClient(clientConfig);
     const metrik = createMetrikClient(
       config,
-      ...(account === null ? [] : ([account] as const)),
+      account === null ? undefined : account,
+      transport,
     );
     return {
       async buildHireTx(input) {
         return await metrik.buildHireTx(input);
       },
-      async openVerifiedStream(input) {
-        return await agentClient.openVerifiedStream(input);
+      async openVerifiedStream({ signedMandate, ...input }) {
+        // No mandate means a policy-enforced wallet: the ceiling was already
+        // checked against the broker's own `/v1/config` before we got here, and
+        // the broker checks it AGAIN server-side on the transaction it signs.
+        // Going straight at the SDK client is the same path the SDK-driven
+        // (non-CLI) flow has always used.
+        if (signedMandate === null) {
+          return await metrik.hireVerifiedService({
+            operator: input.operator,
+            serviceRef: input.serviceRef,
+            budgetUsdc: input.budgetUsdc,
+            ratePerSecond: input.ratePerSecondUsdc,
+            maxDurationSeconds: input.maxDurationSeconds,
+          });
+        }
+        return await agentClient.openVerifiedStream({
+          ...input,
+          signedMandate,
+        });
       },
-      async closeStream(input) {
-        return await agentClient.closeStream(input);
+      async closeStream({ signedMandate, ...input }) {
+        if (signedMandate === null) return await metrik.close(input.streamId);
+        return await agentClient.closeStream({ ...input, signedMandate });
       },
-      async reclaimStream(input) {
-        return await agentClient.reclaimStream(input);
+      async reclaimStream({ signedMandate, ...input }) {
+        if (signedMandate === null) {
+          const closeResult = input.closeFirst
+            ? await metrik.close(input.streamId)
+            : null;
+          return {
+            closeResult,
+            reclaimResult: await metrik.reclaim(input.streamId),
+          };
+        }
+        return await agentClient.reclaimStream({ ...input, signedMandate });
       },
-      async reclaimUnverifiedStream(input) {
-        return await agentClient.reclaimUnverifiedStream(input);
+      async reclaimUnverifiedStream({ signedMandate, ...input }) {
+        if (signedMandate === null) {
+          return await metrik.reclaimUnverified(input.streamId);
+        }
+        return await agentClient.reclaimUnverifiedStream({
+          ...input,
+          signedMandate,
+        });
       },
-      async claimStream(input) {
-        return await agentClient.claimStream(input);
+      async claimStream({ signedMandate, ...input }) {
+        if (signedMandate === null) return await metrik.claim(input.streamId);
+        return await agentClient.claimStream({ ...input, signedMandate });
       },
     };
   },
@@ -429,9 +557,45 @@ export const defaultCliDependencies: CliDependencies = {
   nowSeconds() {
     return Math.floor(Date.now() / 1000);
   },
+  x402: {
+    async pay(input) {
+      const { payX402WithMandate } = await import("../x402-buyer/pay.js");
+      return await payX402WithMandate(input);
+    },
+    async refundClient(config, target) {
+      const { refundClient } = await import("@absol-labs/sdk/x402");
+      return refundClient(target.refundUrl, {
+        streamId: target.streamId,
+        ...(target.opener === undefined ? {} : { opener: target.opener }),
+        // Every relay "success" is checked against the receipt on THIS chain.
+        verifyWith: createMetrikClient(config),
+        expectedChainId: config.chainId,
+        ...(target.maxAttempts === undefined
+          ? {}
+          : { maxAttempts: target.maxAttempts }),
+        ...(target.maxDelayMs === undefined
+          ? {}
+          : { maxDelayMs: target.maxDelayMs }),
+      });
+    },
+  },
   async sleep(ms) {
     await new Promise((resolve) => setTimeout(resolve, ms));
   },
 };
 
+/**
+ * The write-client options a resolved wallet implies.
+ *
+ * Kept next to {@link CreateWriteClientOptions} so every fund-moving command
+ * spells the transport decision the same way, and so a wallet that needs a
+ * provider transport cannot be broadcast through a plain RPC by a command that
+ * simply forgot to pass it.
+ */
+export function writeClientOptions(
+  wallet: { readonly transport?: Transport } | null,
+): CreateWriteClientOptions {
+  return wallet?.transport === undefined ? {} : { transport: wallet.transport };
+}
+
 export type { DiscoverResult, ServiceListing };

package/src/cli/errors.ts

@@ -76,6 +76,28 @@ function namesTheRevert(line: string): boolean {
   );
 }
 
+/**
+ * Links that state the OUTCOME rather than open a sentence the next link
+ * completes — so the trailing "…and it reverted" carries nothing.
+ *
+ * `metrik status <a stream id that does not exist>` used to print
+ *
+ *   stream 0x…: does not exist on the escrow: The contract function
+ *   "getStream" reverted.
+ *
+ * The first link is the whole answer; the tail is viem restating that a revert
+ * is how the escrow says so. Contrast "reclaim simulation failed", which is a
+ * PREFIX — dropping the boilerplate after it would leave a failure with no
+ * stated reason at all, which is why the one-boilerplate rule exists.
+ */
+const STATES_THE_OUTCOME: readonly RegExp[] = [
+  /\bdoes not exist on the escrow\b/,
+];
+
+function statesTheOutcome(line: string): boolean {
+  return STATES_THE_OUTCOME.some((pattern) => pattern.test(line));
+}
+
 function isBoilerplate(line: string): boolean {
   return VIEM_BOILERPLATE.some((pattern) => pattern.test(line));
 }
@@ -108,7 +130,8 @@ export function stripRedundantBoilerplate(
   chain: readonly string[],
 ): readonly string[] {
   const decoded = chain.some(
-    (line) => namesTheRevert(line) && !isBoilerplate(line),
+    (line) =>
+      (namesTheRevert(line) || statesTheOutcome(line)) && !isBoilerplate(line),
   );
   let keptBoilerplate = false;
   const kept = chain.filter((line, index) => {

package/src/cli/escape-hatch.ts

@@ -1,5 +1,7 @@
 import type { StreamV2 } from "@absol-labs/sdk";
 
+import { escapeHatchReadyAtFormula } from "../escrow-generation.js";
+
 import { formatDuration } from "./amounts.js";
 import type { CliReadClient } from "./deps.js";
 
@@ -17,9 +19,11 @@ import type { CliReadClient } from "./deps.js";
  * — and `escapeGraceSeconds` is a public immutable on the escrow, so readiness
  * is fully computable before a single wei of gas is spent.
  *
- * Note which timestamp the escrow uses: `expiresAt`, NEVER `closedAt`. Closing a
- * stream early does not bring the escape hatch forward, and the CLI must not
- * imply that it does.
+ * Note which timestamp the escrow uses, which depends on its GENERATION (the
+ * SDK registry's `escrow.generation`; see `../escrow-generation.ts`): V2 uses
+ * `expiresAt`, NEVER `closedAt` — closing early does not bring the hatch
+ * forward, and the CLI must not imply that it does. V3 opens it at
+ * `min(expiresAt, closedAt) + escapeGraceSeconds`.
  */
 export interface EscapeHatchWindow {
   /** `escapeGraceSeconds` as read from the escrow. */
@@ -32,11 +36,21 @@ export interface EscapeHatchWindow {
 }
 
 export function escapeHatchWindow(
-  stream: Pick<StreamV2, "expiresAt">,
+  stream: Pick<StreamV2, "expiresAt"> & Partial<Pick<StreamV2, "closedAt">>,
   graceSeconds: number,
   nowSeconds: number,
+  generation = "v2",
 ): EscapeHatchWindow {
-  const readyAt = stream.expiresAt + graceSeconds;
+  const readyAt = Number(
+    escapeHatchReadyAtFormula(
+      generation,
+      {
+        expiresAt: BigInt(stream.expiresAt),
+        closedAt: BigInt(stream.closedAt ?? 0),
+      },
+      BigInt(graceSeconds),
+    ),
+  );
   const secondsRemaining = readyAt - nowSeconds;
   return {
     graceSeconds,

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.)`,
     },
   );
 }