@clanker-chain/clanker-cli 2026.9.8 → 2026.9.12

package/bin/clanker.mjs

@@ -3,6 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import os from "node:os";
 import process from "node:process";
 import { getAddress } from "viem";
@@ -25,7 +26,14 @@ 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,
   hubConnectChecklist,
   wireOpenClawMqtt,
 } from "../lib/openclaw-wire.mjs";
@@ -95,8 +103,15 @@ function runScript(scriptPath, args = []) {
 }
 
 function findRepoRoot() {
-  const here = dirname(new URL(import.meta.url).pathname);
-  return dirname(dirname(here));
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    if (existsSync(join(dir, "chain", "foundry.toml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  // npm install: package root (no monorepo checkout)
+  return dirname(dirname(fileURLToPath(import.meta.url)));
 }
 
 /** chain up/deploy and check * need the monorepo; npm installs only ship bin/ + lib/. */
@@ -156,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]
@@ -167,6 +183,10 @@ Usage:
   clanker bot status <label> [--json]
   clanker bot revoke <label> [--json] [--yes]
   clanker bot rotate <label> <newKeyAddress> [--json] [--yes]
+  clanker pair add <operator-label> [--yes] [--auth-url URL] [--openclaw-home DIR]
+  clanker pair remove <operator-label> [--auth-url URL] [--openclaw-home DIR]
+  clanker pair list [--auth-url URL]
+  clanker pair status <operator-label> [--auth-url URL]
   clanker init-openclaw
   clanker chain up|deploy|mint-operator|mint-bot|rotate-bot-key|revoke-bot ...
   clanker check mqtt <bot_id> <operator_id>
@@ -177,11 +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.
+See docs/operator-cli.md, docs/prerequisites.md, and docs/trust-model.md.
 `);
 }
 
@@ -395,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",
         ],
       });
@@ -402,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);
@@ -439,6 +477,93 @@ async function main() {
     return;
   }
 
+  if (cmd === "pair") {
+    const [sub, ...pairRest] = rest;
+    if (!sub || !["add", "remove", "list", "status"].includes(sub)) {
+      console.error("Usage: clanker pair add|remove|list|status [operator-label]");
+      process.exit(1);
+    }
+
+    let peerLabel = null;
+    for (let i = 0; i < pairRest.length; i += 1) {
+      const a = pairRest[i];
+      if (a.startsWith("--")) {
+        if (a !== "--json" && a !== "--yes" && pairRest[i + 1] && !pairRest[i + 1].startsWith("--")) {
+          i += 1; // skip flag value
+        }
+        continue;
+      }
+      peerLabel = a;
+      break;
+    }
+
+    const { runPairAction } = await import("../lib/pair.mjs");
+    try {
+      if (sub === "add") {
+        const planRows = [
+          ["action", "pair add (Policy)"],
+          ["peer", peerLabel ?? "(missing)"],
+          ["note", "One-way allow; peer must pair you for bidirectional DMs"],
+        ];
+        const ok = await confirmPlan(pairRest, planRows, `Allow operator ${peerLabel}?`);
+        if (!ok) process.exit(0);
+      }
+      const out = await runPairAction(pairRest, sub, peerLabel);
+      if (hasFlag(pairRest, "--json")) {
+        console.log(JSON.stringify(out, null, 2));
+      } else if (sub === "list") {
+        console.log(`Operator: ${out.operatorId}`);
+        console.log(`Auth: ${out.authUrl}`);
+        const allows = out.listed?.allows ?? [];
+        if (!allows.length) {
+          console.log("(no allows)");
+        } else {
+          for (const a of allows) {
+            console.log(
+              `  ${a.peer_operator_id}  ${a.mutual ? "mutual" : "pending (one-way)"}`,
+            );
+          }
+        }
+      } else if (sub === "status") {
+        console.log(`peer:    ${out.peerLabel}`);
+        console.log(`allowed: ${out.allowed}`);
+        console.log(`mutual:  ${out.mutual}`);
+        if (out.allowed && !out.mutual) {
+          console.log("Waiting for peer to run: clanker pair add <your-operator>");
+        }
+      } else {
+        console.log(
+          `${sub} ${out.peerLabel}: ${out.result?.mutual ? "mutual" : "one-way / pending"}`,
+        );
+        if (out.openclawSync?.synced) {
+          console.log(`Synced allowOperators → ${out.openclawSync.path}`);
+          console.log(
+            "Restart (or reload) the OpenClaw gateway so channels.mqtt.allowOperators is picked up.",
+          );
+        } else if (out.openclawSync?.reason === "missing_openclaw_json") {
+          console.log(
+            `Hub Policy updated, but no openclaw.json at ${out.openclawSync.path} — ` +
+              "client allowOperators was not synced. Create OpenClaw config or set allowOperators manually.",
+          );
+        }
+        if (sub === "add" && !out.result?.mutual) {
+          nextHint(`Ask ${out.peerLabel} to run: clanker pair add ${out.operatorId}`);
+        }
+      }
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "pairing needs operator key + mqtt-auth /pair endpoints",
+        try: [
+          "clanker doctor",
+          "clanker pair add org.peer --auth-url http://127.0.0.1:9090 --yes",
+          "See docs/trust-model.md",
+        ],
+      });
+    }
+    return;
+  }
+
   if (cmd === "operator") {
     const [sub, ...opArgv] = rest;
     const {
@@ -454,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],
@@ -471,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);
@@ -575,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({
@@ -591,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);
@@ -615,18 +821,30 @@ async function main() {
         keyPath: result.key_path,
       });
       if (hasFlag(flags, "--json")) {
-        printJson({ ...result, openclaw: wire });
+        printJson({
+          ...result,
+          openclaw: wire,
+          bot_identity: botIdentityJson({
+            botId: botLabel,
+            keyPath: result.key_path,
+            openclawConfigPath: wire.path,
+          }),
+        });
       } else {
         console.log(c.green(`Minted bot ${botLabel} under ${operatorLabel}`));
         console.log(`botKey:   ${result.bot_key}`);
-        console.log(`key file: ${result.key_path}`);
-        console.log(`also:     ${result.clanker_key_path}`);
         console.log(`tx:       ${result.tx}`);
-        console.log(
-          wire.created
-            ? c.green(`Wrote ${wire.path}`)
-            : c.green(`Updated channels.mqtt in ${wire.path}`),
-        );
+        console.log(c.dim(`also:     ${result.clanker_key_path}`));
+        console.log("");
+        for (const line of botIdentityCard({
+          botId: botLabel,
+          operatorId: operatorLabel,
+          keyPath: result.key_path,
+          openclawPath: wire.path,
+          created: wire.created,
+        })) {
+          console.log(line);
+        }
         nextHint(
           hubConnectChecklist({
             botId: botLabel,
@@ -921,7 +1139,7 @@ async function main() {
     nextHint([
       "clanker bot mint <label>",
       "Then channels.mqtt.botId / operatorId / privateKeyFile update automatically",
-      "See docs/operator-cli.md and docs/closed-beta-invite.md",
+      "See docs/operator-cli.md and docs/public-testnet-hub.md",
     ]);
     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",