@clanker-chain/clanker-cli 2026.9.8 → 2026.9.12

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/identity-query.mjs

@@ -13,7 +13,7 @@ import {
 } from "viem";
 import { clankerIdentityAbi } from "./clanker-identity-abi.mjs";
 
-/** Match identity-service EVM_LOG_CHUNK_BLOCKS — public RPCs reject wide ranges. */
+/** Public RPC eth_getLogs chunk size — wide ranges are often rejected. */
 export const LOG_CHUNK_BLOCKS = 2000n;
 
 export function labelToId(label) {

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/openclaw-wire.mjs

@@ -8,7 +8,7 @@ import { join } from "node:path";
 import { harnessSnippet } from "./profile.mjs";
 
 /** Current published OpenClaw plugin pins for closed-beta invite. */
-export const OPENCLAW_PLUGIN_PIN = "2026.7.29";
+export const OPENCLAW_PLUGIN_PIN = "2026.9.10";
 
 /**
  * @param {string} [openclawHome]
@@ -94,11 +94,52 @@ export function wireOpenClawMqtt(opts) {
 export function hubConnectChecklist(opts) {
   const pin = opts.pluginPin ?? OPENCLAW_PLUGIN_PIN;
   return [
+    "Your bot login is already wired — install plugins and restart OpenClaw.",
     `openclaw plugins install @clanker-chain/mqtt-channel-plugin@${pin}`,
     `openclaw plugins install @clanker-chain/mqtt-tools@${pin}`,
     "Enable plugin ids mqtt + mqtt-tools (already set in openclaw.json if we wired it)",
     `CONNECT broker: ${opts.channelsMqtt?.brokerUrl ?? "mqtts://mqtt.clanker-chain.com:8883"}`,
-    `Ask hub operator to allow bot_id "${opts.botId}" in france dmPolicy / allowFrom`,
+    "Both operators: clanker pair add <peer-operator>  (Policy — required before DMs deliver)",
     "DM openclaw.france.prod-1 to smoke the mesh",
   ];
 }
+
+/**
+ * Plain-language card: what the bot uses vs operator mint key.
+ * @param {{
+ *   botId: string,
+ *   operatorId: string,
+ *   keyPath: string,
+ *   openclawPath: string,
+ *   created?: boolean,
+ * }} opts
+ * @returns {string[]}
+ */
+export function botIdentityCard(opts) {
+  const openclawState = opts.created
+    ? `${opts.openclawPath} (channels.mqtt created)`
+    : `${opts.openclawPath} (channels.mqtt updated)`;
+  return [
+    "Bot identity (what OpenClaw uses to CONNECT):",
+    `bot id:     ${opts.botId}`,
+    `operator:   ${opts.operatorId}`,
+    `bot key:    ${opts.keyPath}`,
+    `openclaw:   ${openclawState}`,
+    "Do not give the bot ~/.clanker/op.key — that key is only for mint/transfer.",
+  ];
+}
+
+/**
+ * Structured bot_identity for --json mint output.
+ * @param {{ botId: string, keyPath: string, openclawConfigPath: string }} opts
+ */
+export function botIdentityJson(opts) {
+  return {
+    botId: opts.botId,
+    keyPath: opts.keyPath,
+    openclawConfigPath: opts.openclawConfigPath,
+    warnOperatorKey:
+      "Do not give the bot ~/.clanker/op.key — that key is only for mint/transfer.",
+  };
+}
+

package/lib/operator-key.mjs

@@ -0,0 +1,58 @@
+/**
+ * Consumer-path operator key helpers (generate local op.key).
+ * Never logs private keys.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+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";
+
+/** 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.
+ *
+ * @param {string} destPath
+ * @param {{ force?: boolean }} [opts]
+ * @returns {{ path: string, address: string }}
+ */
+export function generateOperatorKeyFile(destPath, opts = {}) {
+  if (existsSync(destPath) && !opts.force) {
+    throw new Error(
+      `Key file already exists: ${destPath} (pass --force to overwrite)`,
+    );
+  }
+  const key = generatePrivateKey();
+  const address = privateKeyToAccount(key).address;
+  mkdirSync(dirname(destPath), { recursive: true });
+  writeFileSync(destPath, `${key}\n`, { mode: 0o600 });
+  return { path: destPath, address };
+}
+
+/**
+ * Plain-language next steps after creating an operator key on Sepolia.
+ * @param {{ address: string, label?: string }} opts
+ */
+export function consumerFundHints(opts) {
+  const mintLabel = opts.label ? ` ${opts.label}` : "";
+  return [
+    `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",
+  ];
+}