polkadot-cli 0.12.0 → 0.13.0

package/README.md

@@ -103,6 +103,45 @@ MY_SECRET="word1 word2 ..." dot tx System.remark 0xdead --from ci-signer
 # Remove one or more accounts
 dot account remove my-validator
 dot account delete my-validator stale-key
+
+# Inspect an account — show public key and SS58 address
+dot account inspect alice
+dot account alice                    # shorthand (same as inspect)
+dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
+dot account inspect alice --prefix 0         # Polkadot mainnet prefix
+dot account inspect alice --output json      # JSON output
+```
+
+#### Inspect accounts
+
+Convert between SS58 addresses, hex public keys, and account names. Accepts any of:
+
+- **Dev account name** (`alice`, `bob`, etc.) — resolves to public key and SS58
+- **Stored account name** — looks up the public key from the accounts file
+- **SS58 address** — decodes to the underlying public key
+- **Hex public key** (`0x` + 64 hex chars) — encodes to SS58
+
+```bash
+dot account inspect alice
+dot account alice                    # shorthand — unknown subcommands fall through to inspect
+
+dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+dot account inspect 0xd43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d
+```
+
+Use `--prefix` to encode the SS58 address with a specific network prefix (default: 42):
+
+```bash
+dot account inspect alice --prefix 0     # Polkadot mainnet (prefix 0, starts with '1')
+dot account inspect alice --prefix 2     # Kusama (prefix 2)
+```
+
+JSON output:
+
+```bash
+dot account inspect alice --output json
+# {"publicKey":"0xd435...a27d","ss58":"5Grw...utQY","prefix":42,"name":"Alice"}
 ```
 
 #### Env-var-backed accounts
@@ -219,20 +258,25 @@ dot const Balances.ExistentialDeposit --output json | jq
 Works offline from cached metadata after the first fetch.
 
 ```bash
-# List all pallets
+# List all pallets (shows storage, constants, and calls counts)
 dot inspect
 
-# List a pallet's storage items and constants
+# List a pallet's storage items, constants, and calls
 dot inspect System
 
-# Detailed type info for a specific item
+# Detailed type info for a specific storage item or constant
 dot inspect System.Account
 
+# Call detail — shows argument signature and docs
+dot inspect Balances.transfer_allow_death
+
 # Inspect a specific chain using chain prefix
 dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
+Use call inspection to discover argument names and types before constructing `dot tx` commands.
+
 ### Submit extrinsics
 
 Build, sign, and submit transactions. Pass a `Pallet.Call` with arguments, or a raw SCALE-encoded call hex (e.g. from a multisig proposal or governance). Both forms display a decoded human-readable representation of the call.
@@ -299,6 +343,12 @@ Both dry-run and submission display the encoded call hex and a decoded human-rea
   Status: ok
 ```
 
+Complex calls (e.g. XCM teleports) that the primary decoder cannot handle are automatically decoded via a fallback path:
+
+```
+  Decode: PolkadotXcm.limited_teleport_assets { dest: V3 { parents: 1, interior: X1(Parachain(5140)) }, beneficiary: V3 { ... }, assets: V3 [...], fee_asset_item: 0, weight_limit: Unlimited }
+```
+
 #### Exit codes
 
 The CLI exits with code **1** when a finalized transaction has a dispatch error (e.g. insufficient balance, bad origin). The full transaction output (events, explorer links) is still printed before the error so you can debug the failure. Module errors are formatted as `PalletName.ErrorVariant` (e.g. `Balances.InsufficientBalance`).
@@ -310,6 +360,18 @@ dot tx Balances.transferKeepAlive 5FHneW46... 999999999999999999 --from alice
 echo $?  # 1
 ```
 
+#### Argument parsing errors
+
+When a call argument is invalid, the CLI shows a contextual error message with the argument name, the expected type, and a hint:
+
+```bash
+dot tx Balances.transferKeepAlive 5GrwvaEF... abc --encode
+# Error: Invalid value for argument 'value' (expected Compact<u128>): "abc"
+#   Hint: Compact<u128>
+```
+
+For struct-based calls, the error identifies the specific field that failed. For tuple-based calls, it shows the argument index. The original parse error is preserved as the `cause` for programmatic access.
+
 #### Custom signed extensions
 
 Chains with non-standard signed extensions (e.g. `people-preview`) are auto-handled:

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 = "0.12.0";
+var version = "0.13.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -247,6 +247,7 @@ import {
   generateMnemonic,
   mnemonicToEntropy,
   ss58Address,
+  ss58Decode,
   validateMnemonic
 } from "@polkadot-labs/hdkd-helpers";
 import { getPolkadotSigner } from "polkadot-api/signer";
@@ -314,6 +315,13 @@ function toSs58(publicKey, prefix = 42) {
   }
   return ss58Address(publicKey, prefix);
 }
+function fromSs58(address) {
+  const [payload] = ss58Decode(address);
+  return payload;
+}
+function isHexPublicKey(input) {
+  return /^0x[0-9a-fA-F]{64}$/.test(input);
+}
 function resolveSecret(secret) {
   if (isEnvSecret(secret)) {
     const value = process.env[secret.env];
@@ -452,6 +460,7 @@ ${BOLD}Usage:${RESET}
   $ 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 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)
 
@@ -462,6 +471,9 @@ ${BOLD}Examples:${RESET}
   $ dot account import treasury --secret "word1 word2 ... word12"
   $ dot account import ci-signer --env MY_SECRET --path //ci
   $ dot account derive treasury treasury-staking --path //staking
+  $ dot account inspect alice
+  $ dot account inspect 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+  $ dot account inspect 0xd435...a27d --prefix 0
   $ dot account list
   $ dot account remove my-validator stale-key
 
@@ -470,7 +482,7 @@ ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
       Hex seed import (0x...) is not supported via CLI.${RESET}
 `.trimStart();
 function registerAccountCommands(cli) {
-  cli.command("account [action] [...names]", "Manage local accounts (create, import, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").option("--env <varName>", "Environment variable name holding the secret").option("--path <derivation>", "Derivation path (e.g. //staking, //polkadot//0/wallet)").action(async (action, names, opts) => {
+  cli.command("account [action] [...names]", "Manage local accounts (create, import, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").option("--env <varName>", "Environment variable name holding the secret").option("--path <derivation>", "Derivation path (e.g. //staking, //polkadot//0/wallet)").option("--prefix <number>", "SS58 prefix for address encoding (default: 42)").action(async (action, names, opts) => {
     if (!action) {
       if (process.argv[2] === "accounts")
         return accountList();
@@ -491,11 +503,10 @@ function registerAccountCommands(cli) {
       case "delete":
       case "remove":
         return accountRemove(names);
+      case "inspect":
+        return accountInspect(names[0], opts);
       default:
-        console.error(`Unknown action "${action}".
-`);
-        console.log(ACCOUNT_HELP);
-        process.exit(1);
+        return accountInspect(action, opts);
     }
   });
 }
@@ -743,6 +754,70 @@ async function accountRemove(names) {
     console.log(`Account "${name}" removed.`);
   }
 }
+async function accountInspect(input, opts) {
+  if (!input) {
+    console.error(`Input is required.
+`);
+    console.error("Usage: dot account inspect <name|ss58-address|0x-public-key> [--prefix <N>]");
+    process.exit(1);
+  }
+  const prefix = opts.prefix != null ? Number(opts.prefix) : 42;
+  if (Number.isNaN(prefix) || prefix < 0) {
+    console.error(`Invalid prefix "${opts.prefix}". Must be a non-negative integer.`);
+    process.exit(1);
+  }
+  let name;
+  let publicKeyHex;
+  if (isDevAccount(input)) {
+    name = input.charAt(0).toUpperCase() + input.slice(1).toLowerCase();
+    const devAddr = getDevAddress(input);
+    publicKeyHex = publicKeyToHex(fromSs58(devAddr));
+  } else {
+    const accountsFile = await loadAccounts();
+    const account = findAccount(accountsFile, input);
+    if (account) {
+      name = account.name;
+      if (account.publicKey) {
+        publicKeyHex = account.publicKey;
+      } else if (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.`);
+          process.exit(1);
+        }
+        publicKeyHex = derived;
+      } else {
+        console.error(`Account "${account.name}" has no public key.`);
+        process.exit(1);
+      }
+    } else if (isHexPublicKey(input)) {
+      publicKeyHex = input;
+    } else {
+      try {
+        const decoded = fromSs58(input);
+        publicKeyHex = publicKeyToHex(decoded);
+      } catch {
+        console.error(`Cannot identify "${input}" as an account name, SS58 address, or hex public key.`);
+        process.exit(1);
+      }
+    }
+  }
+  const ss58 = toSs58(publicKeyHex, prefix);
+  if (opts.output === "json") {
+    const result = { publicKey: publicKeyHex, ss58, prefix };
+    if (name)
+      result.name = name;
+    console.log(formatJson(result));
+  } else {
+    printHeading("Account Info");
+    if (name)
+      console.log(`  ${BOLD}Name:${RESET}        ${name}`);
+    console.log(`  ${BOLD}Public Key:${RESET}  ${publicKeyHex}`);
+    console.log(`  ${BOLD}SS58:${RESET}        ${ss58}`);
+    console.log(`  ${BOLD}Prefix:${RESET}      ${prefix}`);
+    console.log();
+  }
+}
 
 // src/core/client.ts
 import { createClient } from "polkadot-api";
@@ -984,6 +1059,42 @@ function formatLookupEntry(entry) {
       return "unknown";
   }
 }
+function describeCallArgs(meta, palletName, callName) {
+  try {
+    const palletMeta = meta.unified.pallets.find((p) => p.name === palletName);
+    if (!palletMeta?.calls)
+      return "";
+    const callsEntry = meta.lookup(palletMeta.calls.type);
+    if (callsEntry.type !== "enum")
+      return "";
+    const variant = callsEntry.value[callName];
+    if (!variant)
+      return "";
+    if (variant.type === "void")
+      return "()";
+    if (variant.type === "struct") {
+      const fields = Object.entries(variant.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
+      return `(${fields})`;
+    }
+    if (variant.type === "lookupEntry") {
+      const inner = variant.value;
+      if (inner.type === "void")
+        return "()";
+      if (inner.type === "struct") {
+        const fields = Object.entries(inner.value).map(([k, v]) => `${k}: ${formatLookupEntry(v)}`).join(", ");
+        return `(${fields})`;
+      }
+      return `(${formatLookupEntry(inner)})`;
+    }
+    if (variant.type === "tuple") {
+      const types = variant.value.map(formatLookupEntry).join(", ");
+      return `(${types})`;
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
 function hexToBytes(hex) {
   const clean = hex.startsWith("0x") ? hex.slice(2) : hex;
   const bytes = new Uint8Array(clean.length / 2);
@@ -1436,6 +1547,8 @@ function registerInspectCommand(cli) {
           counts.push(`${p.storage.length} storage`);
         if (p.constants.length)
           counts.push(`${p.constants.length} constants`);
+        if (p.calls.length)
+          counts.push(`${p.calls.length} calls`);
         printItem(p.name, counts.join(", "));
       }
       console.log();
@@ -1468,6 +1581,14 @@ function registerInspectCommand(cli) {
         }
         console.log();
       }
+      if (pallet2.calls.length) {
+        console.log(`  ${BOLD}Calls:${RESET}`);
+        for (const c of pallet2.calls) {
+          const doc = c.docs[0] ? ` — ${c.docs[0].slice(0, 80)}` : "";
+          console.log(`    ${CYAN}${c.name}${RESET}${DIM}${doc}${RESET}`);
+        }
+        console.log();
+      }
       return;
     }
     const palletNames = getPalletNames(meta);
@@ -1501,9 +1622,22 @@ function registerInspectCommand(cli) {
       console.log();
       return;
     }
+    const callItem = pallet.calls.find((c) => c.name.toLowerCase() === itemName.toLowerCase());
+    if (callItem) {
+      printHeading(`${pallet.name}.${callItem.name} (Call)`);
+      const args = describeCallArgs(meta, pallet.name, callItem.name);
+      console.log(`  ${BOLD}Args:${RESET} ${args}`);
+      if (callItem.docs.length) {
+        console.log();
+        printDocs(callItem.docs);
+      }
+      console.log();
+      return;
+    }
     const allItems = [
       ...pallet.storage.map((s) => s.name),
-      ...pallet.constants.map((c) => c.name)
+      ...pallet.constants.map((c) => c.name),
+      ...pallet.calls.map((c) => c.name)
     ];
     throw new Error(suggestMessage(`item in ${pallet.name}`, itemName, allItems));
   });
@@ -1549,10 +1683,36 @@ function parseStructArgs(meta, fields, args, callLabel) {
   for (let i = 0;i < fieldNames.length; i++) {
     const name = fieldNames[i];
     const entry = fields[name];
-    result[name] = parseTypedArg(meta, entry, args[i]);
+    try {
+      result[name] = 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])}
+` + `  Hint: ${typeHint(entry, meta)}`, { cause: err });
+    }
   }
   return result;
 }
+function typeHint(entry, meta) {
+  const resolved = entry.type === "lookupEntry" ? entry.value : entry;
+  switch (resolved.type) {
+    case "enum": {
+      const variants = Object.keys(resolved.value);
+      if (variants.length <= 6)
+        return `a variant: ${variants.join(" | ")}`;
+      return `one of ${variants.length} variants (e.g. ${variants.slice(0, 3).join(", ")})`;
+    }
+    case "struct":
+      return `a JSON object with fields: ${Object.keys(resolved.value).join(", ")}`;
+    case "tuple":
+      return "a JSON array";
+    case "sequence":
+    case "array":
+      return "a JSON array or hex-encoded bytes";
+    default:
+      return describeType(meta.lookup, entry.id);
+  }
+}
 function normalizeValue(lookup, entry, value) {
   let resolved = entry;
   while (resolved.type === "lookupEntry") {
@@ -2084,10 +2244,66 @@ function decodeCall(meta, callHex) {
     const callName = decoded.call.value.name;
     const argsStr = formatDecodedArgs(decoded.args.value);
     return `${palletName}.${callName}${argsStr}`;
+  } catch {}
+  try {
+    return decodeCallFallback(meta, callHex);
   } catch {
     return "(unable to decode)";
   }
 }
+function decodeCallFallback(meta, callHex) {
+  const callTypeId = meta.lookup.call;
+  if (callTypeId == null)
+    throw new Error("No RuntimeCall type ID");
+  const codec = meta.builder.buildDefinition(callTypeId);
+  const decoded = codec.dec(Binary3.fromHex(callHex).asBytes());
+  const palletName = decoded.type;
+  const call = decoded.value;
+  const callName = call.type;
+  const args = call.value;
+  if (args === undefined || args === null) {
+    return `${palletName}.${callName}`;
+  }
+  const argsStr = formatRawDecoded(args);
+  return `${palletName}.${callName} ${argsStr}`;
+}
+function formatRawDecoded(value) {
+  if (value === undefined || value === null)
+    return "null";
+  if (value instanceof Binary3)
+    return value.asHex();
+  if (typeof value === "bigint")
+    return value.toString();
+  if (typeof value === "string")
+    return value;
+  if (typeof value === "number")
+    return value.toString();
+  if (typeof value === "boolean")
+    return value.toString();
+  if (Array.isArray(value)) {
+    if (value.length === 0)
+      return "[]";
+    return `[${value.map(formatRawDecoded).join(", ")}]`;
+  }
+  if (typeof value === "object") {
+    const obj = value;
+    if ("type" in obj && typeof obj.type === "string") {
+      const inner = obj.value;
+      if (inner === undefined || inner === null)
+        return obj.type;
+      const innerStr = formatRawDecoded(inner);
+      if (innerStr.startsWith("{"))
+        return `${obj.type} ${innerStr}`;
+      return `${obj.type}(${innerStr})`;
+    }
+    const entries = Object.entries(obj);
+    if (entries.length === 0)
+      return "{}";
+    const fields = entries.map(([k, v]) => `${k}: ${formatRawDecoded(v)}`).join(", ");
+    return `{ ${fields} }`;
+  }
+  return String(value);
+}
 function formatDecodedArgs(decoded) {
   return formatDecoded(decoded);
 }
@@ -2211,14 +2427,26 @@ function parseCallArgs(meta, palletName, callName, args) {
     if (args.length !== 1) {
       throw new Error(`${palletName}.${callName} takes 1 argument (${describeType(meta.lookup, inner.id)}), but ${args.length} provided.`);
     }
-    return parseTypedArg2(meta, inner, args[0]);
+    try {
+      return 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 });
+    }
   }
   if (variant.type === "tuple") {
     const entries = variant.value;
     if (args.length !== entries.length) {
       throw new Error(`${palletName}.${callName} takes ${entries.length} arguments, but ${args.length} provided.`);
     }
-    return entries.map((entry, i) => parseTypedArg2(meta, entry, args[i]));
+    return entries.map((entry, i) => {
+      try {
+        return 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);
 }
@@ -2233,10 +2461,36 @@ function parseStructArgs2(meta, fields, args, callLabel) {
   for (let i = 0;i < fieldNames.length; i++) {
     const name = fieldNames[i];
     const entry = fields[name];
-    result[name] = parseTypedArg2(meta, entry, args[i]);
+    try {
+      result[name] = 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])}
+` + `  Hint: ${typeHint2(entry, meta)}`, { cause: err });
+    }
   }
   return result;
 }
+function typeHint2(entry, meta) {
+  const resolved = entry.type === "lookupEntry" ? entry.value : entry;
+  switch (resolved.type) {
+    case "enum": {
+      const variants = Object.keys(resolved.value);
+      if (variants.length <= 6)
+        return `a variant: ${variants.join(" | ")}`;
+      return `one of ${variants.length} variants (e.g. ${variants.slice(0, 3).join(", ")})`;
+    }
+    case "struct":
+      return `a JSON object with fields: ${Object.keys(resolved.value).join(", ")}`;
+    case "tuple":
+      return "a JSON array";
+    case "sequence":
+    case "array":
+      return "a JSON array or hex-encoded bytes";
+    default:
+      return describeType(meta.lookup, entry.id);
+  }
+}
 function normalizeValue2(lookup, entry, value) {
   let resolved = entry;
   while (resolved.type === "lookupEntry") {

package/package.json

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