polkadot-cli 0.11.0 → 0.13.0

package/README.md

@@ -4,7 +4,26 @@
 
 A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, submit extrinsics, and compute hashes — all from your terminal.
 
-Ships with Polkadot as the default chain. Add any Substrate-based chain by pointing to its RPC endpoint.
+Ships with Polkadot and all system parachains preconfigured with multiple fallback RPC endpoints. Add any Substrate-based chain by pointing to its RPC endpoint(s).
+
+### Preconfigured chains
+
+| Network | Chain | Light client |
+|---------|-------|:---:|
+| Polkadot | `polkadot` (relay, default) | yes |
+| | `polkadot-asset-hub` | yes |
+| | `polkadot-bridge-hub` | yes |
+| | `polkadot-collectives` | yes |
+| | `polkadot-coretime` | yes |
+| | `polkadot-people` | yes |
+| Paseo (testnet) | `paseo` (relay) | yes |
+| | `paseo-asset-hub` | yes |
+| | `paseo-bridge-hub` | — |
+| | `paseo-collectives` | — |
+| | `paseo-coretime` | yes |
+| | `paseo-people` | yes |
+
+Each chain ships with multiple RPC endpoints from decentralized infrastructure providers (IBP, Dotters, Dwellir, and others). The CLI automatically falls back to the next endpoint if the primary is unreachable.
 
 ## Install
 
@@ -23,8 +42,13 @@ This installs the `dot` command globally.
 dot chain               # shows available actions
 dot chains              # shorthand, same as above
 
-# Add a chain
+# Add a chain (single RPC)
 dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
+
+# Add a chain with fallback RPCs (repeat --rpc for each endpoint)
+dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
+
+# Add a chain via light client
 dot chain add westend --light-client
 
 # List configured chains
@@ -58,17 +82,66 @@ dot account list
 # Create a new account (generates a mnemonic)
 dot account create my-validator
 
+# Create with a derivation path
+dot account create my-staking --path //staking
+
 # Import from a BIP39 mnemonic
 dot account import treasury --secret "word1 word2 ... word12"
 
+# Import with a derivation path
+dot account import hot-wallet --secret "word1 word2 ... word12" --path //hot
+
 # Import an env-var-backed account (secret stays off disk)
 dot account import ci-signer --env MY_SECRET
 
+# Derive a child account from an existing one
+dot account derive treasury treasury-staking --path //staking
+
 # Use it — the env var is read at signing time
 MY_SECRET="word1 word2 ..." dot tx System.remark 0xdead --from ci-signer
 
-# Remove an account
+# 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
@@ -83,6 +156,33 @@ dot account import ci-signer --env MY_SECRET
 
 The secret is never written to disk. At signing time, the CLI reads `$MY_SECRET` and derives the keypair. If the variable is not set, the CLI errors with a clear message. `account list` shows an `(env: MY_SECRET)` badge and resolves the address live when the variable is available.
 
+#### Derivation paths
+
+Use `--path` with `create`, `import`, or the `derive` action to derive child keys from the same secret. Different paths produce different keypairs, enabling key separation (e.g. staking vs. governance) without managing multiple mnemonics.
+
+```bash
+# Create with a derivation path
+dot account create my-staking --path //staking
+
+# Multi-segment path (hard + soft junctions)
+dot account create multi --path //polkadot//0/wallet
+
+# Import with a path
+dot account import hot --secret "word1 word2 ..." --path //hot
+
+# Derive a child from an existing account
+dot account derive treasury treasury-staking --path //staking
+```
+
+`derive` copies the source account's secret and applies the given path. It requires both a source name, a new name, and `--path`. Works with env-backed accounts too — the derived account shares the same env var reference.
+
+`account list` shows the derivation path next to the account name:
+
+```
+  treasury-staking (//staking)  5FHneW46...
+  ci-signer (//ci) (env: MY_SECRET)  5EPCUjPx...
+```
+
 **Supported secret formats for import:**
 
 | Format | Example | Status |
@@ -158,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.
@@ -238,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`).
@@ -249,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:
@@ -286,12 +409,24 @@ dot hash blake2b256 0xdeadbeef --output json
 
 Run `dot hash` with no arguments to see all available algorithms.
 
+### Getting help
+
+Every command supports `--help` to show its detailed usage, available actions, and examples:
+
+```bash
+dot --help              # global help with all commands
+dot account --help      # same as `dot account` — shows account actions
+dot chain --help        # same as `dot chain` — shows chain actions
+dot hash --help         # same as `dot hash` — shows algorithms and examples
+```
+
 ### Global options
 
 | Flag | Description |
 |------|-------------|
+| `--help` | Show help (global or command-specific) |
 | `--chain <name>` | Target chain (default from config) |
-| `--rpc <url>` | Override RPC endpoint for this call |
+| `--rpc <url>` | Override RPC endpoint(s) for this call (repeat for fallback) |
 | `--light-client` | Use Smoldot light client |
 | `--output json` | Raw JSON output (default: pretty) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |

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.11.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";
@@ -17,14 +17,117 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 // src/config/types.ts
+function primaryRpc(rpc) {
+  return Array.isArray(rpc) ? rpc[0] : rpc;
+}
 var DEFAULT_CONFIG = {
   defaultChain: "polkadot",
   chains: {
-    polkadot: { rpc: "wss://rpc.polkadot.io" },
-    paseo: { rpc: "wss://rpc.ibp.network/paseo" },
-    "polkadot-asset-hub": { rpc: "wss://polkadot-asset-hub-rpc.polkadot.io" },
-    "paseo-asset-hub": { rpc: "wss://asset-hub-paseo-rpc.dwellir.com" },
-    "polkadot-people": { rpc: "wss://polkadot-people-rpc.polkadot.io" }
+    polkadot: {
+      rpc: [
+        "wss://polkadot.ibp.network",
+        "wss://polkadot.dotters.network",
+        "wss://polkadot-rpc.n.dwellir.com",
+        "wss://polkadot-rpc.publicnode.com",
+        "wss://rpc-polkadot.luckyfriday.io",
+        "wss://polkadot.api.onfinality.io/public-ws",
+        "wss://rpc-polkadot.helixstreet.io",
+        "wss://polkadot-rpc-tn.dwellir.com",
+        "wss://polkadot.public.curie.radiumblock.co/ws",
+        "wss://rpc-polkadot.stakeworld.io",
+        "wss://polkadot.rpc.subquery.network/public/ws",
+        "wss://rpc.polkadot.io"
+      ]
+    },
+    "polkadot-asset-hub": {
+      rpc: [
+        "wss://polkadot-asset-hub-rpc.polkadot.io",
+        "wss://asset-hub-polkadot.ibp.network",
+        "wss://asset-hub-polkadot.dotters.network",
+        "wss://asset-hub-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-asset-hub-polkadot.luckyfriday.io",
+        "wss://statemint.api.onfinality.io/public-ws",
+        "wss://statemint-rpc-tn.dwellir.com",
+        "wss://statemint.public.curie.radiumblock.co/ws",
+        "wss://asset-hub-polkadot.rpc.permanence.io"
+      ]
+    },
+    "polkadot-bridge-hub": {
+      rpc: [
+        "wss://polkadot-bridge-hub-rpc.polkadot.io",
+        "wss://bridge-hub-polkadot.ibp.network",
+        "wss://bridge-hub-polkadot.dotters.network",
+        "wss://bridge-hub-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-bridge-hub-polkadot.luckyfriday.io",
+        "wss://bridgehub-polkadot.api.onfinality.io/public-ws",
+        "wss://polkadot-bridge-hub-rpc-tn.dwellir.com",
+        "wss://bridgehub-polkadot.public.curie.radiumblock.co/ws"
+      ]
+    },
+    "polkadot-collectives": {
+      rpc: [
+        "wss://polkadot-collectives-rpc.polkadot.io",
+        "wss://collectives-polkadot.ibp.network",
+        "wss://collectives-polkadot.dotters.network",
+        "wss://collectives-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-collectives-polkadot.luckyfriday.io",
+        "wss://collectives.api.onfinality.io/public-ws",
+        "wss://polkadot-collectives-rpc-tn.dwellir.com",
+        "wss://collectives.public.curie.radiumblock.co/ws"
+      ]
+    },
+    "polkadot-coretime": {
+      rpc: [
+        "wss://polkadot-coretime-rpc.polkadot.io",
+        "wss://coretime-polkadot.ibp.network",
+        "wss://coretime-polkadot.dotters.network",
+        "wss://coretime-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-coretime-polkadot.luckyfriday.io",
+        "wss://coretime-polkadot.api.onfinality.io/public-ws"
+      ]
+    },
+    "polkadot-people": {
+      rpc: [
+        "wss://polkadot-people-rpc.polkadot.io",
+        "wss://people-polkadot.ibp.network",
+        "wss://people-polkadot.dotters.network",
+        "wss://people-polkadot-rpc.n.dwellir.com",
+        "wss://rpc-people-polkadot.luckyfriday.io",
+        "wss://people-polkadot.api.onfinality.io/public-ws"
+      ]
+    },
+    paseo: {
+      rpc: [
+        "wss://paseo.ibp.network",
+        "wss://paseo.dotters.network",
+        "wss://paseo-rpc.n.dwellir.com",
+        "wss://paseo.rpc.amforc.com"
+      ]
+    },
+    "paseo-asset-hub": {
+      rpc: [
+        "wss://asset-hub-paseo.ibp.network",
+        "wss://asset-hub-paseo.dotters.network",
+        "wss://asset-hub-paseo-rpc.n.dwellir.com",
+        "wss://sys.turboflakes.io/asset-hub-paseo"
+      ]
+    },
+    "paseo-bridge-hub": {
+      rpc: ["wss://bridge-hub-paseo.ibp.network", "wss://bridge-hub-paseo.dotters.network"]
+    },
+    "paseo-collectives": {
+      rpc: ["wss://collectives-paseo.ibp.network", "wss://collectives-paseo.dotters.network"]
+    },
+    "paseo-coretime": {
+      rpc: ["wss://coretime-paseo.ibp.network", "wss://coretime-paseo.dotters.network"]
+    },
+    "paseo-people": {
+      rpc: [
+        "wss://people-paseo.ibp.network",
+        "wss://people-paseo.dotters.network",
+        "wss://people-paseo.rpc.amforc.com"
+      ]
+    }
   }
 };
 var BUILTIN_CHAIN_NAMES = new Set(Object.keys(DEFAULT_CONFIG.chains));
@@ -144,6 +247,7 @@ import {
   generateMnemonic,
   mnemonicToEntropy,
   ss58Address,
+  ss58Decode,
   validateMnemonic
 } from "@polkadot-labs/hdkd-helpers";
 import { getPolkadotSigner } from "polkadot-api/signer";
@@ -177,24 +281,24 @@ function getDevAddress(name, prefix = 42) {
   const keypair = getDevKeypair(name);
   return ss58Address(keypair.publicKey, prefix);
 }
-function createNewAccount() {
+function createNewAccount(path = "") {
   const mnemonic = generateMnemonic();
   const entropy = mnemonicToEntropy(mnemonic);
   const miniSecret = entropyToMiniSecret(entropy);
   const derive = sr25519CreateDerive(miniSecret);
-  const keypair = derive("");
+  const keypair = derive(path);
   return { mnemonic, publicKey: keypair.publicKey };
 }
-function importAccount(secret) {
+function importAccount(secret, path = "") {
   const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(secret);
   if (isHexSeed) {
-    const keypair2 = deriveFromHexSeed(secret, "");
+    const keypair2 = deriveFromHexSeed(secret, path);
     return { publicKey: keypair2.publicKey };
   }
   if (!validateMnemonic(secret)) {
     throw new Error("Invalid secret. Expected a 0x-prefixed 32-byte hex seed or a valid BIP39 mnemonic.");
   }
-  const keypair = deriveFromMnemonic(secret, "");
+  const keypair = deriveFromMnemonic(secret, path);
   return { publicKey: keypair.publicKey };
 }
 function publicKeyToHex(publicKey) {
@@ -211,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];
@@ -221,12 +332,12 @@ function resolveSecret(secret) {
   }
   return secret;
 }
-function tryDerivePublicKey(envVarName) {
+function tryDerivePublicKey(envVarName, path = "") {
   const value = process.env[envVarName];
   if (!value)
     return null;
   try {
-    const { publicKey } = importAccount(value);
+    const { publicKey } = importAccount(value, path);
     return publicKeyToHex(publicKey);
   } catch {
     return null;
@@ -345,50 +456,61 @@ class Spinner {
 // src/commands/account.ts
 var ACCOUNT_HELP = `
 ${BOLD}Usage:${RESET}
-  $ dot account create|new <name>                       Create a new account
-  $ dot account import|add <name> --secret <s>          Import from BIP39 mnemonic
-  $ dot account import|add <name> --env <VAR>           Import account backed by env variable
-  $ dot account list                                    List all accounts
-  $ dot account remove|delete <name>                    Remove a stored account
+  $ 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 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 create my-validator
+  $ dot account create my-staking --path //staking
+  $ dot account create multi --path //polkadot//0/wallet
   $ dot account import treasury --secret "word1 word2 ... word12"
-  $ dot account import ci-signer --env MY_SECRET
+  $ 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
+  $ dot account remove my-validator stale-key
 
 ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
       Use --env to keep secrets off disk entirely.
       Hex seed import (0x...) is not supported via CLI.${RESET}
 `.trimStart();
 function registerAccountCommands(cli) {
-  cli.command("account [action] [name]", "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").action(async (action, name, 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();
       console.log(ACCOUNT_HELP);
       return;
     }
     switch (action) {
       case "new":
       case "create":
-        return accountCreate(name);
+        return accountCreate(names[0], opts);
       case "import":
       case "add":
-        return accountImport(name, opts);
+        return accountImport(names[0], opts);
+      case "derive":
+        return accountDerive(names[0], names[1], opts);
       case "list":
         return accountList();
       case "delete":
       case "remove":
-        return accountRemove(name);
+        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);
     }
   });
 }
-async function accountCreate(name) {
+async function accountCreate(name, opts) {
   if (!name) {
     console.error(`Account name is required.
 `);
@@ -402,18 +524,21 @@ async function accountCreate(name) {
   if (findAccount(accountsFile, name)) {
     throw new Error(`Account "${name}" already exists.`);
   }
-  const { mnemonic, publicKey } = createNewAccount();
+  const path = opts.path ?? "";
+  const { mnemonic, publicKey } = createNewAccount(path);
   const hexPub = publicKeyToHex(publicKey);
   const address = toSs58(publicKey);
   accountsFile.accounts.push({
     name,
     secret: mnemonic,
     publicKey: hexPub,
-    derivationPath: ""
+    derivationPath: path
   });
   await saveAccounts(accountsFile);
   printHeading("Account Created");
   console.log(`  ${BOLD}Name:${RESET}     ${name}`);
+  if (path)
+    console.log(`  ${BOLD}Path:${RESET}     ${path}`);
   console.log(`  ${BOLD}Address:${RESET}  ${address}`);
   console.log(`  ${BOLD}Mnemonic:${RESET} ${mnemonic}`);
   console.log();
@@ -446,17 +571,20 @@ async function accountImport(name, opts) {
   if (findAccount(accountsFile, name)) {
     throw new Error(`Account "${name}" already exists.`);
   }
+  const path = opts.path ?? "";
   if (opts.env) {
-    const publicKey = tryDerivePublicKey(opts.env) ?? "";
+    const publicKey = tryDerivePublicKey(opts.env, path) ?? "";
     accountsFile.accounts.push({
       name,
       secret: { env: opts.env },
       publicKey,
-      derivationPath: ""
+      derivationPath: path
     });
     await saveAccounts(accountsFile);
     printHeading("Account Imported");
     console.log(`  ${BOLD}Name:${RESET}    ${name}`);
+    if (path)
+      console.log(`  ${BOLD}Path:${RESET}    ${path}`);
     console.log(`  ${BOLD}Env:${RESET}     ${opts.env}`);
     if (publicKey) {
       console.log(`  ${BOLD}Address:${RESET} ${toSs58(publicKey)}`);
@@ -465,18 +593,90 @@ async function accountImport(name, opts) {
     }
     console.log();
   } else {
-    const { publicKey } = importAccount(opts.secret);
+    const { publicKey } = importAccount(opts.secret, path);
     const hexPub = publicKeyToHex(publicKey);
     const address = toSs58(publicKey);
     accountsFile.accounts.push({
       name,
       secret: opts.secret,
       publicKey: hexPub,
-      derivationPath: ""
+      derivationPath: path
     });
     await saveAccounts(accountsFile);
     printHeading("Account Imported");
     console.log(`  ${BOLD}Name:${RESET}    ${name}`);
+    if (path)
+      console.log(`  ${BOLD}Path:${RESET}    ${path}`);
+    console.log(`  ${BOLD}Address:${RESET} ${address}`);
+    console.log();
+  }
+}
+async function accountDerive(sourceName, newName, opts) {
+  if (!sourceName) {
+    console.error(`Source account name is required.
+`);
+    console.error("Usage: dot account derive <source> <new-name> --path <derivation>");
+    process.exit(1);
+  }
+  if (!newName) {
+    console.error(`New account name is required.
+`);
+    console.error("Usage: dot account derive <source> <new-name> --path <derivation>");
+    process.exit(1);
+  }
+  if (!opts.path) {
+    console.error(`--path is required for derive.
+`);
+    console.error("Usage: dot account derive <source> <new-name> --path <derivation>");
+    process.exit(1);
+  }
+  if (isDevAccount(newName)) {
+    throw new Error(`"${newName}" is a built-in dev account and cannot be used as a custom account name.`);
+  }
+  const accountsFile = await loadAccounts();
+  const source = findAccount(accountsFile, sourceName);
+  if (!source) {
+    throw new Error(`Source account "${sourceName}" not found.`);
+  }
+  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) ?? "";
+    accountsFile.accounts.push({
+      name: newName,
+      secret: source.secret,
+      publicKey,
+      derivationPath: path
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Derived");
+    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}`);
+    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();
+  } else {
+    const { publicKey } = importAccount(source.secret, path);
+    const hexPub = publicKeyToHex(publicKey);
+    const address = toSs58(publicKey);
+    accountsFile.accounts.push({
+      name: newName,
+      secret: source.secret,
+      publicKey: hexPub,
+      derivationPath: path
+    });
+    await saveAccounts(accountsFile);
+    printHeading("Account Derived");
+    console.log(`  ${BOLD}Name:${RESET}    ${newName}`);
+    console.log(`  ${BOLD}Source:${RESET}  ${sourceName}`);
+    console.log(`  ${BOLD}Path:${RESET}    ${path}`);
     console.log(`  ${BOLD}Address:${RESET} ${address}`);
     console.log();
   }
@@ -493,12 +693,15 @@ async function accountList() {
     printHeading("Stored Accounts");
     for (const account of accountsFile.accounts) {
       let displayName = account.name;
+      if (account.derivationPath) {
+        displayName += ` (${account.derivationPath})`;
+      }
       let address;
       if (isEnvSecret(account.secret)) {
         displayName += ` (env: ${account.secret.env})`;
         let pubKey = account.publicKey;
         if (!pubKey) {
-          pubKey = tryDerivePublicKey(account.secret.env) ?? "";
+          pubKey = tryDerivePublicKey(account.secret.env, account.derivationPath) ?? "";
         }
         address = pubKey ? toSs58(pubKey) : "n/a";
       } else {
@@ -512,24 +715,108 @@ async function accountList() {
   }
   console.log();
 }
-async function accountRemove(name) {
-  if (!name) {
-    console.error(`Account name is required.
+async function accountRemove(names) {
+  if (names.length === 0) {
+    console.error(`At least one account name is required.
 `);
-    console.error("Usage: dot account remove <name>");
+    console.error("Usage: dot account remove <name> [name2] ...");
     process.exit(1);
   }
-  if (isDevAccount(name)) {
-    throw new Error("Cannot remove built-in dev accounts.");
+  const errors = [];
+  for (const name of names) {
+    if (isDevAccount(name)) {
+      errors.push(`Cannot remove built-in dev account "${name}".`);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join(`
+`));
   }
   const accountsFile = await loadAccounts();
-  const idx = accountsFile.accounts.findIndex((a) => a.name.toLowerCase() === name.toLowerCase());
-  if (idx === -1) {
-    throw new Error(`Account "${name}" not found.`);
+  const indicesToRemove = new Set;
+  for (const name of names) {
+    const idx = accountsFile.accounts.findIndex((a) => a.name.toLowerCase() === name.toLowerCase());
+    if (idx === -1) {
+      errors.push(`Account "${name}" not found.`);
+    } else {
+      indicesToRemove.add(idx);
+    }
+  }
+  if (errors.length > 0) {
+    throw new Error(errors.join(`
+`));
+  }
+  for (const idx of [...indicesToRemove].sort((a, b) => b - a)) {
+    accountsFile.accounts.splice(idx, 1);
   }
-  accountsFile.accounts.splice(idx, 1);
   await saveAccounts(accountsFile);
-  console.log(`Account "${name}" removed.`);
+  for (const name of 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
@@ -566,8 +853,13 @@ var KNOWN_CHAIN_SPECS = {
   westend: { spec: "polkadot-api/chains/westend2" },
   paseo: { spec: "polkadot-api/chains/paseo" },
   "polkadot-asset-hub": { spec: "polkadot-api/chains/polkadot_asset_hub", relay: "polkadot" },
+  "polkadot-bridge-hub": { spec: "polkadot-api/chains/polkadot_bridge_hub", relay: "polkadot" },
+  "polkadot-collectives": { spec: "polkadot-api/chains/polkadot_collectives", relay: "polkadot" },
+  "polkadot-coretime": { spec: "polkadot-api/chains/polkadot_coretime", relay: "polkadot" },
   "polkadot-people": { spec: "polkadot-api/chains/polkadot_people", relay: "polkadot" },
-  "paseo-asset-hub": { spec: "polkadot-api/chains/paseo_asset_hub", relay: "paseo" }
+  "paseo-asset-hub": { spec: "polkadot-api/chains/paseo_asset_hub", relay: "paseo" },
+  "paseo-coretime": { spec: "polkadot-api/chains/paseo_coretime", relay: "paseo" },
+  "paseo-people": { spec: "polkadot-api/chains/paseo_people", relay: "paseo" }
 };
 function suppressWsNoise() {
   const orig = console.error;
@@ -767,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);
@@ -788,6 +1116,7 @@ ${BOLD}Usage:${RESET}
 
 ${BOLD}Examples:${RESET}
   $ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
+  $ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io --rpc wss://kusama-rpc.dwellir.com
   $ dot chain add westend --light-client
   $ dot chain default kusama
   $ dot chain list
@@ -798,6 +1127,8 @@ ${BOLD}Examples:${RESET}
 function registerChainCommands(cli) {
   cli.command("chain [action] [name]", "Manage chains (add, remove, update, list, default)").alias("chains").action(async (action, name, opts) => {
     if (!action) {
+      if (process.argv[2] === "chains")
+        return chainList();
       console.log(CHAIN_HELP);
       return;
     }
@@ -880,8 +1211,15 @@ async function chainList() {
   for (const [name, chainConfig] of Object.entries(config.chains)) {
     const isDefault = name === config.defaultChain;
     const marker = isDefault ? ` ${BOLD}(default)${RESET}` : "";
-    const provider = chainConfig.lightClient ? `${DIM}light-client${RESET}` : `${DIM}${chainConfig.rpc}${RESET}`;
-    console.log(`  ${CYAN}${name}${RESET}${marker}  ${provider}`);
+    if (chainConfig.lightClient) {
+      console.log(`  ${CYAN}${name}${RESET}${marker}  ${DIM}light-client${RESET}`);
+    } else {
+      const rpcs = Array.isArray(chainConfig.rpc) ? chainConfig.rpc : [chainConfig.rpc];
+      console.log(`  ${CYAN}${name}${RESET}${marker}  ${DIM}${rpcs[0]}${RESET}`);
+      for (let i = 1;i < rpcs.length; i++) {
+        console.log(`    ${DIM}${rpcs[i]}${RESET}`);
+      }
+    }
   }
   console.log();
 }
@@ -1209,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();
@@ -1241,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);
@@ -1274,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));
   });
@@ -1322,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") {
@@ -1816,7 +2203,7 @@ function registerTxCommand(cli) {
           }
         }
       }
-      const rpcUrl = opts.rpc ?? chainConfig.rpc;
+      const rpcUrl = primaryRpc(opts.rpc ?? chainConfig.rpc);
       if (rpcUrl) {
         const blockHash = result.block.hash;
         console.log(`  ${BOLD}Explorer:${RESET}`);
@@ -1857,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);
 }
@@ -1984,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);
 }
@@ -2006,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") {
@@ -2492,7 +2973,7 @@ registerConstCommand(cli);
 registerAccountCommands(cli);
 registerTxCommand(cli);
 registerHashCommand(cli);
-cli.help();
+cli.option("--help, -h", "Display this message");
 cli.version(version);
 async function showUpdateAndExit(code) {
   await waitForPendingCheck();
@@ -2515,8 +2996,18 @@ async function handleError(err) {
 async function main() {
   try {
     cli.parse(process.argv, { run: false });
-    if (cli.options.version || cli.options.help) {
+    if (cli.options.version) {
       await showUpdateAndExit(0);
+    } else if (cli.options.help) {
+      if (cli.matchedCommandName) {
+        const result = cli.runMatchedCommand();
+        if (result && typeof result.then === "function") {
+          await result.then(() => showUpdateAndExit(0), handleError);
+        }
+      } else {
+        cli.outputHelp();
+        await showUpdateAndExit(0);
+      }
     } else if (!cli.matchedCommandName) {
       cli.outputHelp();
       await showUpdateAndExit(0);

package/package.json

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