@clanker-chain/clanker-cli 2026.9.12 → 2026.9.13

package/bin/chain-identity.mjs

@@ -3,41 +3,14 @@
  * On-chain identity commands (ClankerIdentity contract).
  */
 
-import {
-  createPublicClient,
-  createWalletClient,
-  defineChain,
-  http,
-} from "viem";
 import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
 import { clankerIdentityAbi } from "../lib/clanker-identity-abi.mjs";
 import { assertSafeBotLabel, writeBotKeyFiles } from "../lib/keys.mjs";
 import { harnessSnippet, writeOperator } from "../lib/profile.mjs";
 import { labelToId } from "../lib/identity-query.mjs";
+import { resolveOperatorSigner } from "../lib/operator-signer.mjs";
 import { resolveOperatorKey } from "../lib/resolve.mjs";
 
-async function chainFromRpc(rpc) {
-  const publicClient = createPublicClient({ transport: http(rpc) });
-  const id = await publicClient.getChainId();
-  return defineChain({
-    id,
-    name: `clanker-chain-${id}`,
-    nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
-    rpcUrls: { default: { http: [rpc] } },
-  });
-}
-
-async function walletFromKey(rpc, key) {
-  const account = privateKeyToAccount(key);
-  const transport = http(rpc);
-  const chain = await chainFromRpc(rpc);
-  return {
-    account,
-    public: createPublicClient({ chain, transport }),
-    wallet: createWalletClient({ account, chain, transport }),
-  };
-}
-
 async function waitOk(pub, hash) {
   const receipt = await pub.waitForTransactionReceipt({ hash });
   if (receipt.status !== "success") {
@@ -48,6 +21,7 @@ async function waitOk(pub, hash) {
 
 /**
  * Shared resolve for mutating chain commands (Anvil-guarded).
+ * Prefer resolveOperatorSigner for Privy + local.
  * @param {string[]} argv
  */
 export function resolveForWrite(argv) {
@@ -55,15 +29,15 @@ export function resolveForWrite(argv) {
 }
 
 export async function chainMintOperator(label, argv, opts = {}) {
-  const { key, address, network, keyPointer } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const operatorFee = await pub.readContract({
-    address: network.registry,
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "operatorFee",
   });
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "registerOperator",
     args: [label],
@@ -72,23 +46,27 @@ export async function chainMintOperator(label, argv, opts = {}) {
   await waitOk(pub, hash);
 
   writeOperator(
-    { label, owner: address, key: opts.keyPointer ?? keyPointer },
-    opts.home ?? network.home,
+    {
+      label,
+      owner: signer.address,
+      key: opts.keyPointer ?? signer.keyPointer,
+    },
+    opts.home ?? signer.network.home,
   );
 
   return {
     ok: true,
     label,
     operator_id: labelToId(label),
-    owner: address,
+    owner: signer.address,
     tx: hash,
   };
 }
 
 export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
   assertSafeBotLabel(botLabel);
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   let botPrivateKey;
   for (let i = 0; i < argv.length; i += 1) {
     const a = argv[i];
@@ -114,12 +92,12 @@ export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
   );
 
   const botFee = await pub.readContract({
-    address: network.registry,
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "botFee",
   });
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "registerBot",
     args: [operatorIdBytes, botLabel, botAccount.address],
@@ -130,7 +108,7 @@ export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
   const channelsMqtt = harnessSnippet({
     botId: botLabel,
     operatorId: operatorLabel,
-    network,
+    network: signer.network,
   });
 
   return {
@@ -146,11 +124,11 @@ export async function chainMintBot(botLabel, operatorLabel, argv, opts = {}) {
 }
 
 export async function chainRotateBotKey(botLabel, newKey, argv, opts = {}) {
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const botIdBytes = labelToId(botLabel);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "rotateBotKey",
     args: [botIdBytes, newKey],
@@ -160,11 +138,11 @@ export async function chainRotateBotKey(botLabel, newKey, argv, opts = {}) {
 }
 
 export async function chainRevokeBot(botLabel, argv, opts = {}) {
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const botIdBytes = labelToId(botLabel);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "revokeBot",
     args: [botIdBytes],
@@ -174,11 +152,11 @@ export async function chainRevokeBot(botLabel, argv, opts = {}) {
 }
 
 export async function chainProposeOperatorTransfer(label, newOwner, argv, opts = {}) {
-  const { key, network } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const id = labelToId(label);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "proposeOperatorTransfer",
     args: [id, newOwner],
@@ -188,11 +166,11 @@ export async function chainProposeOperatorTransfer(label, newOwner, argv, opts =
 }
 
 export async function chainAcceptOperatorTransfer(label, argv, opts = {}) {
-  const { key, address, network, keyPointer } = resolveOperatorKey(argv, opts);
-  const { public: pub, wallet } = await walletFromKey(network.rpc, key);
+  const signer = await resolveOperatorSigner(argv, opts);
+  const pub = signer.publicClient;
   const id = labelToId(label);
-  const hash = await wallet.writeContract({
-    address: network.registry,
+  const hash = await signer.writeContract({
+    address: signer.network.registry,
     abi: clankerIdentityAbi,
     functionName: "acceptOperatorTransfer",
     args: [id],
@@ -201,12 +179,12 @@ export async function chainAcceptOperatorTransfer(label, argv, opts = {}) {
   writeOperator(
     {
       label,
-      owner: address,
-      key: opts.keyPointer ?? keyPointer,
+      owner: signer.address,
+      key: opts.keyPointer ?? signer.keyPointer,
     },
-    opts.home ?? network.home,
+    opts.home ?? signer.network.home,
   );
-  return { ok: true, label, owner: address, tx: hash };
+  return { ok: true, label, owner: signer.address, tx: hash };
 }
 
 export { labelToId };

package/bin/clanker.mjs

@@ -24,9 +24,11 @@ import {
   resolvePreferredOperator,
 } from "../lib/identity-query.mjs";
 import { resolveForRead, resolveOperatorKey, resolveReadIdentity } from "../lib/resolve.mjs";
+import { resolveOperatorSigner } from "../lib/operator-signer.mjs";
 import { runSetup } from "../lib/setup.mjs";
 import { runDoctor } from "../lib/doctor.mjs";
 import { runFund } from "../lib/fund.mjs";
+import { runLogin, runLogout } from "../lib/login.mjs";
 import {
   assessMintBudget,
   formatEthTrim,
@@ -170,8 +172,10 @@ function usage() {
   console.log(`clanker - clanker-chain helper CLI
 
 Usage:
-  clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--key-file path] [--force]
-  clanker fund [--no-open] [--timeout ms] [--json]
+  clanker setup [--preset sepolia|local] [--operator <label>] [--address 0x…] [--skip-key] [--bot-key path] [--key-file path] [--force]
+  clanker login [--no-open] [--operator <label>] [--json]
+  clanker logout [--json]
+  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]
@@ -197,7 +201,7 @@ 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 fund\` / \`doctor\` / \`whoami\`.
+Humans: \`clanker login\` (email vault) or \`clanker setup --generate-key\`, then \`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\`).
@@ -415,7 +419,8 @@ async function main() {
         error: err.message,
         because: "setup could not write a valid local profile",
         try: [
-          "clanker setup --preset sepolia --operator org.you --address 0x… --yes --force",
+          "clanker login",
+          "clanker setup --preset sepolia --operator org.you --yes --force",
           "clanker fund",
           "clanker doctor",
         ],
@@ -424,6 +429,36 @@ async function main() {
     return;
   }
 
+  if (cmd === "login") {
+    try {
+      const { exitCode } = await runLogin(rest);
+      process.exit(exitCode);
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "login needs Privy CLI access enabled and /authorize approval",
+        try: [
+          "Open the printed URL and Approve",
+          "Privy dashboard: Enable CLI and agent access → Verification URI https://clanker-chain.com/authorize",
+          "clanker setup --generate-key   # local key door instead",
+        ],
+      });
+    }
+  }
+
+  if (cmd === "logout") {
+    try {
+      const { exitCode } = await runLogout(rest);
+      process.exit(exitCode);
+    } catch (err) {
+      exitCliError({
+        error: err.message,
+        because: "logout could not clear the Privy session",
+        try: ["clanker logout"],
+      });
+    }
+  }
+
   if (cmd === "fund") {
     try {
       const { exitCode } = await runFund(rest);
@@ -581,21 +616,21 @@ async function main() {
       let planRows;
       let preview;
       try {
-        preview = resolveOperatorKey(flags);
+        preview = await resolveOperatorSigner(flags);
         planRows = [
           ["action", "registerOperator"],
           ["label", label],
           ["owner", preview.address],
           ["rpc", preview.network.rpc],
           ["registry", preview.network.registry ?? "(none)"],
-          ["key", preview.source],
+          ["signer", preview.source],
         ];
       } catch (err) {
         exitCliError({
           error: err.message,
-          because: "operator mint needs a signing key on this network",
+          because: "operator mint needs a signer on this network",
           try: [
-            "export OPERATOR_PRIVATE_KEY=0x…",
+            "clanker login",
             "clanker operator mint " + label + " --key-file ~/.clanker/op.key --yes",
             "clanker fund",
             "clanker doctor",
@@ -736,14 +771,15 @@ async function main() {
       let preview = null;
       if (!operatorLabel) {
         try {
-          preview = resolveOperatorKey(flags);
+          preview = await resolveOperatorSigner(flags);
           const inferred = await resolveOperatorLabel(flags, preview.address, preview.network);
           operatorLabel = inferred.label;
         } catch (err) {
           exitCliError({
             error: err.message,
-            because: "bot mint needs an operator label or a resolvable signing key",
+            because: "bot mint needs an operator label or a resolvable signer",
             try: [
+              "clanker login",
               `clanker bot mint ${botLabel} <operator_label> --yes`,
               "clanker setup",
             ],
@@ -752,12 +788,13 @@ async function main() {
       }
       if (!preview) {
         try {
-          preview = resolveOperatorKey(flags);
+          preview = await resolveOperatorSigner(flags);
         } catch (err) {
           exitCliError({
             error: err.message,
-            because: "bot mint needs a signing key on this network",
+            because: "bot mint needs a signer on this network",
             try: [
+              "clanker login",
               `clanker bot mint ${botLabel} ${operatorLabel} --key-file ~/.clanker/op.key --yes`,
               "clanker fund",
             ],
@@ -770,6 +807,7 @@ async function main() {
         ["operator", operatorLabel],
         ["owner", preview.address],
         ["registry", preview.network.registry ?? "(none)"],
+        ["signer", preview.source],
       ];
       try {
         if (preview.network.registry) {

package/lib/doctor.mjs

@@ -12,6 +12,7 @@ import {
 } from "./profile.mjs";
 import { detectSetupHints, formatSetupDetectTable } from "./setup-detect.mjs";
 import { publicClientFromRpc } from "./identity-query.mjs";
+import { loadPrivySession } from "./privy-session.mjs";
 import {
   assessMintBudget,
   budgetToJson,
@@ -96,17 +97,24 @@ export async function runDoctorChecks(opts = {}) {
     });
   }
 
+  const privySession = loadPrivySession(home);
+  const hasPrivy =
+    Boolean(operator?.key?.type === "privy" && operator.key.value) ||
+    Boolean(privySession?.accessToken && privySession?.walletId);
   const hasKey =
     Boolean(operator?.key?.type === "keyFile" && operator.key.value) ||
     Boolean(operator?.key?.type === "env" && operator.key.value) ||
-    Boolean(env.OPERATOR_PRIVATE_KEY);
+    Boolean(env.OPERATOR_PRIVATE_KEY) ||
+    hasPrivy;
   checks.push({
     id: "signing",
     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",
+    message: hasPrivy
+      ? "Privy session available (mint/pair/rotate via email vault)"
+      : hasKey
+        ? "signing key pointer available (mint/pair/rotate OK)"
+        : "read-only profile — whoami/bots/fund OK; mint/pair/rotate need clanker login or a key pointer",
   });
 
   checks.push({
@@ -293,17 +301,22 @@ export async function runDoctor(argv = [], opts = {}) {
   } 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 clanker login or a signing key (non-Anvil owner on public RPC)",
+      ),
+    );
   }
 
   if (!report.readyWhoami) {
-    nextHint(["clanker setup"]);
+    nextHint(["clanker setup", "clanker login"]);
   } else if (report.budget && !report.budget.funded && !report.budget.local) {
     nextHint(["clanker fund", "clanker doctor"]);
   } else if (!report.readyMint) {
     nextHint([
+      "clanker login",
       "clanker whoami",
-      "clanker setup --key-file ~/.clanker/op.key --force   # to enable mint",
+      "mint/pair/rotate need login or --key-file",
     ]);
   } else {
     nextHint(["clanker whoami", "clanker bots"]);

package/lib/fund.mjs

@@ -4,7 +4,13 @@
 
 import { spawn } from "node:child_process";
 import { getAddress } from "viem";
-import { clankerHome, loadConfig, loadOperator, isLocalRpc } from "./profile.mjs";
+import {
+  clankerHome,
+  loadConfig,
+  loadOperator,
+  isLocalRpc,
+  PRESETS,
+} from "./profile.mjs";
 import { publicClientFromRpc } from "./identity-query.mjs";
 import {
   assessMintBudget,
@@ -53,10 +59,12 @@ export function parseFundFlags(argv) {
   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]) {
@@ -69,7 +77,29 @@ export function parseFundFlags(argv) {
   if (!Number.isFinite(pollMs) || pollMs < 100) {
     throw new Error("--poll must be >= 100 (ms)");
   }
-  return { timeoutMs, pollMs, noOpen, json };
+  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",
+  ];
 }
 
 /**
@@ -94,16 +124,31 @@ export async function runFund(argv = [], opts = {}) {
   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 sepolia = PRESETS.sepolia;
+  let owner;
+  let rpc;
+  let registry;
+  let label = operator?.label ?? null;
 
-  const rpc = config.chainRpcUrl ?? "";
-  const registry = config.registryAddress;
-  const owner = getAddress(operator.owner);
+  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 = {
@@ -138,7 +183,7 @@ export async function runFund(argv = [], opts = {}) {
       registry,
       owner,
       rpc,
-      operatorLabel: operator.label,
+      operatorLabel: label,
     });
 
   let budget = await assess();
@@ -154,7 +199,7 @@ export async function runFund(argv = [], opts = {}) {
     console.log(c.bold("clanker fund"));
     console.log("");
     console.log(`owner:    ${owner}`);
-    console.log(`label:    ${operator.label ?? "(none)"}`);
+    console.log(`label:    ${label ?? "(none)"}`);
     console.log(`registry: ${registry}`);
     console.log(`budget:   ${formatBudgetSummary(budget)}`);
     console.log(`faucet:   ${budget.faucetUrl}`);
@@ -165,11 +210,7 @@ export async function runFund(argv = [], opts = {}) {
   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",
-      ]);
+      nextHint(fundNextHints({ operator, canSign: Boolean(operator?.key) }));
     }
     return { exitCode: 0, funded: true, budget };
   }
@@ -218,11 +259,7 @@ export async function runFund(argv = [], opts = {}) {
       } 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",
-        ]);
+        nextHint(fundNextHints({ operator, canSign: Boolean(operator?.key) }));
       }
       return { exitCode: 0, funded: true, budget };
     }
@@ -243,7 +280,7 @@ export async function runFund(argv = [], opts = {}) {
     nextHint([
       `Open ${budget.faucetUrl} and claim again`,
       `Backup: ${budget.backupFaucetUrl}`,
-      "clanker fund",
+      flags.address ? `clanker fund --address ${owner}` : "clanker fund",
     ]);
   }
   return { exitCode: 1, funded: false, budget, timedOut: true };