@clanker-chain/clanker-cli 2026.9.10 → 2026.9.12-1

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,
@@ -165,7 +170,8 @@ function usage() {
   console.log(`clanker - clanker-chain helper CLI
 
 Usage:
-  clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--key-file path] [--force]
+  clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--skip-key] [--bot-key path] [--key-file path] [--force]
+  clanker fund [--address 0x…] [--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;
@@ -90,8 +105,8 @@ export async function runDoctorChecks(opts = {}) {
     ok: true,
     level: hasKey ? "pass" : "warn",
     message: hasKey
-      ? "signing key pointer available (mint/revoke OK)"
-      : "read-only profile — whoami/bots OK; mint needs --key-file or OPERATOR_PRIVATE_KEY",
+      ? "signing key pointer available (mint/pair/rotate OK)"
+      : "read-only profile — whoami/bots/fund OK; mint/pair/rotate need a key pointer or the /join owner",
   });
 
   checks.push({
@@ -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,16 +290,25 @@ 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)"));
+    console.log(
+      c.dim(
+        "Mint/pair/rotate: need a signing key or stay on /join (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",
-      "clanker setup --key-file ~/.clanker/op.key --force   # to enable mint",
+      "clanker bots",
+      "mint/pair/rotate need --key-file / OPERATOR_PRIVATE_KEY or stay on /join",
     ]);
   } else {
     nextHint(["clanker whoami", "clanker bots"]);

package/lib/fund.mjs

@@ -0,0 +1,287 @@
+/**
+ * `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,
+  PRESETS,
+} 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;
+  let address = null;
+  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 === "--address" && argv[i + 1]) address = argv[++i];
+    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)");
+  }
+  if (address && !/^0x[0-9a-fA-F]{40}$/.test(address)) {
+    throw new Error("--address must be 0x + 40 hex");
+  }
+  return { timeoutMs, pollMs, noOpen, json, address };
+}
+
+/**
+ * @param {{ operator?: { key?: object|null, label?: string|null }|null, canSign?: boolean }} opts
+ */
+function fundNextHints(opts = {}) {
+  const canSign = opts.canSign ?? Boolean(opts.operator?.key);
+  if (canSign) {
+    return [
+      "clanker doctor",
+      `clanker operator mint ${opts.operator?.label ?? "<label>"} --yes`,
+      "clanker bot mint <bot_label> --yes",
+    ];
+  }
+  return [
+    "clanker doctor",
+    "clanker whoami",
+    "mint/pair/rotate need a signing key or stay on /join",
+  ];
+}
+
+/**
+ * @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;
+
+  const sepolia = PRESETS.sepolia;
+  let owner;
+  let rpc;
+  let registry;
+  let label = operator?.label ?? null;
+
+  if (flags.address) {
+    owner = getAddress(flags.address);
+    rpc = config?.chainRpcUrl ?? sepolia.chainRpcUrl;
+    registry = config?.registryAddress ?? sepolia.registryAddress;
+  } else {
+    if (!config) {
+      throw new Error(
+        "config.json missing — run clanker setup, or pass --address 0x… to fund before setup",
+      );
+    }
+    if (!operator?.owner || !/^0x[0-9a-fA-F]{40}$/.test(operator.owner)) {
+      throw new Error(
+        "operator.json incomplete — run clanker setup, or pass --address 0x…",
+      );
+    }
+    owner = getAddress(operator.owner);
+    rpc = config.chainRpcUrl ?? "";
+    registry = config.registryAddress;
+  }
+
+  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: 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:    ${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(fundNextHints({ operator, canSign: Boolean(operator?.key) }));
+    }
+    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(fundNextHints({ operator, canSign: Boolean(operator?.key) }));
+      }
+      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}`,
+      flags.address ? `clanker fund --address ${owner}` : "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

@@ -10,9 +10,15 @@ import { defaultOperatorKeyPath } from "./foundry.mjs";
 
 export { defaultOperatorKeyPath };
 
-/** Coinbase Developer Platform faucet UI (Base Sepolia). */
-export const BASE_SEPOLIA_FAUCET_URL =
-  "https://portal.cdp.coinbase.com/products/faucet";
+/** Coinbase Developer Platform portal (Faucets live in-nav; deep link /products/faucet 404s). */
+export const BASE_SEPOLIA_FAUCET_URL = "https://portal.cdp.coinbase.com/";
+
+/** 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).
@@ -42,7 +48,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/resolve.mjs

@@ -78,6 +78,10 @@ export function keyPointerFromSource(opts) {
   return { type: "env", value: "OPERATOR_PRIVATE_KEY" };
 }
 
+/** Honest error when mint/pair/rotate/transfer have no owner signer. */
+export const OWNER_SIGNER_REQUIRED =
+  "Owner actions need a signing key (--key-file / OPERATOR_PRIVATE_KEY) or the browser door that created this address. A read-only profile can still run whoami, bots, fund, and doctor.";
+
 /**
  * Resolve the operator signing key with Anvil guard.
  *
@@ -133,11 +137,7 @@ export function resolveOperatorKey(argv = [], opts = {}) {
       key = normalizePrivateKey(ANVIL_DEFAULT_PRIVATE_KEY);
       source = "anvil-default (local RPC)";
     } else {
-      throw new Error(
-        "Operator private key required for non-local RPC. Set OPERATOR_PRIVATE_KEY, " +
-          "pass --key / --key-file, or configure ~/.clanker/operator.json key pointer. " +
-          "Anvil account #0 is not used on public networks.",
-      );
+      throw new Error(OWNER_SIGNER_REQUIRED);
     }
   }
 
@@ -216,7 +216,11 @@ export function resolveReadIdentity(argv = [], opts = {}) {
     };
   } catch (err) {
     const msg = err?.message ?? String(err);
-    if (!/private key required|Anvil account #0|Key file not found|Profile keyFile/i.test(msg)) {
+    if (
+      !/private key required|Owner actions need a signing key|Anvil account #0|Key file not found|Profile keyFile/i.test(
+        msg,
+      )
+    ) {
       throw err;
     }
   }

package/lib/setup.mjs

@@ -3,7 +3,14 @@
  */
 
 import { stdin as input } from "node:process";
-import { existsSync } from "node:fs";
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
 import { getAddress } from "viem";
 import * as clack from "@clack/prompts";
 import {
@@ -34,12 +41,11 @@ import {
   resolveFoundryAddress,
 } from "./foundry.mjs";
 import {
-  BASE_SEPOLIA_FAUCET_URL,
   consumerFundHints,
   generateOperatorKeyFile,
 } from "./operator-key.mjs";
+import { wireOpenClawMqtt } from "./openclaw-wire.mjs";
 import { c, nextHint } from "./ui.mjs";
-import { join } from "node:path";
 
 /**
  * @param {string[]} argv
@@ -58,6 +64,7 @@ export function parseSetupFlags(argv) {
   let foundryAccount = null;
   let exportKey = false;
   let generateKey = false;
+  let botKey = null;
 
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -68,6 +75,7 @@ export function parseSetupFlags(argv) {
     else if (a === "--key-env" && argv[i + 1]) keyEnv = argv[++i];
     else if (a === "--from-block" && argv[i + 1]) fromBlock = BigInt(argv[++i]);
     else if (a === "--foundry-account" && argv[i + 1]) foundryAccount = argv[++i];
+    else if (a === "--bot-key" && argv[i + 1]) botKey = argv[++i];
     else if (a === "--export-key") exportKey = true;
     else if (a === "--generate-key") generateKey = true;
     else if (a === "--force") force = true;
@@ -90,6 +98,7 @@ export function parseSetupFlags(argv) {
     foundryAccount,
     exportKey,
     generateKey,
+    botKey,
   };
 }
 
@@ -163,6 +172,39 @@ export function buildKeyPointer({ keyFile, keyEnv, skipKey, env = process.env })
   return null;
 }
 
+/**
+ * Copy a downloaded bot key into ~/.openclaw/keys and wire channels.mqtt.
+ * @param {string} botKeyPath
+ * @param {{
+ *   operatorLabel: string,
+ *   network: { rpc: string, registry: string|null, brokerUrl?: string, mqttAuthServiceUrl?: string },
+ *   openclawHome?: string,
+ * }} opts
+ */
+export function attachBotKeyFile(botKeyPath, opts) {
+  if (!existsSync(botKeyPath)) {
+    throw new Error(`Bot key file not found: ${botKeyPath}`);
+  }
+  const botId = basename(botKeyPath).replace(/\.key$/i, "");
+  if (!botId || botId.includes("/") || botId.includes("..")) {
+    throw new Error(`Invalid bot key basename: ${botKeyPath}`);
+  }
+  const openclawHome = opts.openclawHome ?? join(homedir(), ".openclaw");
+  const destDir = join(openclawHome, "keys");
+  mkdirSync(destDir, { recursive: true });
+  const dest = join(destDir, `${botId}.key`);
+  copyFileSync(botKeyPath, dest);
+  chmodSync(dest, 0o600);
+  const wired = wireOpenClawMqtt({
+    botId,
+    operatorId: opts.operatorLabel,
+    network: opts.network,
+    keyPath: dest,
+    openclawHome,
+  });
+  return { botId, keyPath: dest, openclawPath: wired.path };
+}
+
 /**
  * Apply setup choices to disk.
  */
@@ -300,7 +342,7 @@ export async function runSetupNonInteractive(argv, opts = {}) {
     }
   }
 
-  return applySetup(
+  const result = applySetup(
     {
       preset: flags.preset,
       force: flags.force || flags.yes,
@@ -312,6 +354,34 @@ export async function runSetupNonInteractive(argv, opts = {}) {
     },
     { home, env },
   );
+  return finishSetupResult(result, flags, { ...opts, quiet: true });
+}
+
+/**
+ * @param {object} result
+ * @param {{ botKey?: string|null, operator?: string|null }} flags
+ * @param {{ openclawHome?: string, quiet?: boolean }} [opts]
+ */
+async function finishSetupResult(result, flags, opts = {}) {
+  if (flags.botKey) {
+    const attached = attachBotKeyFile(flags.botKey, {
+      operatorLabel: result.operator?.label ?? flags.operator,
+      network: {
+        rpc: result.config.chainRpcUrl,
+        registry: result.config.registryAddress,
+        brokerUrl: result.config.brokerUrl,
+        mqttAuthServiceUrl: result.config.mqttAuthServiceUrl,
+      },
+      openclawHome: opts.openclawHome,
+    });
+    result.botKey = attached;
+    if (!opts.quiet) {
+      clack.log.success(
+        `Bot key → ${attached.keyPath}; wired ${attached.openclawPath}`,
+      );
+    }
+  }
+  return result;
 }
 
 /**
@@ -335,7 +405,7 @@ export async function runSetupInteractive(argv, opts = {}) {
   );
   clack.log.message(
     c.dim(
-      "New here? Create a key file — no wallet app or Foundry required. Mint needs a little test ETH later.",
+      "Attach an existing owner address (/join or any 0x), or create ~/.clanker/op.key. Mint needs test ETH later.",
     ),
   );
   clack.log.message(c.dim(`Profile: ${home}`));
@@ -441,10 +511,15 @@ export async function runSetupInteractive(argv, opts = {}) {
   }
   if (!address) {
     const options = [
+      {
+        value: "__paste__",
+        label: "I already have an owner address",
+        hint: "/join or any 0x — usually read-only",
+      },
       {
         value: "__generate__",
         label: "Create a new operator key for me",
-        hint: "writes ~/.clanker/op.key (recommended)",
+        hint: "writes ~/.clanker/op.key",
       },
       {
         value: "__keyfile__",
@@ -467,20 +542,16 @@ export async function runSetupInteractive(argv, opts = {}) {
         hint: "advanced — install Foundry first",
       });
     }
-    options.push({
-      value: "__paste__",
-      label: "Paste an address…",
-      hint: "read-only unless you add a key later",
-    });
 
     const pick = cancelIf(
       await clack.select({
         message: "How do you want to set your operator identity?",
         options,
-        initialValue: "__generate__",
+        initialValue: "__paste__",
       }),
     );
 
+    let attachReadOnly = false;
     if (pick === "__generate__") {
       const dest = defaultOperatorKeyPath(home);
       let forceGen = flags.force;
@@ -527,15 +598,17 @@ export async function runSetupInteractive(argv, opts = {}) {
             /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
         }),
       );
+      attachReadOnly = true;
     } else if (pick === "__paste__") {
       address = cancelIf(
         await clack.text({
-          message: "Operator owner address",
+          message: "Owner address (from /join or any EOA)",
           placeholder: "0x…",
           validate: (v) =>
             /^0x[0-9a-fA-F]{40}$/.test(v || "") ? undefined : "Need 0x + 40 hex",
         }),
       );
+      attachReadOnly = true;
     } else {
       foundryAccountUsed = pick;
       try {
@@ -558,6 +631,9 @@ export async function runSetupInteractive(argv, opts = {}) {
         );
       }
     }
+    if (attachReadOnly) {
+      flags.skipKey = true;
+    }
   }
   address = getAddress(address);
 
@@ -688,17 +764,20 @@ export async function runSetupInteractive(argv, opts = {}) {
     { home, env },
   );
 
+  await finishSetupResult(result, { ...flags, operator: label }, opts);
+
   clack.outro(c.green(`Wrote ${result.configPath}\nWrote ${result.operatorPath}`));
   if (!key) {
     nextHint([
+      "clanker fund",
       "clanker whoami",
-      "clanker setup — choose Create a new operator key when you need mint",
+      "mint/pair/rotate need a signing key or stay on /join",
     ]);
   } else if (preset === "sepolia" && generatedKeyFile) {
     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-1",
   "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"
   }
 }