@clanker-chain/clanker-cli 2026.9.10 → 2026.9.12

package/bin/clanker.mjs

@@ -26,6 +26,11 @@ import {
 import { resolveForRead, resolveOperatorKey, resolveReadIdentity } from "../lib/resolve.mjs";
 import { runSetup } from "../lib/setup.mjs";
 import { runDoctor } from "../lib/doctor.mjs";
+import { runFund } from "../lib/fund.mjs";
+import {
+  assessMintBudget,
+  formatEthTrim,
+} from "../lib/mint-budget.mjs";
 import {
   botIdentityCard,
   botIdentityJson,
@@ -166,6 +171,7 @@ function usage() {
 
 Usage:
   clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--key-file path] [--force]
+  clanker fund [--no-open] [--timeout ms] [--json]
   clanker doctor [--json]
   clanker init --preset sepolia|local [--force]
   clanker whoami [--json] [--operator <label>] [--address 0x…] [--with-bots]
@@ -191,12 +197,12 @@ Profile:
   ~/.clanker/operator.json   label + owner + optional key pointer (never raw hex)
   ~/.clanker/keys/           bot keys (also written to ~/.openclaw/keys/)
 
-Humans: \`clanker setup\` then \`clanker doctor\` / \`whoami\`.
+Humans: \`clanker setup\` then \`clanker fund\` / \`doctor\` / \`whoami\`.
 Pairing (Policy): both operators run \`clanker pair add\` before DMs deliver on the hub.
 Mutates print a plan and confirm unless --yes or --json.
 whoami is fast by default; pass --with-bots to enrich child bots (or use \`clanker bots\`).
 
-See docs/operator-cli.md and docs/trust-model.md.
+See docs/operator-cli.md, docs/prerequisites.md, and docs/trust-model.md.
 `);
 }
 
@@ -410,6 +416,7 @@ async function main() {
         because: "setup could not write a valid local profile",
         try: [
           "clanker setup --preset sepolia --operator org.you --address 0x… --yes --force",
+          "clanker fund",
           "clanker doctor",
         ],
       });
@@ -417,6 +424,22 @@ async function main() {
     return;
   }
 
+  if (cmd === "fund") {
+    try {
+      const { exitCode } = await runFund(rest);
+      process.exit(exitCode);
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "fund needs a Sepolia profile with an owner address",
+        try: [
+          "clanker setup --preset sepolia --operator org.you --generate-key --yes --force",
+          "clanker fund",
+        ],
+      });
+    }
+  }
+
   if (cmd === "doctor") {
     const { exitCode } = await runDoctor(rest);
     process.exit(exitCode);
@@ -556,8 +579,9 @@ async function main() {
         process.exit(1);
       }
       let planRows;
+      let preview;
       try {
-        const preview = resolveOperatorKey(flags);
+        preview = resolveOperatorKey(flags);
         planRows = [
           ["action", "registerOperator"],
           ["label", label],
@@ -573,10 +597,42 @@ async function main() {
           try: [
             "export OPERATOR_PRIVATE_KEY=0x…",
             "clanker operator mint " + label + " --key-file ~/.clanker/op.key --yes",
+            "clanker fund",
             "clanker doctor",
           ],
         });
       }
+      try {
+        if (preview.network.registry) {
+          const pub = await publicClientFromRpc(preview.network.rpc);
+          const budget = await assessMintBudget({
+            pub,
+            registry: preview.network.registry,
+            owner: preview.address,
+            rpc: preview.network.rpc,
+            operatorLabel: label,
+            mode: "operator",
+          });
+          planRows.push(
+            ["fee", `${formatEthTrim(budget.operatorFeeWei)} ETH`],
+            ["balance", `${formatEthTrim(budget.balanceWei)} ETH`],
+            [
+              "needed",
+              `${formatEthTrim(budget.neededWei)} ETH (fee + gas cushion)`,
+            ],
+          );
+          if (!budget.funded) {
+            exitCliError({
+              error: `insufficient ETH: have ${formatEthTrim(budget.balanceWei)}, need ${formatEthTrim(budget.neededWei)}`,
+              because: "mint sends the exact registry fee plus gas",
+              try: ["clanker fund", "clanker doctor"],
+            });
+          }
+        }
+      } catch (err) {
+        // Non-fatal if RPC read fails before confirm; mint will still fail clearly.
+        planRows.push(["balance", `(could not check: ${err.message ?? err})`]);
+      }
       const ok = await confirmPlan(flags, planRows, `Mint operator ${label}?`);
       if (!ok) process.exit(0);
       const result = await chainMintOperator(label, flags);
@@ -677,10 +733,11 @@ async function main() {
         process.exit(1);
       }
       let operatorLabel = operatorArg ?? flagValue(flags, "--operator") ?? null;
+      let preview = null;
       if (!operatorLabel) {
         try {
-          const { address, network } = resolveOperatorKey(flags);
-          const inferred = await resolveOperatorLabel(flags, address, network);
+          preview = resolveOperatorKey(flags);
+          const inferred = await resolveOperatorLabel(flags, preview.address, preview.network);
           operatorLabel = inferred.label;
         } catch (err) {
           exitCliError({
@@ -693,13 +750,60 @@ async function main() {
           });
         }
       }
+      if (!preview) {
+        try {
+          preview = resolveOperatorKey(flags);
+        } catch (err) {
+          exitCliError({
+            error: err.message,
+            because: "bot mint needs a signing key on this network",
+            try: [
+              `clanker bot mint ${botLabel} ${operatorLabel} --key-file ~/.clanker/op.key --yes`,
+              "clanker fund",
+            ],
+          });
+        }
+      }
+      const planRows = [
+        ["action", "registerBot"],
+        ["bot", botLabel],
+        ["operator", operatorLabel],
+        ["owner", preview.address],
+        ["registry", preview.network.registry ?? "(none)"],
+      ];
+      try {
+        if (preview.network.registry) {
+          const pub = await publicClientFromRpc(preview.network.rpc);
+          const budget = await assessMintBudget({
+            pub,
+            registry: preview.network.registry,
+            owner: preview.address,
+            rpc: preview.network.rpc,
+            operatorLabel,
+            mode: "bot",
+          });
+          planRows.push(
+            ["fee", `${formatEthTrim(budget.botFeeWei)} ETH`],
+            ["balance", `${formatEthTrim(budget.balanceWei)} ETH`],
+            [
+              "needed",
+              `${formatEthTrim(budget.neededWei)} ETH (fee + gas cushion)`,
+            ],
+          );
+          if (!budget.funded) {
+            exitCliError({
+              error: `insufficient ETH: have ${formatEthTrim(budget.balanceWei)}, need ${formatEthTrim(budget.neededWei)}`,
+              because: "mint sends the exact registry fee plus gas",
+              try: ["clanker fund", "clanker doctor"],
+            });
+          }
+        }
+      } catch (err) {
+        planRows.push(["balance", `(could not check: ${err.message ?? err})`]);
+      }
       const ok = await confirmPlan(
         flags,
-        [
-          ["action", "registerBot"],
-          ["bot", botLabel],
-          ["operator", operatorLabel],
-        ],
+        planRows,
         `Mint bot ${botLabel} under ${operatorLabel}?`,
       );
       if (!ok) process.exit(0);

package/lib/clanker-identity-abi.mjs

@@ -19,6 +19,11 @@ export const clankerIdentityAbi = [
         "name": "_feeRecipient",
         "type": "address",
         "internalType": "address"
+      },
+      {
+        "name": "_priorRegistry",
+        "type": "address",
+        "internalType": "address"
       }
     ],
     "stateMutability": "nonpayable"
@@ -176,6 +181,19 @@ export const clankerIdentityAbi = [
     ],
     "stateMutability": "view"
   },
+  {
+    "type": "function",
+    "name": "priorRegistry",
+    "inputs": [],
+    "outputs": [
+      {
+        "name": "",
+        "type": "address",
+        "internalType": "address"
+      }
+    ],
+    "stateMutability": "view"
+  },
   {
     "type": "function",
     "name": "proposeOperatorTransfer",

package/lib/doctor.mjs

@@ -11,10 +11,25 @@ import {
   clankerHome,
 } from "./profile.mjs";
 import { detectSetupHints, formatSetupDetectTable } from "./setup-detect.mjs";
+import { publicClientFromRpc } from "./identity-query.mjs";
+import {
+  assessMintBudget,
+  budgetToJson,
+  formatBudgetSummary,
+} from "./mint-budget.mjs";
 import { c, nextHint } from "./ui.mjs";
 
 /**
- * @param {{ home?: string, env?: NodeJS.ProcessEnv, openclawDir?: string, castBin?: string, spawn?: Function, fetchImpl?: typeof fetch }} [opts]
+ * @param {{
+ *   home?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   openclawDir?: string,
+ *   castBin?: string,
+ *   spawn?: Function,
+ *   fetchImpl?: typeof fetch,
+ *   publicClient?: { readContract: Function, getBalance: Function },
+ *   skipBalance?: boolean,
+ * }} [opts]
  */
 export async function runDoctorChecks(opts = {}) {
   const env = opts.env ?? process.env;
@@ -103,6 +118,59 @@ export async function runDoctorChecks(opts = {}) {
       : "Foundry cast not on PATH (optional)",
   });
 
+  /** @type {object|null} */
+  let budget = null;
+
+  const canCheckBalance =
+    !opts.skipBalance &&
+    hasOwner &&
+    registry &&
+    /^0x[0-9a-fA-F]{40}$/.test(registry) &&
+    rpc;
+
+  if (canCheckBalance) {
+    try {
+      if (isLocalRpc(rpc)) {
+        budget = await assessMintBudget({
+          pub: { readContract: async () => 0n, getBalance: async () => 0n },
+          registry,
+          owner: getAddress(operator.owner),
+          rpc,
+          operatorLabel: operator.label,
+        });
+        checks.push({
+          id: "balance",
+          ok: true,
+          level: "pass",
+          message: formatBudgetSummary(budget),
+        });
+      } else {
+        const pub =
+          opts.publicClient ?? (await publicClientFromRpc(rpc));
+        budget = await assessMintBudget({
+          pub,
+          registry,
+          owner: getAddress(operator.owner),
+          rpc,
+          operatorLabel: operator.label,
+        });
+        checks.push({
+          id: "balance",
+          ok: budget.funded,
+          level: budget.funded ? "pass" : "fail",
+          message: formatBudgetSummary(budget),
+        });
+      }
+    } catch (err) {
+      checks.push({
+        id: "balance",
+        ok: false,
+        level: "warn",
+        message: `balance check skipped: ${err.message ?? err}`,
+      });
+    }
+  }
+
   const authUrl = config?.mqttAuthServiceUrl;
   if (authUrl && typeof fetchImpl === "function") {
     const healthUrl = `${String(authUrl).replace(/\/$/, "")}/health`;
@@ -146,8 +214,12 @@ export async function runDoctorChecks(opts = {}) {
   const readyWhoami = checks
     .filter((ch) => ch.id === "config" || ch.id === "registry" || ch.id === "operator")
     .every((ch) => ch.ok);
-  const readyMint = readyWhoami && hasKey &&
-    !checks.some((ch) => ch.id === "anvil_public" && !ch.ok);
+  const balanceOk = !checks.some((ch) => ch.id === "balance" && ch.level === "fail");
+  const readyMint =
+    readyWhoami &&
+    hasKey &&
+    !checks.some((ch) => ch.id === "anvil_public" && !ch.ok) &&
+    balanceOk;
 
   return {
     home,
@@ -156,17 +228,19 @@ export async function runDoctorChecks(opts = {}) {
     readyWhoami,
     readyMint,
     ok: readyWhoami,
+    budget,
   };
 }
 
 /**
  * @param {string[]} argv
- * @param {{ home?: string, env?: NodeJS.ProcessEnv }} [opts]
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv, publicClient?: object, skipBalance?: boolean }} [opts]
  * @returns {Promise<{ exitCode: number, report: object }>}
  */
 export async function runDoctor(argv = [], opts = {}) {
   const json = argv.includes("--json");
   const report = await runDoctorChecks(opts);
+  const budgetJson = report.budget ? budgetToJson(report.budget) : null;
 
   if (json) {
     console.log(
@@ -177,6 +251,15 @@ export async function runDoctor(argv = [], opts = {}) {
           readyMint: report.readyMint,
           home: report.home,
           checks: report.checks,
+          ...(budgetJson
+            ? {
+                balanceWei: budgetJson.balanceWei,
+                neededWei: budgetJson.neededWei,
+                shortfallWei: budgetJson.shortfallWei,
+                claimsNeeded: budgetJson.claimsNeeded,
+                budget: budgetJson,
+              }
+            : {}),
         },
         null,
         2,
@@ -207,12 +290,16 @@ export async function runDoctor(argv = [], opts = {}) {
   }
   if (report.readyMint) {
     console.log(c.green("Ready for: clanker operator mint / bot mint"));
+  } else if (report.budget && !report.budget.funded && !report.budget.local) {
+    console.log(c.dim("Mint: fund the operator address first (clanker fund)"));
   } else {
     console.log(c.dim("Mint/revoke: need signing key (and non-Anvil owner on public RPC)"));
   }
 
   if (!report.readyWhoami) {
     nextHint(["clanker setup"]);
+  } else if (report.budget && !report.budget.funded && !report.budget.local) {
+    nextHint(["clanker fund", "clanker doctor"]);
   } else if (!report.readyMint) {
     nextHint([
       "clanker whoami",

package/lib/fund.mjs

@@ -0,0 +1,250 @@
+/**
+ * `clanker fund` — print mint ETH budget, open faucet, poll until funded.
+ */
+
+import { spawn } from "node:child_process";
+import { getAddress } from "viem";
+import { clankerHome, loadConfig, loadOperator, isLocalRpc } from "./profile.mjs";
+import { publicClientFromRpc } from "./identity-query.mjs";
+import {
+  assessMintBudget,
+  budgetToJson,
+  formatBudgetSummary,
+  formatEthTrim,
+} from "./mint-budget.mjs";
+import { c, nextHint } from "./ui.mjs";
+
+export const DEFAULT_FUND_TIMEOUT_MS = 5 * 60 * 1000;
+export const DEFAULT_FUND_POLL_MS = 5000;
+
+/**
+ * Best-effort open URL in the default browser. Never throws.
+ * @param {string} url
+ * @param {{ platform?: string, spawnImpl?: typeof spawn }} [opts]
+ * @returns {Promise<boolean>}
+ */
+export async function openUrl(url, opts = {}) {
+  const platform = opts.platform ?? process.platform;
+  const spawnImpl = opts.spawnImpl ?? spawn;
+  try {
+    if (platform === "darwin") {
+      spawnImpl("open", [url], { stdio: "ignore", detached: true }).unref();
+      return true;
+    }
+    if (platform === "win32") {
+      spawnImpl("cmd", ["/c", "start", "", url], {
+        stdio: "ignore",
+        detached: true,
+      }).unref();
+      return true;
+    }
+    spawnImpl("xdg-open", [url], { stdio: "ignore", detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {string[]} argv
+ */
+export function parseFundFlags(argv) {
+  let timeoutMs = DEFAULT_FUND_TIMEOUT_MS;
+  let pollMs = DEFAULT_FUND_POLL_MS;
+  let noOpen = false;
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--no-open") noOpen = true;
+    else if (a === "--json") json = true;
+    else if (a === "--timeout" && argv[i + 1]) {
+      timeoutMs = Number(argv[++i]);
+    } else if (a === "--poll" && argv[i + 1]) {
+      pollMs = Number(argv[++i]);
+    }
+  }
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new Error("--timeout must be a non-negative number (ms)");
+  }
+  if (!Number.isFinite(pollMs) || pollMs < 100) {
+    throw new Error("--poll must be >= 100 (ms)");
+  }
+  return { timeoutMs, pollMs, noOpen, json };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{
+ *   home?: string,
+ *   env?: NodeJS.ProcessEnv,
+ *   publicClient?: { readContract: Function, getBalance: Function },
+ *   openUrlImpl?: typeof openUrl,
+ *   sleep?: (ms: number) => Promise<void>,
+ *   now?: () => number,
+ * }} [opts]
+ */
+export async function runFund(argv = [], opts = {}) {
+  const flags = parseFundFlags(argv);
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? clankerHome(env);
+  const config = loadConfig(home);
+  const operator = loadOperator(home);
+  const sleep =
+    opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? (() => Date.now());
+  const openUrlImpl = opts.openUrlImpl ?? openUrl;
+
+  if (!config) {
+    throw new Error("config.json missing — run clanker setup");
+  }
+  if (!operator?.owner || !/^0x[0-9a-fA-F]{40}$/.test(operator.owner)) {
+    throw new Error("operator.json incomplete — run clanker setup");
+  }
+
+  const rpc = config.chainRpcUrl ?? "";
+  const registry = config.registryAddress;
+  const owner = getAddress(operator.owner);
+
+  if (isLocalRpc(rpc)) {
+    const payload = {
+      ok: true,
+      funded: true,
+      local: true,
+      owner,
+      message: "Anvil is prefunded — no faucet needed",
+    };
+    if (flags.json) {
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      console.log(c.bold("clanker fund"));
+      console.log("");
+      console.log(c.green("Anvil is prefunded — no faucet needed."));
+      nextHint(["clanker doctor", "clanker whoami"]);
+    }
+    return { exitCode: 0, ...payload };
+  }
+
+  if (!registry || !/^0x[0-9a-fA-F]{40}$/.test(registry)) {
+    throw new Error(
+      "registry missing — run clanker setup --preset sepolia (or set after local deploy)",
+    );
+  }
+
+  const pub = opts.publicClient ?? (await publicClientFromRpc(rpc));
+
+  const assess = () =>
+    assessMintBudget({
+      pub,
+      registry,
+      owner,
+      rpc,
+      operatorLabel: operator.label,
+    });
+
+  let budget = await assess();
+
+  if (flags.json && budget.funded) {
+    console.log(
+      JSON.stringify({ ok: true, ...budgetToJson(budget) }, null, 2),
+    );
+    return { exitCode: 0, funded: true, budget };
+  }
+
+  if (!flags.json) {
+    console.log(c.bold("clanker fund"));
+    console.log("");
+    console.log(`owner:    ${owner}`);
+    console.log(`label:    ${operator.label ?? "(none)"}`);
+    console.log(`registry: ${registry}`);
+    console.log(`budget:   ${formatBudgetSummary(budget)}`);
+    console.log(`faucet:   ${budget.faucetUrl}`);
+    console.log(`backup:   ${budget.backupFaucetUrl}`);
+    console.log("");
+  }
+
+  if (budget.funded) {
+    if (!flags.json) {
+      console.log(c.green("Already funded for remaining mint fees + gas."));
+      nextHint([
+        "clanker doctor",
+        `clanker operator mint ${operator.label ?? "<label>"} --yes`,
+        "clanker bot mint <bot_label> --yes",
+      ]);
+    }
+    return { exitCode: 0, funded: true, budget };
+  }
+
+  if (!flags.noOpen) {
+    const opened = await openUrlImpl(budget.faucetUrl);
+    if (!flags.json) {
+      if (opened) {
+        console.log(c.dim(`Opened faucet in browser (paste ${owner}).`));
+      } else {
+        console.log(
+          c.dim(`Could not open browser — visit ${budget.faucetUrl}`),
+        );
+      }
+      console.log(
+        c.dim(
+          `Select Base Sepolia → ETH. CDP ~${budget.dripEth} ETH/claim; claim ~${budget.claimsNeeded} time(s).`,
+        ),
+      );
+      console.log(c.dim("Waiting for balance…"));
+      console.log("");
+    }
+  } else if (!flags.json) {
+    console.log(c.dim(`Open faucet: ${budget.faucetUrl}`));
+    console.log(c.dim(`Paste address: ${owner}`));
+    console.log(c.dim("Waiting for balance…"));
+    console.log("");
+  }
+
+  const deadline = now() + flags.timeoutMs;
+  while (now() < deadline) {
+    await sleep(flags.pollMs);
+    budget = await assess();
+    if (!flags.json) {
+      console.log(
+        c.dim(
+          `have ${formatEthTrim(budget.balanceWei)} / need ${formatEthTrim(budget.neededWei)} ETH`,
+        ),
+      );
+    }
+    if (budget.funded) {
+      if (flags.json) {
+        console.log(
+          JSON.stringify({ ok: true, ...budgetToJson(budget) }, null, 2),
+        );
+      } else {
+        console.log("");
+        console.log(c.green("Funded. Ready to mint."));
+        nextHint([
+          "clanker doctor",
+          `clanker operator mint ${operator.label ?? "<label>"} --yes`,
+          "clanker bot mint <bot_label> --yes",
+        ]);
+      }
+      return { exitCode: 0, funded: true, budget };
+    }
+  }
+
+  if (flags.json) {
+    console.log(
+      JSON.stringify(
+        { ok: false, funded: false, timedOut: true, ...budgetToJson(budget) },
+        null,
+        2,
+      ),
+    );
+  } else {
+    console.log("");
+    console.log(c.red("Timed out waiting for funds."));
+    console.log(formatBudgetSummary(budget));
+    nextHint([
+      `Open ${budget.faucetUrl} and claim again`,
+      `Backup: ${budget.backupFaucetUrl}`,
+      "clanker fund",
+    ]);
+  }
+  return { exitCode: 1, funded: false, budget, timedOut: true };
+}

package/lib/mint-budget.mjs

@@ -0,0 +1,237 @@
+/**
+ * Mint ETH budget helpers: live registry fees + balance + CDP faucet claim estimate.
+ */
+
+import { formatEther, parseEther } from "viem";
+import { clankerIdentityAbi } from "./clanker-identity-abi.mjs";
+import { readOperator } from "./identity-query.mjs";
+import { isLocalRpc } from "./profile.mjs";
+import {
+  ALCHEMY_BASE_SEPOLIA_FAUCET_URL,
+  BASE_SEPOLIA_FAUCET_URL,
+  CDP_FAUCET_DRIP_ETH,
+} from "./operator-key.mjs";
+
+/** Fixed gas cushion for one operator mint + one bot mint (no live estimateGas). */
+export const MINT_GAS_RESERVE_WEI = parseEther("0.00005");
+
+/** Documented CDP Base Sepolia ETH drip per claim (wei). */
+export const CDP_FAUCET_DRIP_WEI = parseEther(CDP_FAUCET_DRIP_ETH);
+
+/**
+ * @param {bigint} wei
+ * @returns {string}
+ */
+export function formatEthTrim(wei) {
+  const s = formatEther(wei);
+  if (!s.includes(".")) return s;
+  const trimmed = s.replace(/\.?0+$/, "");
+  return trimmed === "" ? "0" : trimmed;
+}
+
+/**
+ * Ceiling of shortfall / drip (integer claims).
+ * @param {bigint} shortfallWei
+ * @param {bigint} [dripWei]
+ * @returns {number}
+ */
+export function claimsNeeded(shortfallWei, dripWei = CDP_FAUCET_DRIP_WEI) {
+  if (shortfallWei <= 0n) return 0;
+  if (dripWei <= 0n) return 0;
+  return Number((shortfallWei + dripWei - 1n) / dripWei);
+}
+
+/**
+ * Pure budget math given fees, balance, and which fees remain.
+ *
+ * @param {{
+ *   operatorFee: bigint,
+ *   botFee: bigint,
+ *   balance: bigint,
+ *   needOperatorFee: boolean,
+ *   needBotFee: boolean,
+ *   gasReserve?: bigint,
+ *   local?: boolean,
+ * }} opts
+ */
+export function computeMintBudget(opts) {
+  const gasReserve = opts.gasReserve ?? MINT_GAS_RESERVE_WEI;
+  if (opts.local) {
+    return {
+      local: true,
+      funded: true,
+      balanceWei: opts.balance,
+      operatorFeeWei: opts.operatorFee,
+      botFeeWei: opts.botFee,
+      gasReserveWei: gasReserve,
+      feesWei: 0n,
+      neededWei: 0n,
+      shortfallWei: 0n,
+      claimsNeeded: 0,
+      needOperatorFee: false,
+      needBotFee: false,
+    };
+  }
+
+  let feesWei = 0n;
+  if (opts.needOperatorFee) feesWei += opts.operatorFee;
+  if (opts.needBotFee) feesWei += opts.botFee;
+  // If nothing left to mint, needed is 0 (already funded for first operator+bot path).
+  const effectiveNeeded =
+    !opts.needOperatorFee && !opts.needBotFee ? 0n : feesWei + gasReserve;
+  const shortfallWei =
+    opts.balance >= effectiveNeeded ? 0n : effectiveNeeded - opts.balance;
+
+  return {
+    local: false,
+    funded: shortfallWei === 0n,
+    balanceWei: opts.balance,
+    operatorFeeWei: opts.operatorFee,
+    botFeeWei: opts.botFee,
+    gasReserveWei: gasReserve,
+    feesWei,
+    neededWei: effectiveNeeded,
+    shortfallWei,
+    claimsNeeded: claimsNeeded(shortfallWei),
+    needOperatorFee: opts.needOperatorFee,
+    needBotFee: opts.needBotFee,
+  };
+}
+
+/**
+ * Read live fees + balance and decide remaining fees for the onboarding path.
+ *
+ * @param {{
+ *   pub: { readContract: Function, getBalance: Function },
+ *   registry: string,
+ *   owner: string,
+ *   rpc: string,
+ *   operatorLabel?: string|null,
+ *   mode?: 'onboarding'|'operator'|'bot',
+ *   gasReserve?: bigint,
+ * }} opts
+ */
+export async function assessMintBudget(opts) {
+  const local = isLocalRpc(opts.rpc);
+  if (local) {
+    return computeMintBudget({
+      operatorFee: 0n,
+      botFee: 0n,
+      balance: 0n,
+      needOperatorFee: false,
+      needBotFee: false,
+      local: true,
+      gasReserve: opts.gasReserve,
+    });
+  }
+
+  if (!opts.registry || !/^0x[0-9a-fA-F]{40}$/.test(opts.registry)) {
+    throw new Error("registry address required to assess mint budget");
+  }
+
+  const [operatorFee, botFee, balance] = await Promise.all([
+    opts.pub.readContract({
+      address: opts.registry,
+      abi: clankerIdentityAbi,
+      functionName: "operatorFee",
+    }),
+    opts.pub.readContract({
+      address: opts.registry,
+      abi: clankerIdentityAbi,
+      functionName: "botFee",
+    }),
+    opts.pub.getBalance({ address: opts.owner }),
+  ]);
+
+  const mode = opts.mode ?? "onboarding";
+  let needOperatorFee = false;
+  let needBotFee = false;
+
+  if (mode === "operator") {
+    needOperatorFee = true;
+    needBotFee = false;
+  } else if (mode === "bot") {
+    needOperatorFee = false;
+    needBotFee = true;
+  } else {
+    // onboarding: operator + first bot unless operator already active
+    needBotFee = true;
+    needOperatorFee = true;
+    if (opts.operatorLabel) {
+      try {
+        const op = await readOperator(opts.pub, opts.registry, opts.operatorLabel);
+        if (op.active) {
+          needOperatorFee = false;
+        }
+      } catch {
+        // keep both fees if read fails
+      }
+    }
+  }
+
+  const budget = computeMintBudget({
+    operatorFee: BigInt(operatorFee),
+    botFee: BigInt(botFee),
+    balance: BigInt(balance),
+    needOperatorFee,
+    needBotFee,
+    gasReserve: opts.gasReserve,
+    local: false,
+  });
+
+  return {
+    ...budget,
+    owner: opts.owner,
+    registry: opts.registry,
+    operatorLabel: opts.operatorLabel ?? null,
+    faucetUrl: BASE_SEPOLIA_FAUCET_URL,
+    backupFaucetUrl: ALCHEMY_BASE_SEPOLIA_FAUCET_URL,
+    dripEth: CDP_FAUCET_DRIP_ETH,
+  };
+}
+
+/**
+ * Human-readable one-liner for doctor / fund.
+ * @param {ReturnType<typeof computeMintBudget> & { dripEth?: string }} budget
+ */
+export function formatBudgetSummary(budget) {
+  if (budget.local) {
+    return "local RPC — Anvil accounts are prefunded";
+  }
+  if (budget.funded) {
+    return `have ${formatEthTrim(budget.balanceWei)} ETH (need ${formatEthTrim(budget.neededWei)} ETH)`;
+  }
+  const parts = [];
+  if (budget.needOperatorFee) parts.push(`operator fee ${formatEthTrim(budget.operatorFeeWei)}`);
+  if (budget.needBotFee) parts.push(`bot fee ${formatEthTrim(budget.botFeeWei)}`);
+  parts.push(`gas ~${formatEthTrim(budget.gasReserveWei)}`);
+  const drip = budget.dripEth ?? CDP_FAUCET_DRIP_ETH;
+  return (
+    `have ${formatEthTrim(budget.balanceWei)} ETH, need ${formatEthTrim(budget.neededWei)} ETH` +
+    ` (${parts.join(" + ")}). CDP ~${drip} ETH/claim → claim ~${budget.claimsNeeded} time(s)`
+  );
+}
+
+/**
+ * JSON-serializable budget fields (wei as strings).
+ * @param {object} budget
+ */
+export function budgetToJson(budget) {
+  return {
+    local: Boolean(budget.local),
+    funded: Boolean(budget.funded),
+    balanceWei: String(budget.balanceWei ?? 0n),
+    neededWei: String(budget.neededWei ?? 0n),
+    shortfallWei: String(budget.shortfallWei ?? 0n),
+    claimsNeeded: budget.claimsNeeded ?? 0,
+    operatorFeeWei: String(budget.operatorFeeWei ?? 0n),
+    botFeeWei: String(budget.botFeeWei ?? 0n),
+    gasReserveWei: String(budget.gasReserveWei ?? 0n),
+    needOperatorFee: Boolean(budget.needOperatorFee),
+    needBotFee: Boolean(budget.needBotFee),
+    owner: budget.owner ?? null,
+    faucetUrl: budget.faucetUrl ?? BASE_SEPOLIA_FAUCET_URL,
+    backupFaucetUrl: budget.backupFaucetUrl ?? ALCHEMY_BASE_SEPOLIA_FAUCET_URL,
+    dripEth: budget.dripEth ?? CDP_FAUCET_DRIP_ETH,
+  };
+}

package/lib/operator-key.mjs

@@ -14,6 +14,13 @@ export { defaultOperatorKeyPath };
 export const BASE_SEPOLIA_FAUCET_URL =
   "https://portal.cdp.coinbase.com/products/faucet";
 
+/** Backup Base Sepolia faucet (amounts not guaranteed). */
+export const ALCHEMY_BASE_SEPOLIA_FAUCET_URL =
+  "https://www.alchemy.com/faucets/base-sepolia";
+
+/** Documented CDP ETH drip per claim on Base Sepolia. */
+export const CDP_FAUCET_DRIP_ETH = "0.0001";
+
 /**
  * Generate a new secp256k1 key and write it to destPath (mode 0o600).
  * Does not print the key.
@@ -42,7 +49,8 @@ export function generateOperatorKeyFile(destPath, opts = {}) {
 export function consumerFundHints(opts) {
   const mintLabel = opts.label ? ` ${opts.label}` : "";
   return [
-    `Your operator address is ${opts.address} — fund it with Base Sepolia ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+    `Your operator address is ${opts.address} — fund it with Base Sepolia ETH`,
+    "clanker fund",
     "clanker doctor",
     `clanker operator mint${mintLabel} --yes`,
     "clanker bot mint <bot_label> --yes",

package/lib/setup.mjs

@@ -34,7 +34,6 @@ import {
   resolveFoundryAddress,
 } from "./foundry.mjs";
 import {
-  BASE_SEPOLIA_FAUCET_URL,
   consumerFundHints,
   generateOperatorKeyFile,
 } from "./operator-key.mjs";
@@ -698,7 +697,7 @@ export async function runSetupInteractive(argv, opts = {}) {
     nextHint(consumerFundHints({ address, label }));
   } else if (preset === "sepolia") {
     nextHint([
-      `If this address needs test ETH: ${BASE_SEPOLIA_FAUCET_URL}`,
+      "clanker fund",
       "clanker doctor",
       "clanker whoami",
       `clanker bot mint <label>`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clanker-chain/clanker-cli",
-  "version": "2026.9.10",
+  "version": "2026.9.12",
   "description": "CLI for wiring clanker-chain identity and MQTT into OpenClaw and other agentic stacks.",
   "type": "module",
   "bin": {
@@ -25,6 +25,9 @@
   "dependencies": {
     "@clack/prompts": "^1.8.0",
     "picocolors": "^1.1.1",
-    "viem": "^2.21.0"
+    "viem": "^2.56.3"
+  },
+  "overrides": {
+    "ws": "^8.21.0"
   }
 }