polkadot-cli 1.3.0 → 1.5.0

package/README.md

@@ -251,11 +251,17 @@ dot query System.Number
 # Map entry by key
 dot query System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 
-# All map entries (default limit: 100)
-dot query System.Account --limit 10
+# Map without key — shows help/usage (use --dump to fetch all entries)
+dot query System.Account
+
+# Dump all map entries (requires --dump, default limit: 100)
+dot query System.Account --dump --limit 10
+
+# Enum variant as map key (case-insensitive)
+dot query people-preview.ChunksManager.Chunks R2e9 1
 
 # Pipe-safe — stdout is clean data, progress messages go to stderr
-dot query System.Account --limit 5 | jq '.[0].value.data.free'
+dot query System.Account --dump --limit 5 | jq '.[0].value.data.free'
 dot query System.Number --output json | jq '.+1'
 
 # Query a specific chain using chain prefix
@@ -315,6 +321,8 @@ dot inspect kusama.System
 dot inspect kusama.System.Account
 ```
 
+All listings — pallets, storage items, constants, calls, events, and errors — are sorted alphabetically, making it easy to find a specific item at a glance.
+
 The pallet listing view shows type information inline so you can understand item shapes at a glance:
 
 - **Storage**: key/value types with `[map]` tag for map items (e.g. `Account: AccountId32 → { nonce: u32, ... }    [map]`)
@@ -451,6 +459,31 @@ dot tx Balances.transferKeepAlive 5GrwvaEF... abc --encode
 
 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.
 
+#### Wait level
+
+By default, `dot tx` waits for finalization (~30s on Polkadot). Use `--wait` / `-w` to return earlier:
+
+```bash
+# Return as soon as the tx is broadcast (fastest)
+dot tx System.remark 0xdead --from alice --wait broadcast
+
+# Return when included in a best block
+dot tx System.remark 0xdead --from alice -w best-block
+dot tx System.remark 0xdead --from alice -w best    # alias
+
+# Wait for finalization (default, unchanged)
+dot tx System.remark 0xdead --from alice --wait finalized
+dot tx System.remark 0xdead --from alice             # same
+```
+
+| Level | Resolves when | Events shown | Explorer links |
+|-------|---------------|:---:|:---:|
+| `broadcast` | Tx is broadcast to the network | — | — |
+| `best-block` / `best` | Tx is included in a best block | yes | yes |
+| `finalized` (default) | Tx is finalized | yes | yes |
+
+The `--wait` flag is silently ignored when combined with `--dry-run` or `--encode` (both return before submission).
+
 #### Custom signed extensions
 
 Chains with non-standard signed extensions (e.g. `people-preview`) are auto-handled:
@@ -526,7 +559,9 @@ dot tx.System.remark 0xdead               # shows call help (no error)
 | `--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) |
+| `--dump` | Dump all entries of a storage map (required for keyless map queries) |
 | `--limit <n>` | Max entries for map queries (0 = unlimited, default: 100) |
+| `-w, --wait <level>` | Tx wait level: `broadcast`, `best-block` / `best`, `finalized` (default) |
 
 ### Pipe-safe output
 

package/dist/cli.mjs

@@ -447,26 +447,27 @@ async function getOrFetchMetadata(chainName, clientHandle) {
   return parseMetadata(raw);
 }
 function listPallets(meta) {
-  return meta.unified.pallets.map((p) => ({
+  const sortByName = (arr) => arr.sort((a, b) => a.name.localeCompare(b.name));
+  return sortByName(meta.unified.pallets.map((p) => ({
     name: p.name,
     index: p.index,
     docs: p.docs ?? [],
-    storage: (p.storage?.items ?? []).map((s) => ({
+    storage: sortByName((p.storage?.items ?? []).map((s) => ({
       name: s.name,
       docs: s.docs ?? [],
       type: s.type.tag,
       keyTypeId: s.type.tag === "map" ? s.type.value.key : null,
       valueTypeId: s.type.tag === "plain" ? s.type.value : s.type.value.value
-    })),
-    constants: (p.constants ?? []).map((c) => ({
+    }))),
+    constants: sortByName((p.constants ?? []).map((c) => ({
       name: c.name,
       docs: c.docs ?? [],
       typeId: c.type
-    })),
-    calls: extractEnumVariants(meta, p.calls),
-    events: extractEnumVariants(meta, p.events),
-    errors: extractEnumVariants(meta, p.errors).map(({ name, docs }) => ({ name, docs }))
-  }));
+    }))),
+    calls: sortByName(extractEnumVariants(meta, p.calls)),
+    events: sortByName(extractEnumVariants(meta, p.events)),
+    errors: sortByName(extractEnumVariants(meta, p.errors).map(({ name, docs }) => ({ name, docs })))
+  })));
 }
 function extractEnumVariants(meta, ref) {
   if (!ref)
@@ -505,7 +506,7 @@ function getSignedExtensions(meta) {
   return byVersion[Number(versionKeys[0])] ?? [];
 }
 function getPalletNames(meta) {
-  return meta.unified.pallets.map((p) => p.name);
+  return meta.unified.pallets.map((p) => p.name).sort((a, b) => a.localeCompare(b));
 }
 function describeType(lookup, typeId) {
   try {
@@ -766,6 +767,9 @@ async function generateCompletions(currentWord, precedingWords) {
     const names = [...DEV_NAMES, ...accounts.accounts.map((a) => a.name)];
     return filterPrefix(names, currentWord);
   }
+  if (prevWord === "--wait" || prevWord === "-w") {
+    return filterPrefix(["broadcast", "best-block", "best", "finalized"], currentWord);
+  }
   if (currentWord.startsWith("--")) {
     const activeCategory = detectCategory(precedingWords, knownChains);
     const options = [...GLOBAL_OPTIONS];
@@ -807,7 +811,11 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
   const partial = endsWithDot ? "" : parts[parts.length - 1] ?? "";
   const numComplete = completeSegments.length;
   if (numComplete === 0 && !endsWithDot) {
-    const candidates = [...CATEGORIES.map(String), ...knownChains, ...NAMED_COMMANDS];
+    const candidates = [
+      ...CATEGORIES.map((c) => `${c}.`),
+      ...knownChains.map((c) => `${c}.`),
+      ...NAMED_COMMANDS
+    ];
     return filterPrefix(candidates, partial);
   }
   const first = completeSegments[0] ?? "";
@@ -822,7 +830,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
       if (!pallets)
         return [];
       const filtered = filterPallets(pallets, category);
-      const candidates = filtered.map((p) => `${first}.${p.name}`);
+      const candidates = filtered.map((p) => `${first}.${p.name}.`);
       return filterPrefix(candidates, currentWord.slice(0, -1));
     }
     if (numComplete === 1 && !endsWithDot) {
@@ -831,7 +839,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
       if (!pallets)
         return [];
       const filtered = filterPallets(pallets, category);
-      const candidates = filtered.map((p) => `${first}.${p.name}`);
+      const candidates = filtered.map((p) => `${first}.${p.name}.`);
       return filterPrefix(candidates, currentWord);
     }
     if (numComplete === 2) {
@@ -852,11 +860,11 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
   if (firstIsChain) {
     const chainName = first;
     if (numComplete === 1 && endsWithDot) {
-      const candidates = CATEGORIES.map((c) => `${first}.${c}`);
+      const candidates = CATEGORIES.map((c) => `${first}.${c}.`);
       return filterPrefix(candidates, currentWord.slice(0, -1));
     }
     if (numComplete === 1 && !endsWithDot) {
-      const candidates = CATEGORIES.map((c) => `${first}.${c}`);
+      const candidates = CATEGORIES.map((c) => `${first}.${c}.`);
       return filterPrefix(candidates, currentWord);
     }
     if (numComplete === 2) {
@@ -868,7 +876,7 @@ async function completeDotpath(currentWord, config, knownChains, precedingWords)
         return [];
       const filtered = filterPallets(pallets, category);
       const prefix = `${first}.${completeSegments[1]}`;
-      const candidates = filtered.map((p) => `${prefix}.${p.name}`);
+      const candidates = filtered.map((p) => `${prefix}.${p.name}.`);
       return filterPrefix(candidates, endsWithDot ? currentWord.slice(0, -1) : currentWord);
     }
     if (numComplete === 3) {
@@ -924,14 +932,14 @@ var init_complete = __esm(() => {
     "inspect"
   ];
   GLOBAL_OPTIONS = ["--chain", "--rpc", "--light-client", "--output", "--help", "--version"];
-  TX_OPTIONS = ["--from", "--dry-run", "--encode", "--ext"];
+  TX_OPTIONS = ["--from", "--dry-run", "--encode", "--ext", "--wait"];
   QUERY_OPTIONS = ["--limit"];
 });
 
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.3.0";
+var version = "1.5.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -1700,9 +1708,10 @@ async function chainDefault(name) {
 
 // src/commands/completions.ts
 var ZSH_SCRIPT = `_dot_completions() {
+  emulate -L zsh
   local -a completions
   local current_word="\${words[CURRENT]}"
-  local preceding=("\${words[@]:1:CURRENT-2}")
+  local preceding=("\${words[2,CURRENT-1]}")
 
   # Build args: -- <current_word> <preceding_words...>
   local args=("__complete" "--" "\${current_word}")
@@ -2132,13 +2141,14 @@ async function showItemHelp(category, target, opts) {
       if (storageItem.keyTypeId != null) {
         console.log(`${BOLD}Usage:${RESET}`);
         console.log(`  dot query.${pallet.name}.${storageItem.name} <key>`);
-        console.log(`  dot query.${pallet.name}.${storageItem.name}              # all entries`);
+        console.log(`  dot query.${pallet.name}.${storageItem.name} --dump       # all entries`);
       } else {
         console.log(`${BOLD}Usage:${RESET}`);
         console.log(`  dot query.${pallet.name}.${storageItem.name}`);
       }
       console.log();
       console.log(`${BOLD}Options:${RESET}`);
+      console.log(`  --dump           Dump all entries of a map (required for keyless map queries)`);
       console.log(`  --limit <n>      Max entries for map queries (0 = unlimited, default: 100)`);
       console.log();
       return;
@@ -2576,13 +2586,14 @@ async function showItemHelp2(category, target, opts) {
       if (storageItem.keyTypeId != null) {
         console.log(`${BOLD}Usage:${RESET}`);
         console.log(`  dot query.${pallet.name}.${storageItem.name} <key>`);
-        console.log(`  dot query.${pallet.name}.${storageItem.name}              # all entries`);
+        console.log(`  dot query.${pallet.name}.${storageItem.name} --dump       # all entries`);
       } else {
         console.log(`${BOLD}Usage:${RESET}`);
         console.log(`  dot query.${pallet.name}.${storageItem.name}`);
       }
       console.log();
       console.log(`${BOLD}Options:${RESET}`);
+      console.log(`  --dump           Dump all entries of a map (required for keyless map queries)`);
       console.log(`  --limit <n>      Max entries for map queries (0 = unlimited, default: 100)`);
       console.log();
       return;
@@ -3256,7 +3267,8 @@ async function parseTypedArg(meta, entry, arg) {
       const matched = variants.find((v) => v.toLowerCase() === arg.toLowerCase());
       if (matched) {
         const variant = entry.value[matched];
-        if (variant.type === "void") {
+        const resolved = variant.type === "lookupEntry" ? variant.value : variant;
+        if (resolved.type === "void") {
           return { type: matched };
         }
       }
@@ -3404,6 +3416,12 @@ async function handleQuery(target, keys, opts) {
     const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, keys);
     const format = opts.output ?? "pretty";
     if (storageItem.type === "map" && parsedKeys.length === 0) {
+      if (!opts.dump) {
+        clientHandle.destroy();
+        await showItemHelp("query", target, { chain: opts.chain, rpc: opts.rpc });
+        console.log(`${DIM}Hint: use --dump to fetch all entries${RESET}`);
+        return;
+      }
       const entries = await storageApi.getEntries();
       const limit = Number(opts.limit);
       const truncated = limit > 0 && entries.length > limit;
@@ -3472,6 +3490,20 @@ import { getViewBuilder as getViewBuilder2 } from "@polkadot-api/view-builder";
 import { Binary as Binary3 } from "polkadot-api";
 init_metadata();
 init_errors();
+function parseWaitLevel(raw) {
+  switch (raw) {
+    case "broadcast":
+      return "broadcast";
+    case "best-block":
+    case "best":
+      return "best-block";
+    case "finalized":
+    case undefined:
+      return "finalized";
+    default:
+      throw new CliError(`Invalid --wait value "${raw}". Valid: broadcast, best-block, best, finalized`);
+  }
+}
 async function handleTx(target, args, opts) {
   if (!target) {
     const config2 = await loadConfig();
@@ -3605,15 +3637,23 @@ async function handleTx(target, args, opts) {
       }
       return;
     }
-    const result = await watchTransaction(tx.signSubmitAndWatch(signer, txOptions));
+    const waitLevel = parseWaitLevel(opts.wait);
+    const result = await watchTransaction(tx.signSubmitAndWatch(signer, txOptions), waitLevel);
     console.log();
     console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
     console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
     console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
     console.log(`  ${BOLD}Tx:${RESET}     ${result.txHash}`);
+    if (result.type === "broadcasted") {
+      console.log(`  ${BOLD}Status:${RESET} ${GREEN}broadcasted${RESET}`);
+      console.log(`  ${DIM}Note: tx was broadcast but not yet included in a block${RESET}`);
+      console.log();
+      return;
+    }
     let dispatchErrorMsg;
     if (result.ok) {
-      console.log(`  ${BOLD}Status:${RESET} ${GREEN}ok${RESET}`);
+      const hint = result.type === "txBestBlocksState" ? ` ${DIM}(best block, not yet finalized)${RESET}` : "";
+      console.log(`  ${BOLD}Status:${RESET} ${GREEN}ok${RESET}${hint}`);
     } else {
       dispatchErrorMsg = formatDispatchError(result.dispatchError);
       console.log(`  ${BOLD}Status:${RESET} ${RED}dispatch error${RESET}`);
@@ -4089,7 +4129,8 @@ async function parseTypedArg2(meta, entry, arg) {
       const matched = variants.find((v) => v.toLowerCase() === arg.toLowerCase());
       if (matched) {
         const variant = entry.value[matched];
-        if (variant.type === "void") {
+        const resolved = variant.type === "lookupEntry" ? variant.value : variant;
+        if (resolved.type === "void") {
           return { type: matched };
         }
       }
@@ -4222,12 +4263,15 @@ function autoDefaultForType(entry) {
   }
   return NO_DEFAULT2;
 }
-function watchTransaction(observable) {
+function watchTransaction(observable, level) {
   const spinner = new Spinner;
   return new Promise((resolve, reject) => {
+    let settled = false;
     spinner.start("Signing...");
-    observable.subscribe({
+    const subscription = observable.subscribe({
       next(event) {
+        if (settled)
+          return;
         switch (event.type) {
           case "signed":
             spinner.succeed("Signed");
@@ -4235,24 +4279,41 @@ function watchTransaction(observable) {
             spinner.start("Broadcasting...");
             break;
           case "broadcasted":
-            spinner.succeed("Broadcasted");
-            spinner.start("In best block...");
+            if (level === "broadcast") {
+              spinner.succeed("Broadcasted");
+              settled = true;
+              subscription.unsubscribe();
+              resolve(event);
+            } else {
+              spinner.succeed("Broadcasted");
+              spinner.start("In best block...");
+            }
             break;
           case "txBestBlocksState":
             if (event.found) {
-              spinner.succeed(`In best block #${event.block.number}`);
-              spinner.start("Finalizing...");
+              if (level === "best-block") {
+                spinner.succeed(`In best block #${event.block.number}`);
+                settled = true;
+                subscription.unsubscribe();
+                resolve(event);
+              } else {
+                spinner.succeed(`In best block #${event.block.number}`);
+                spinner.start("Finalizing...");
+              }
             } else {
               spinner.start("In best block...");
             }
             break;
           case "finalized":
             spinner.succeed(`Finalized in block #${event.block.number}`);
+            settled = true;
             resolve(event);
             break;
         }
       },
       error(err) {
+        if (settled)
+          return;
         spinner.stop();
         reject(err);
       }
@@ -4555,9 +4616,11 @@ if (process.argv[2] === "__complete") {
   registerAccountCommands(cli);
   registerHashCommand(cli);
   registerCompletionsCommand(cli);
-  cli.command("[dotpath] [...args]").option("--from <name>", "Account to sign with (for tx)").option("--dry-run", "Estimate fees without submitting (for tx)").option("--encode", "Encode call to hex without signing (for tx)").option("--ext <json>", "Custom signed extension values as JSON (for tx)").option("--limit <n>", "Max entries to return for map queries (0 = unlimited)", {
+  cli.command("[dotpath] [...args]").option("--from <name>", "Account to sign with (for tx)").option("--dry-run", "Estimate fees without submitting (for tx)").option("--encode", "Encode call to hex without signing (for tx)").option("--ext <json>", "Custom signed extension values as JSON (for tx)").option("-w, --wait <level>", "Resolve at: broadcast, best-block (or best), finalized (for tx)", {
+    default: "finalized"
+  }).option("--limit <n>", "Max entries to return for map queries (0 = unlimited)", {
     default: 100
-  }).action(async (dotpath, args, opts) => {
+  }).option("--dump", "Dump all entries of a storage map (without specifying a key)").action(async (dotpath, args, opts) => {
     if (!dotpath) {
       printHelp();
       return;
@@ -4582,7 +4645,7 @@ if (process.argv[2] === "__complete") {
     }
     switch (parsed.category) {
       case "query":
-        await handleQuery(target, args, { ...handlerOpts, limit: opts.limit });
+        await handleQuery(target, args, { ...handlerOpts, limit: opts.limit, dump: opts.dump });
         break;
       case "tx":
         if (parsed.pallet && /^0x[0-9a-fA-F]+$/.test(parsed.pallet)) {
@@ -4591,7 +4654,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
-            ext: opts.ext
+            ext: opts.ext,
+            wait: opts.wait
           });
         } else {
           await handleTx(target, args, {
@@ -4599,7 +4663,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
-            ext: opts.ext
+            ext: opts.ext,
+            wait: opts.wait
           });
         }
         break;

package/package.json

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