@clanker-chain/clanker-cli 2026.9.7-1

package/lib/identity-query.mjs

@@ -0,0 +1,364 @@
+/**
+ * Read-only identity queries via contract storage + event logs.
+ */
+
+import {
+  createPublicClient,
+  defineChain,
+  getAddress,
+  http,
+  keccak256,
+  toBytes,
+  parseAbiItem,
+} from "viem";
+import { clankerIdentityAbi } from "./clanker-identity-abi.mjs";
+
+/** Match identity-service EVM_LOG_CHUNK_BLOCKS — public RPCs reject wide ranges. */
+export const LOG_CHUNK_BLOCKS = 2000n;
+
+export function labelToId(label) {
+  return keccak256(toBytes(label));
+}
+
+const OPERATOR_REGISTERED = parseAbiItem(
+  "event OperatorRegistered(bytes32 indexed id, address indexed owner, string label)",
+);
+const OPERATOR_TRANSFERRED = parseAbiItem(
+  "event OperatorTransferred(bytes32 indexed id, address indexed oldOwner, address indexed newOwner)",
+);
+const BOT_REGISTERED = parseAbiItem(
+  "event BotRegistered(bytes32 indexed id, bytes32 indexed operatorId, address indexed botKey, string label)",
+);
+
+/**
+ * @param {string} rpc
+ */
+export async function publicClientFromRpc(rpc) {
+  const transport = http(rpc);
+  const bare = createPublicClient({ transport });
+  const id = await bare.getChainId();
+  const chain = defineChain({
+    id,
+    name: `clanker-chain-${id}`,
+    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
+    rpcUrls: { default: { http: [rpc] } },
+  });
+  return createPublicClient({ chain, transport });
+}
+
+/**
+ * eth_getLogs in fixed-size block chunks (public RPC safe).
+ *
+ * @param {{ getLogs: Function, getBlockNumber?: Function }} pub
+ * @param {object} params — viem getLogs params; fromBlock required; toBlock may be "latest"
+ * @param {{ chunkBlocks?: bigint }} [opts]
+ */
+export async function getLogsChunked(pub, params, opts = {}) {
+  const chunkBlocks = opts.chunkBlocks ?? LOG_CHUNK_BLOCKS;
+  let fromBlock = params.fromBlock ?? 0n;
+  if (typeof fromBlock === "number") fromBlock = BigInt(fromBlock);
+
+  let toBlock = params.toBlock ?? "latest";
+  if (toBlock === "latest") {
+    if (typeof pub.getBlockNumber !== "function") {
+      throw new Error("getLogsChunked: pub.getBlockNumber required when toBlock is latest");
+    }
+    toBlock = await pub.getBlockNumber();
+  } else if (typeof toBlock === "number") {
+    toBlock = BigInt(toBlock);
+  }
+
+  if (fromBlock > toBlock) return [];
+
+  const all = [];
+  let cursor = fromBlock;
+  while (cursor <= toBlock) {
+    const chunkEnd =
+      cursor + chunkBlocks - 1n > toBlock ? toBlock : cursor + chunkBlocks - 1n;
+    const chunk = await pub.getLogs({
+      ...params,
+      fromBlock: cursor,
+      toBlock: chunkEnd,
+    });
+    all.push(...chunk);
+    cursor = chunkEnd + 1n;
+  }
+  return all;
+}
+
+/**
+ * @param {import('viem').PublicClient} pub
+ * @param {string} registry
+ * @param {string} label
+ */
+export async function readOperator(pub, registry, label) {
+  const id = labelToId(label);
+  const [owner, registeredAt, revokedAt] = await pub.readContract({
+    address: /** @type {`0x${string}`} */ (registry),
+    abi: clankerIdentityAbi,
+    functionName: "operators",
+    args: [id],
+  });
+  return {
+    label,
+    id,
+    owner,
+    registeredAt: BigInt(registeredAt),
+    revokedAt: BigInt(revokedAt),
+    active: registeredAt > 0n && revokedAt === 0n,
+  };
+}
+
+/**
+ * Preferred-label path: storage read, no logs. Requires current owner + active.
+ *
+ * @param {import('viem').PublicClient} pub
+ * @param {{ registry: string, label: string, owner: `0x${string}` }} opts
+ */
+export async function resolvePreferredOperator(pub, opts) {
+  const op = await readOperator(pub, opts.registry, opts.label);
+  if (op.registeredAt === 0n) {
+    return {
+      error: `Operator "${opts.label}" is not registered`,
+      candidates: [],
+    };
+  }
+  if (!op.active) {
+    return {
+      error: `Operator "${opts.label}" is revoked`,
+      candidates: [],
+    };
+  }
+  const want = getAddress(opts.owner);
+  const got = getAddress(op.owner);
+  if (want !== got) {
+    return {
+      error: `Operator "${opts.label}" is owned by ${got}, not ${want}`,
+      candidates: [],
+    };
+  }
+  return { operator: op };
+}
+
+/**
+ * @param {import('viem').PublicClient} pub
+ * @param {string} registry
+ * @param {string} label
+ */
+export async function readBot(pub, registry, label) {
+  const id = labelToId(label);
+  const [operatorId, botKey, registeredAt, revokedAt] = await pub.readContract({
+    address: /** @type {`0x${string}`} */ (registry),
+    abi: clankerIdentityAbi,
+    functionName: "bots",
+    args: [id],
+  });
+  return {
+    label,
+    id,
+    operatorId,
+    botKey,
+    registeredAt: BigInt(registeredAt),
+    revokedAt: BigInt(revokedAt),
+    active: registeredAt > 0n && revokedAt === 0n,
+  };
+}
+
+/**
+ * Find operators currently owned by address (minted or transferred).
+ * @param {import('viem').PublicClient} pub
+ * @param {{ registry: string, owner: `0x${string}`, fromBlock?: bigint, chunkBlocks?: bigint }} opts
+ */
+export async function findOperatorsByOwner(pub, opts) {
+  const fromBlock = opts.fromBlock ?? 0n;
+  const chunkBlocks = opts.chunkBlocks ?? LOG_CHUNK_BLOCKS;
+  const registry = /** @type {`0x${string}`} */ (opts.registry);
+  const owner = getAddress(opts.owner);
+
+  const registeredLogs = await getLogsChunked(
+    pub,
+    {
+      address: registry,
+      event: OPERATOR_REGISTERED,
+      args: { owner },
+      fromBlock,
+      toBlock: "latest",
+    },
+    { chunkBlocks },
+  );
+
+  const transferredLogs = await getLogsChunked(
+    pub,
+    {
+      address: registry,
+      event: OPERATOR_TRANSFERRED,
+      args: { newOwner: owner },
+      fromBlock,
+      toBlock: "latest",
+    },
+    { chunkBlocks },
+  );
+
+  /** @type {Map<string, { label?: string, id: `0x${string}`, tx?: string }>} */
+  const byId = new Map();
+
+  for (const log of registeredLogs) {
+    const id = log.args.id;
+    const label = log.args.label;
+    if (!id) continue;
+    byId.set(id.toLowerCase(), {
+      id,
+      label: label ?? undefined,
+      tx: log.transactionHash,
+    });
+  }
+
+  for (const log of transferredLogs) {
+    const id = log.args.id;
+    if (!id) continue;
+    const key = id.toLowerCase();
+    if (!byId.has(key)) {
+      byId.set(key, { id, tx: log.transactionHash });
+    }
+  }
+
+  // Recover labels for transfer-only ids via OperatorRegistered filtered by id.
+  for (const entry of byId.values()) {
+    if (entry.label) continue;
+    const labelLogs = await getLogsChunked(
+      pub,
+      {
+        address: registry,
+        event: OPERATOR_REGISTERED,
+        args: { id: entry.id },
+        fromBlock,
+        toBlock: "latest",
+      },
+      { chunkBlocks },
+    );
+    const last = labelLogs[labelLogs.length - 1];
+    if (last?.args?.label) {
+      entry.label = last.args.label;
+      entry.tx = entry.tx ?? last.transactionHash;
+    }
+  }
+
+  const results = [];
+  for (const entry of byId.values()) {
+    if (!entry.label) continue;
+    const [storageOwner, registeredAt, revokedAt] = await pub.readContract({
+      address: registry,
+      abi: clankerIdentityAbi,
+      functionName: "operators",
+      args: [entry.id],
+    });
+    if (getAddress(storageOwner) !== owner) continue;
+    results.push({
+      label: entry.label,
+      id: entry.id,
+      owner: storageOwner,
+      registeredAt: BigInt(registeredAt),
+      revokedAt: BigInt(revokedAt),
+      active: registeredAt > 0n && revokedAt === 0n,
+      mintTx: entry.tx,
+    });
+  }
+  return results;
+}
+
+/**
+ * Find bots under an operator via BotRegistered logs + storage refresh.
+ * @param {import('viem').PublicClient} pub
+ * @param {{ registry: string, operatorId: `0x${string}`, fromBlock?: bigint, chunkBlocks?: bigint }} opts
+ */
+export async function findBotsByOperator(pub, opts) {
+  const fromBlock = opts.fromBlock ?? 0n;
+  const chunkBlocks = opts.chunkBlocks ?? LOG_CHUNK_BLOCKS;
+  const registry = /** @type {`0x${string}`} */ (opts.registry);
+
+  const logs = await getLogsChunked(
+    pub,
+    {
+      address: registry,
+      event: BOT_REGISTERED,
+      args: { operatorId: opts.operatorId },
+      fromBlock,
+      toBlock: "latest",
+    },
+    { chunkBlocks },
+  );
+
+  const byLabel = new Map();
+  for (const log of logs) {
+    const label = log.args.label;
+    const id = log.args.id;
+    if (!label || !id) continue;
+    byLabel.set(label, {
+      label,
+      id,
+      botKeyAtMint: log.args.botKey,
+      blockNumber: log.blockNumber,
+      tx: log.transactionHash,
+    });
+  }
+
+  const results = [];
+  for (const entry of byLabel.values()) {
+    const [operatorId, botKey, registeredAt, revokedAt] = await pub.readContract({
+      address: registry,
+      abi: clankerIdentityAbi,
+      functionName: "bots",
+      args: [entry.id],
+    });
+    results.push({
+      label: entry.label,
+      id: entry.id,
+      operatorId,
+      botKey,
+      registeredAt: BigInt(registeredAt),
+      revokedAt: BigInt(revokedAt),
+      active: registeredAt > 0n && revokedAt === 0n,
+      mintTx: entry.tx,
+    });
+  }
+  return results;
+}
+
+/**
+ * Pure helper: pick a single operator label when profile/flag/list interact.
+ * Preferred labels must be active when present in the list.
+ *
+ * @param {{ operators: Array<{label: string, active: boolean}>, preferred?: string|null }} opts
+ * @returns {{ label: string } | { error: string, candidates: string[] }}
+ */
+export function pickOperatorLabel(opts) {
+  const active = opts.operators.filter((o) => o.active);
+  if (opts.preferred) {
+    const hit = opts.operators.find((o) => o.label === opts.preferred);
+    if (!hit) {
+      return {
+        error: `Operator "${opts.preferred}" not found for this owner`,
+        candidates: opts.operators.map((o) => o.label),
+      };
+    }
+    if (!hit.active) {
+      return {
+        error: `Operator "${opts.preferred}" is revoked`,
+        candidates: active.map((o) => o.label),
+      };
+    }
+    return { label: hit.label };
+  }
+  if (active.length === 1) return { label: active[0].label };
+  if (active.length === 0) {
+    return {
+      error: "No active operators for this address. Mint one with `clanker operator mint <label>`.",
+      candidates: [],
+    };
+  }
+  return {
+    error:
+      "Multiple operators for this address; pass --operator <label> or set ~/.clanker/operator.json",
+    candidates: active.map((o) => o.label),
+  };
+}

package/lib/keys.mjs

@@ -0,0 +1,75 @@
+/**
+ * Dual-write bot keys to ~/.openclaw/keys and ~/.clanker/keys.
+ */
+
+import { existsSync, mkdirSync, symlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { clankerKeysDir, openclawKeysDir } from "./profile.mjs";
+
+/**
+ * Reject labels that are unsafe as a single path segment.
+ * @param {string} label
+ */
+export function assertSafeBotLabel(label) {
+  const s = String(label ?? "");
+  if (!s) {
+    throw new Error("Bot label must be non-empty");
+  }
+  if (s.includes("\0")) {
+    throw new Error("Bot label must not contain NUL");
+  }
+  if (s.includes("/") || s.includes("\\")) {
+    throw new Error("Bot label must not contain path separators");
+  }
+  if (s === "." || s === ".." || s.includes("..")) {
+    throw new Error('Bot label must not contain ".."');
+  }
+}
+
+/**
+ * Write bot private key before broadcasting registerBot.
+ * Primary path remains ~/.openclaw/keys for published plugins.
+ * Also writes (or symlinks) under ~/.clanker/keys (or CLANKER_KEY_DIR).
+ *
+ * @param {string} botLabel
+ * @param {string} botPrivateKey
+ * @param {{ env?: NodeJS.ProcessEnv, openclawKeysDir?: string, clankerKeysDir?: string }} [opts]
+ * @returns {{ openclawPath: string, clankerPath: string }}
+ */
+export function writeBotKeyFiles(botLabel, botPrivateKey, opts = {}) {
+  assertSafeBotLabel(botLabel);
+  const env = opts.env ?? process.env;
+  const openclawDir = opts.openclawKeysDir ?? openclawKeysDir();
+  const clankerDir = opts.clankerKeysDir ?? clankerKeysDir(env);
+
+  mkdirSync(openclawDir, { recursive: true });
+  mkdirSync(clankerDir, { recursive: true });
+
+  const openclawPath = join(openclawDir, `${botLabel}.key`);
+  const clankerPath = join(clankerDir, `${botLabel}.key`);
+
+  if (existsSync(openclawPath)) {
+    throw new Error(
+      `Key file already exists at ${openclawPath}; refusing to overwrite. ` +
+        `Remove it or choose a different bot label.`,
+    );
+  }
+  if (existsSync(clankerPath)) {
+    throw new Error(
+      `Key file already exists at ${clankerPath}; refusing to overwrite. ` +
+        `Remove it or choose a different bot label.`,
+    );
+  }
+
+  const body = `${botPrivateKey}\n`;
+  writeFileSync(openclawPath, body, { flag: "wx", mode: 0o600 });
+
+  try {
+    symlinkSync(openclawPath, clankerPath);
+  } catch {
+    // Symlink may fail on some FS; fall back to a second copy.
+    writeFileSync(clankerPath, body, { flag: "wx", mode: 0o600 });
+  }
+
+  return { openclawPath, clankerPath };
+}

package/lib/profile.mjs

@@ -0,0 +1,232 @@
+/**
+ * Local operator profile under ~/.clanker (or CLANKER_HOME).
+ * Never stores raw private keys — only key pointers.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Anvil account #0 — local-dev only. */
+export const ANVIL_DEFAULT_PRIVATE_KEY =
+  "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
+
+export const ANVIL_DEFAULT_ADDRESS = "0xf39Fd6e51aad88F6F4ce6aB8827279cffFb92266";
+
+/** Closed-beta Base Sepolia registry (see docs/public-testnet-hub.md). */
+export const SEPOLIA_REGISTRY = "0xD650467f9D7A20f37E55ec23Ca1c711598f97958";
+
+/**
+ * Safe floor for Sepolia getLogs (before registry deploy). Documented so scans
+ * stay cheap; bump only if you redeploy the registry earlier.
+ */
+export const SEPOLIA_FROM_BLOCK = 35_000_000n;
+
+export const PRESETS = {
+  local: {
+    preset: "local",
+    registryAddress: null,
+    chainRpcUrl: "http://127.0.0.1:8545",
+    brokerUrl: "mqtt://localhost:1883",
+    mqttAuthServiceUrl: "http://localhost:9090",
+    fromBlock: 0n,
+  },
+  sepolia: {
+    preset: "sepolia",
+    registryAddress: SEPOLIA_REGISTRY,
+    chainRpcUrl: "https://sepolia.base.org",
+    brokerUrl: "mqtts://mqtt.clanker-chain.com:8883",
+    mqttAuthServiceUrl: "https://mqtt-auth.clanker-chain.com",
+    fromBlock: SEPOLIA_FROM_BLOCK,
+  },
+};
+
+export function clankerHome(env = process.env) {
+  return env.CLANKER_HOME ?? join(homedir(), ".clanker");
+}
+
+export function configPath(home = clankerHome()) {
+  return join(home, "config.json");
+}
+
+export function operatorPath(home = clankerHome()) {
+  return join(home, "operator.json");
+}
+
+export function clankerKeysDir(env = process.env, home = clankerHome(env)) {
+  return env.CLANKER_KEY_DIR ?? join(home, "keys");
+}
+
+export function openclawKeysDir() {
+  return join(homedir(), ".openclaw", "keys");
+}
+
+/**
+ * @param {string} presetName
+ * @param {{ force?: boolean, registryAddress?: string|null, home?: string, fromBlock?: bigint|string|number }} [opts]
+ */
+export function initProfile(presetName, opts = {}) {
+  const name = String(presetName || "").toLowerCase();
+  if (!PRESETS[name]) {
+    throw new Error(`Unknown preset "${presetName}". Use "local" or "sepolia".`);
+  }
+  const home = opts.home ?? clankerHome();
+  const path = configPath(home);
+  if (existsSync(path) && !opts.force) {
+    throw new Error(
+      `Profile already exists at ${path}. Pass --force to overwrite, or edit the file.`,
+    );
+  }
+  mkdirSync(home, { recursive: true });
+  const preset = PRESETS[name];
+  const fromBlock =
+    opts.fromBlock != null ? BigInt(opts.fromBlock) : preset.fromBlock;
+  const config = {
+    preset: preset.preset,
+    registryAddress: opts.registryAddress ?? preset.registryAddress,
+    chainRpcUrl: preset.chainRpcUrl,
+    brokerUrl: preset.brokerUrl,
+    mqttAuthServiceUrl: preset.mqttAuthServiceUrl,
+    fromBlock: fromBlock.toString(),
+  };
+  if (name === "local" && !config.registryAddress) {
+    // Placeholder until chain deploy; operator must set after forge deploy.
+    config.registryAddress = null;
+  }
+  writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+  return { path, config };
+}
+
+/**
+ * @param {string} [home]
+ * @returns {object|null}
+ */
+export function loadConfig(home = clankerHome()) {
+  const path = configPath(home);
+  if (!existsSync(path)) return null;
+  const raw = JSON.parse(readFileSync(path, "utf8"));
+  if (raw.fromBlock != null && typeof raw.fromBlock !== "bigint") {
+    raw.fromBlock = BigInt(raw.fromBlock);
+  }
+  return raw;
+}
+
+/**
+ * @param {string} [home]
+ * @returns {object|null}
+ */
+export function loadOperator(home = clankerHome()) {
+  const path = operatorPath(home);
+  if (!existsSync(path)) return null;
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+/**
+ * Write operator profile (label + owner + optional key pointer). Never stores hex keys.
+ * Omit `key` (or pass null) for a read-only profile; mint/revoke still need a pointer later.
+ * @param {{ label: string, owner: string, key?: { type: 'env'|'keyFile', value?: string }|null }} op
+ * @param {string} [home]
+ */
+export function writeOperator(op, home = clankerHome()) {
+  mkdirSync(home, { recursive: true });
+  const path = operatorPath(home);
+  const out = {
+    label: op.label,
+    owner: op.owner,
+  };
+  if (op.key != null) {
+    out.key = op.key;
+  }
+  writeFileSync(path, `${JSON.stringify(out, null, 2)}\n`, { mode: 0o600 });
+  return { path, operator: out };
+}
+
+/**
+ * Merge profile + env + argv overrides into a network view (no key yet).
+ * Precedence: argv flags > env > profile > preset defaults for local RPC.
+ *
+ * @param {string[]} argv
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv }} [opts]
+ */
+export function resolveNetwork(argv = [], opts = {}) {
+  const env = opts.env ?? process.env;
+  const home = opts.home ?? clankerHome(env);
+  const config = loadConfig(home);
+
+  let rpc = env.CHAIN_RPC_URL ?? env.BASE_SEPOLIA_RPC_URL ?? null;
+  let registry = env.REGISTRY_ADDRESS ?? null;
+  let fromBlock = null;
+  let brokerUrl = null;
+  let mqttAuthServiceUrl = null;
+  let preset = null;
+  let keyFile = null;
+  let json = false;
+  let operatorLabel = null;
+
+  if (config) {
+    preset = config.preset ?? null;
+    rpc = rpc ?? config.chainRpcUrl ?? null;
+    registry = registry ?? config.registryAddress ?? null;
+    fromBlock = config.fromBlock != null ? BigInt(config.fromBlock) : null;
+    brokerUrl = config.brokerUrl ?? null;
+    mqttAuthServiceUrl = config.mqttAuthServiceUrl ?? null;
+  }
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--rpc" && argv[i + 1]) rpc = argv[++i];
+    else if (a === "--registry" && argv[i + 1]) registry = argv[++i];
+    else if (a === "--key-file" && argv[i + 1]) keyFile = argv[++i];
+    else if (a === "--operator" && argv[i + 1]) operatorLabel = argv[++i];
+    else if (a === "--from-block" && argv[i + 1]) fromBlock = BigInt(argv[++i]);
+    else if (a === "--json") json = true;
+  }
+
+  if (!rpc) {
+    rpc = "http://127.0.0.1:8545";
+  }
+
+  if (fromBlock == null) {
+    fromBlock = isLocalRpc(rpc) ? 0n : SEPOLIA_FROM_BLOCK;
+  }
+
+  return {
+    rpc,
+    registry,
+    fromBlock,
+    brokerUrl,
+    mqttAuthServiceUrl,
+    preset,
+    keyFile,
+    json,
+    operatorLabel,
+    config,
+    home,
+  };
+}
+
+export function isLocalRpc(rpc) {
+  if (!rpc) return false;
+  try {
+    const u = new URL(rpc);
+    const host = u.hostname.toLowerCase();
+    return host === "127.0.0.1" || host === "localhost" || host === "::1";
+  } catch {
+    return /127\.0\.0\.1|localhost/.test(rpc);
+  }
+}
+
+/**
+ * Harness snippet for OpenClaw channels.mqtt from network + ids.
+ */
+export function harnessSnippet({ botId, operatorId, network }) {
+  return {
+    enabled: true,
+    botId,
+    operatorId,
+    brokerUrl: network.brokerUrl ?? "mqtt://localhost:1883",
+    chainRpcUrl: network.rpc,
+    registryAddress: network.registry,
+    mqttAuthServiceUrl: network.mqttAuthServiceUrl ?? "http://localhost:9090",
+  };
+}