polkadot-cli 1.1.1 → 1.2.0

package/README.md

@@ -79,6 +79,10 @@ dot accounts            # shorthand, same as above
 # List all accounts (dev + stored)
 dot account list
 
+# Add a watch-only address (no secret — for use as tx recipient or query target)
+dot account add treasury 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+dot account add council 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
+
 # Create a new account (generates a mnemonic)
 dot account create my-validator
 
@@ -113,6 +117,36 @@ dot account inspect alice --prefix 0         # Polkadot mainnet prefix
 dot account inspect alice --output json      # JSON output
 ```
 
+#### Watch-only accounts
+
+Add named addresses without secrets — useful for saving frequently-used recipients, multisig members, or query targets:
+
+```bash
+dot account add treasury 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+dot account add council 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
+```
+
+Watch-only accounts appear in `dot account list` with a `(watch-only)` badge and can be inspected and removed like any other account. They cannot be used with `--from` (signing) or as a source for `derive`.
+
+The `add` subcommand is context-sensitive: bare `add <name> <address>` creates a watch-only entry, while `add --secret` or `add --env` imports a keyed account (same as `import`).
+
+#### Named address resolution
+
+Named accounts (both watch-only and keyed) resolve automatically everywhere an AccountId32 or MultiAddress is expected — in `dot tx` arguments and `dot query` keys:
+
+```bash
+# Use a named account as transfer recipient
+dot tx Balances.transferKeepAlive treasury 1000000000000 --from alice
+
+# Query by account name
+dot query System.Account treasury
+
+# Dev accounts also resolve
+dot tx Balances.transferKeepAlive bob 1000000000000 --from alice
+```
+
+Resolution order: dev account name > stored account name > SS58 address > hex public key. If the input doesn't match any, the CLI shows an error listing available account names.
+
 #### Inspect accounts
 
 Convert between SS58 addresses, hex public keys, and account names. Accepts any of:

package/dist/cli.mjs

@@ -5,7 +5,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.1.1";
+var version = "1.2.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -238,6 +238,9 @@ function findAccount(file, name) {
 function isEnvSecret(secret) {
   return typeof secret === "object" && secret !== null && "env" in secret;
 }
+function isWatchOnly(account) {
+  return account.secret === undefined;
+}
 
 // src/core/accounts.ts
 import { sr25519CreateDerive } from "@polkadot-labs/hdkd";
@@ -354,6 +357,9 @@ async function resolveAccountSigner(name) {
     const available = [...DEV_NAMES, ...accountsFile.accounts.map((a) => a.name)];
     throw new Error(`Unknown account "${name}". Available accounts: ${available.join(", ")}`);
   }
+  if (account.secret === undefined) {
+    throw new Error(`Account "${name}" is watch-only (no secret). Cannot sign. Import with --secret or --env.`);
+  }
   const secret = resolveSecret(account.secret);
   const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(secret);
   const keypair = isHexSeed ? deriveFromHexSeed(secret, account.derivationPath) : deriveFromMnemonic(secret, account.derivationPath);
@@ -463,15 +469,19 @@ function firstSentence(docs) {
 // src/commands/account.ts
 var ACCOUNT_HELP = `
 ${BOLD}Usage:${RESET}
+  $ dot account add <name> <ss58|hex>                                Add a watch-only address (no secret)
+  $ dot account add <name> --secret <s> [--path <derivation>]        Import from BIP39 mnemonic
+  $ dot account add <name> --env <VAR> [--path <derivation>]         Import account backed by env variable
   $ dot account create|new <name> [--path <derivation>]              Create a new account
-  $ dot account import|add <name> --secret <s> [--path <derivation>] Import from BIP39 mnemonic
-  $ dot account import|add <name> --env <VAR> [--path <derivation>]  Import account backed by env variable
+  $ dot account import <name> --secret <s> [--path <derivation>]     Import from BIP39 mnemonic
+  $ dot account import <name> --env <VAR> [--path <derivation>]      Import account backed by env variable
   $ dot account derive <source> <new-name> --path <derivation>       Derive a child account
   $ dot account inspect <input> [--prefix <N>]                       Inspect an account/address/key
   $ dot account list                                                 List all accounts
   $ dot account remove|delete <name> [name2] ...                     Remove stored account(s)
 
 ${BOLD}Examples:${RESET}
+  $ dot account add treasury 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
   $ dot account create my-validator
   $ dot account create my-staking --path //staking
   $ dot account create multi --path //polkadot//0/wallet
@@ -500,8 +510,11 @@ function registerAccountCommands(cli) {
       case "new":
       case "create":
         return accountCreate(names[0], opts);
-      case "import":
       case "add":
+        if (opts.secret || opts.env)
+          return accountImport(names[0], opts);
+        return accountAddWatchOnly(names[0], names[1]);
+      case "import":
         return accountImport(names[0], opts);
       case "derive":
         return accountDerive(names[0], names[1], opts);
@@ -618,6 +631,48 @@ async function accountImport(name, opts) {
     console.log();
   }
 }
+async function accountAddWatchOnly(name, address) {
+  if (!name) {
+    console.error(`Account name is required.
+`);
+    console.error("Usage: dot account add <name> <ss58-address|0x-public-key>");
+    process.exit(1);
+  }
+  if (!address) {
+    console.error(`Address is required.
+`);
+    console.error("Usage: dot account add <name> <ss58-address|0x-public-key>");
+    process.exit(1);
+  }
+  if (isDevAccount(name)) {
+    throw new Error(`"${name}" is a built-in dev account and cannot be used as a custom account name.`);
+  }
+  const accountsFile = await loadAccounts();
+  if (findAccount(accountsFile, name)) {
+    throw new Error(`Account "${name}" already exists.`);
+  }
+  let hexPub;
+  if (isHexPublicKey(address)) {
+    hexPub = address;
+  } else {
+    try {
+      const decoded = fromSs58(address);
+      hexPub = publicKeyToHex(decoded);
+    } catch {
+      throw new Error(`Invalid address "${address}". Expected an SS58 address or 0x-prefixed 32-byte hex public key.`);
+    }
+  }
+  accountsFile.accounts.push({
+    name,
+    publicKey: hexPub,
+    derivationPath: ""
+  });
+  await saveAccounts(accountsFile);
+  printHeading("Account Added (watch-only)");
+  console.log(`  ${BOLD}Name:${RESET}    ${name}`);
+  console.log(`  ${BOLD}Address:${RESET} ${toSs58(hexPub)}`);
+  console.log();
+}
 async function accountDerive(sourceName, newName, opts) {
   if (!sourceName) {
     console.error(`Source account name is required.
@@ -645,15 +700,19 @@ async function accountDerive(sourceName, newName, opts) {
   if (!source) {
     throw new Error(`Source account "${sourceName}" not found.`);
   }
+  if (isWatchOnly(source)) {
+    throw new Error(`Cannot derive from "${sourceName}": watch-only, no secret.`);
+  }
   if (findAccount(accountsFile, newName)) {
     throw new Error(`Account "${newName}" already exists.`);
   }
   const path = opts.path;
-  if (isEnvSecret(source.secret)) {
-    const publicKey = tryDerivePublicKey(source.secret.env, path) ?? "";
+  const sourceSecret = source.secret;
+  if (isEnvSecret(sourceSecret)) {
+    const publicKey = tryDerivePublicKey(sourceSecret.env, path) ?? "";
     accountsFile.accounts.push({
       name: newName,
-      secret: source.secret,
+      secret: sourceSecret,
       publicKey,
       derivationPath: path
     });
@@ -662,20 +721,20 @@ async function accountDerive(sourceName, newName, opts) {
     console.log(`  ${BOLD}Name:${RESET}    ${newName}`);
     console.log(`  ${BOLD}Source:${RESET}  ${sourceName}`);
     console.log(`  ${BOLD}Path:${RESET}    ${path}`);
-    console.log(`  ${BOLD}Env:${RESET}     ${source.secret.env}`);
+    console.log(`  ${BOLD}Env:${RESET}     ${sourceSecret.env}`);
     if (publicKey) {
       console.log(`  ${BOLD}Address:${RESET} ${toSs58(publicKey)}`);
     } else {
-      console.log(`  ${YELLOW}Address will resolve when $${source.secret.env} is set.${RESET}`);
+      console.log(`  ${YELLOW}Address will resolve when $${sourceSecret.env} is set.${RESET}`);
     }
     console.log();
   } else {
-    const { publicKey } = importAccount(source.secret, path);
+    const { publicKey } = importAccount(sourceSecret, path);
     const hexPub = publicKeyToHex(publicKey);
     const address = toSs58(publicKey);
     accountsFile.accounts.push({
       name: newName,
-      secret: source.secret,
+      secret: sourceSecret,
       publicKey: hexPub,
       derivationPath: path
     });
@@ -704,7 +763,10 @@ async function accountList() {
         displayName += ` (${account.derivationPath})`;
       }
       let address;
-      if (isEnvSecret(account.secret)) {
+      if (isWatchOnly(account)) {
+        displayName += " (watch-only)";
+        address = account.publicKey ? toSs58(account.publicKey) : "n/a";
+      } else if (account.secret !== undefined && isEnvSecret(account.secret)) {
         displayName += ` (env: ${account.secret.env})`;
         let pubKey = account.publicKey;
         if (!pubKey) {
@@ -786,7 +848,7 @@ async function accountInspect(input, opts) {
       name = account.name;
       if (account.publicKey) {
         publicKeyHex = account.publicKey;
-      } else if (isEnvSecret(account.secret)) {
+      } else if (account.secret !== undefined && isEnvSecret(account.secret)) {
         const derived = tryDerivePublicKey(account.secret.env, account.derivationPath);
         if (!derived) {
           console.error(`Cannot derive public key for "${account.name}": $${account.secret.env} is not set.`);
@@ -2564,8 +2626,35 @@ import { Binary as Binary2 } from "polkadot-api";
 var pjsAppsLink = (rpc, hash) => `https://polkadot.js.org/apps/?rpc=${encodeURIComponent(rpc)}#/explorer/query/${hash}`;
 var papiLink = (rpc, hash) => `https://dev.papi.how/explorer/${hash}#networkId=custom&endpoint=${encodeURIComponent(rpc)}`;
 
+// src/core/resolve-address.ts
+async function resolveAccountAddress(input) {
+  if (isDevAccount(input)) {
+    return getDevAddress(input);
+  }
+  const accountsFile = await loadAccounts();
+  const account = findAccount(accountsFile, input);
+  if (account) {
+    if (account.publicKey) {
+      return toSs58(account.publicKey);
+    }
+    throw new Error(`Account "${account.name}" has no public key resolved yet.`);
+  }
+  try {
+    const decoded = fromSs58(input);
+    publicKeyToHex(decoded);
+    return input;
+  } catch {}
+  if (isHexPublicKey(input)) {
+    return input;
+  }
+  const stored = accountsFile.accounts.map((a) => a.name);
+  const available = [...DEV_NAMES, ...stored];
+  throw new Error(`Unknown account or address "${input}".
+  Available accounts: ${available.join(", ")}`);
+}
+
 // src/commands/tx.ts
-function parseStructArgs(meta, fields, args, callLabel) {
+async function parseStructArgs(meta, fields, args, callLabel) {
   const fieldNames = Object.keys(fields);
   if (args.length !== fieldNames.length) {
     const expected = fieldNames.map((name) => `${name}: ${describeType(meta.lookup, fields[name].id)}`).join(", ");
@@ -2577,7 +2666,7 @@ function parseStructArgs(meta, fields, args, callLabel) {
     const name = fieldNames[i];
     const entry = fields[name];
     try {
-      result[name] = parseTypedArg(meta, entry, args[i]);
+      result[name] = await parseTypedArg(meta, entry, args[i]);
     } catch (err) {
       const typeDesc = describeType(meta.lookup, entry.id);
       throw new Error(`Invalid value for argument '${name}' (expected ${typeDesc}): ${JSON.stringify(args[i])}
@@ -2723,7 +2812,7 @@ function parseEnumShorthand(arg) {
     return null;
   return { variant, inner: arg.slice(firstParen + 1, -1) };
 }
-function parseTypedArg(meta, entry, arg) {
+async function parseTypedArg(meta, entry, arg) {
   if (entry.type === "lookupEntry")
     return parseTypedArg(meta, entry.value, arg);
   switch (entry.type) {
@@ -2732,6 +2821,7 @@ function parseTypedArg(meta, entry, arg) {
     case "compact":
       return entry.isBig ? BigInt(arg) : parseInt(arg, 10);
     case "AccountId32":
+      return resolveAccountAddress(arg);
     case "AccountId20":
       return arg;
     case "option": {
@@ -2760,7 +2850,7 @@ function parseTypedArg(meta, entry, arg) {
           if (resolvedDef.type === "void" || shorthand.inner === "") {
             return { type: matched2 };
           }
-          const innerValue = parseTypedArg(meta, variantDef, shorthand.inner);
+          const innerValue = await parseTypedArg(meta, variantDef, shorthand.inner);
           return normalizeValue(meta.lookup, entry, { type: matched2, value: innerValue });
         }
       }
@@ -2768,7 +2858,8 @@ function parseTypedArg(meta, entry, arg) {
         const idVariant = entry.value.Id;
         const innerType = idVariant.type === "lookupEntry" ? idVariant.value : idVariant;
         if (innerType.type === "AccountId32" && !arg.startsWith("{")) {
-          return { type: "Id", value: arg };
+          const resolved = await resolveAccountAddress(arg);
+          return { type: "Id", value: resolved };
         }
       }
       const matched = variants.find((v) => v.toLowerCase() === arg.toLowerCase());
@@ -2919,7 +3010,7 @@ async function handleQuery(target, keys, opts) {
     }
     const unsafeApi = clientHandle.client.getUnsafeApi();
     const storageApi = unsafeApi.query[palletInfo.name][storageItem.name];
-    const parsedKeys = parseStorageKeys(meta, palletInfo.name, storageItem, keys);
+    const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, keys);
     const format = opts.output ?? "pretty";
     if (storageItem.type === "map" && parsedKeys.length === 0) {
       const entries = await storageApi.getEntries();
@@ -2945,7 +3036,7 @@ ${DIM}Showing ${limit} of ${entries.length} entries. Use --limit 0 for all.${RES
 function palletName(name) {
   return name;
 }
-function parseStorageKeys(meta, palletName2, storageItem, args) {
+async function parseStorageKeys(meta, palletName2, storageItem, args) {
   if (storageItem.type === "plain" || storageItem.keyTypeId == null) {
     return args.map(parseValue);
   }
@@ -2956,11 +3047,11 @@ function parseStorageKeys(meta, palletName2, storageItem, args) {
   const keyEntry = meta.lookup(storageItem.keyTypeId);
   if (len === 1) {
     if (args.length === 1) {
-      return [parseTypedArg(meta, keyEntry, args[0])];
+      return [await parseTypedArg(meta, keyEntry, args[0])];
     }
     if (keyEntry.type === "struct") {
       const label = `${palletName2}.${storageItem.name} key`;
-      return [parseStructArgs(meta, keyEntry.value, args, label)];
+      return [await parseStructArgs(meta, keyEntry.value, args, label)];
     }
     const typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
     throw new Error(`${palletName2}.${storageItem.name} key expects ${typeDesc}
@@ -2977,9 +3068,9 @@ function parseStorageKeys(meta, palletName2, storageItem, args) {
   }
   if (keyEntry.type === "tuple") {
     const entries = keyEntry.value;
-    return entries.map((entry, i) => parseTypedArg(meta, entry, args[i]));
+    return Promise.all(entries.map((entry, i) => parseTypedArg(meta, entry, args[i])));
   }
-  return args.map((arg) => parseTypedArg(meta, keyEntry, arg));
+  return Promise.all(args.map((arg) => parseTypedArg(meta, keyEntry, arg)));
 }
 
 // src/commands/tx.ts
@@ -3090,7 +3181,7 @@ async function handleTx(target, args, opts) {
         const callNames = palletInfo.calls.map((c) => c.name);
         throw new Error(suggestMessage(`call in ${palletInfo.name}`, callName, callNames));
       }
-      const callData = parseCallArgs(meta, palletInfo.name, callInfo.name, args);
+      const callData = await parseCallArgs(meta, palletInfo.name, callInfo.name, args);
       if (opts.encode) {
         const { codec, location } = meta.builder.buildCall(palletInfo.name, callInfo.name);
         const encodedArgs = codec.enc(callData);
@@ -3339,7 +3430,7 @@ function formatEventValue(v) {
   }
   return JSON.stringify(v, (_k, val) => typeof val === "bigint" ? val.toString() : val);
 }
-function parseCallArgs(meta, palletName2, callName, args) {
+async function parseCallArgs(meta, palletName2, callName, args) {
   const palletMeta = meta.unified.pallets.find((p) => p.name === palletName2);
   if (!palletMeta?.calls)
     return;
@@ -3356,12 +3447,12 @@ function parseCallArgs(meta, palletName2, callName, args) {
     return;
   }
   if (variant.type === "struct") {
-    return parseStructArgs2(meta, variant.value, args, `${palletName2}.${callName}`);
+    return await parseStructArgs2(meta, variant.value, args, `${palletName2}.${callName}`);
   }
   if (variant.type === "lookupEntry") {
     const inner = variant.value;
     if (inner.type === "struct") {
-      return parseStructArgs2(meta, inner.value, args, `${palletName2}.${callName}`);
+      return await parseStructArgs2(meta, inner.value, args, `${palletName2}.${callName}`);
     }
     if (inner.type === "void")
       return;
@@ -3369,7 +3460,7 @@ function parseCallArgs(meta, palletName2, callName, args) {
       throw new Error(`${palletName2}.${callName} takes 1 argument (${describeType(meta.lookup, inner.id)}), but ${args.length} provided.`);
     }
     try {
-      return parseTypedArg2(meta, inner, args[0]);
+      return await parseTypedArg2(meta, inner, args[0]);
     } catch (err) {
       const typeDesc = describeType(meta.lookup, inner.id);
       throw new Error(`Invalid value for argument 0 (expected ${typeDesc}): ${JSON.stringify(args[0])}`, { cause: err });
@@ -3380,18 +3471,18 @@ function parseCallArgs(meta, palletName2, callName, args) {
     if (args.length !== entries.length) {
       throw new Error(`${palletName2}.${callName} takes ${entries.length} arguments, but ${args.length} provided.`);
     }
-    return entries.map((entry, i) => {
+    return Promise.all(entries.map(async (entry, i) => {
       try {
-        return parseTypedArg2(meta, entry, args[i]);
+        return await parseTypedArg2(meta, entry, args[i]);
       } catch (err) {
         const typeDesc = describeType(meta.lookup, entry.id);
         throw new Error(`Invalid value for argument ${i} (expected ${typeDesc}): ${JSON.stringify(args[i])}`, { cause: err });
       }
-    });
+    }));
   }
   return args.length === 0 ? undefined : args.map(parseValue);
 }
-function parseStructArgs2(meta, fields, args, callLabel) {
+async function parseStructArgs2(meta, fields, args, callLabel) {
   const fieldNames = Object.keys(fields);
   if (args.length !== fieldNames.length) {
     const expected = fieldNames.map((name) => `${name}: ${describeType(meta.lookup, fields[name].id)}`).join(", ");
@@ -3403,7 +3494,7 @@ function parseStructArgs2(meta, fields, args, callLabel) {
     const name = fieldNames[i];
     const entry = fields[name];
     try {
-      result[name] = parseTypedArg2(meta, entry, args[i]);
+      result[name] = await parseTypedArg2(meta, entry, args[i]);
     } catch (err) {
       const typeDesc = describeType(meta.lookup, entry.id);
       throw new Error(`Invalid value for argument '${name}' (expected ${typeDesc}): ${JSON.stringify(args[i])}
@@ -3549,7 +3640,7 @@ function parseEnumShorthand2(arg) {
     return null;
   return { variant, inner: arg.slice(firstParen + 1, -1) };
 }
-function parseTypedArg2(meta, entry, arg) {
+async function parseTypedArg2(meta, entry, arg) {
   if (entry.type === "lookupEntry")
     return parseTypedArg2(meta, entry.value, arg);
   switch (entry.type) {
@@ -3558,6 +3649,7 @@ function parseTypedArg2(meta, entry, arg) {
     case "compact":
       return entry.isBig ? BigInt(arg) : parseInt(arg, 10);
     case "AccountId32":
+      return resolveAccountAddress(arg);
     case "AccountId20":
       return arg;
     case "option": {
@@ -3586,7 +3678,7 @@ function parseTypedArg2(meta, entry, arg) {
           if (resolvedDef.type === "void" || shorthand.inner === "") {
             return { type: matched2 };
           }
-          const innerValue = parseTypedArg2(meta, variantDef, shorthand.inner);
+          const innerValue = await parseTypedArg2(meta, variantDef, shorthand.inner);
           return normalizeValue2(meta.lookup, entry, { type: matched2, value: innerValue });
         }
       }
@@ -3594,7 +3686,8 @@ function parseTypedArg2(meta, entry, arg) {
         const idVariant = entry.value.Id;
         const innerType = idVariant.type === "lookupEntry" ? idVariant.value : idVariant;
         if (innerType.type === "AccountId32" && !arg.startsWith("{")) {
-          return { type: "Id", value: arg };
+          const resolved = await resolveAccountAddress(arg);
+          return { type: "Id", value: resolved };
         }
       }
       const matched = variants.find((v) => v.toLowerCase() === arg.toLowerCase());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polkadot-cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {