polkadot-cli 1.8.1 → 1.10.0

package/README.md

@@ -1,3 +1,4 @@
+[![npm version](https://img.shields.io/npm/v/polkadot-cli)](https://www.npmjs.com/package/polkadot-cli)
 [![codecov](https://codecov.io/gh/peetzweg/polkadot-cli/branch/main/graph/badge.svg)](https://codecov.io/gh/peetzweg/polkadot-cli)
 
 # polkadot-cli
@@ -309,12 +310,32 @@ dot query System.Number --output json | jq '.+1'
 dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 ```
 
+#### Partial key queries
+
+For storage maps with multiple keys (NMaps), you can provide fewer keys than
+expected to retrieve all entries matching that prefix. This uses the chain's
+prefix-based iteration and does not require `--dump`.
+
+```bash
+# Full key — returns a single value
+dot query Staking.ErasStakers 100 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
+
+# Partial key — returns all entries matching the first key
+dot query Staking.ErasStakers 100
+
+# No keys — requires --dump (safety net for large maps)
+dot query Staking.ErasStakers --dump --limit 10
+```
+
+The `--limit` option applies to partial key results just like it does for
+`--dump` (default: 100, use `--limit 0` for unlimited).
+
 #### Output formatting
 
 Query results automatically convert on-chain types for readability:
 
 - **BigInt** values (e.g. balances) render as decimal strings
-- **Binary** fields (e.g. token `name`, `symbol`) render as text when valid UTF-8, or as `0x`-prefixed hex otherwise
+- **Binary** fields (e.g. token `name`, `symbol`) render as text when the value contains only printable characters, or as `0x`-prefixed hex otherwise (values containing control characters, Private Use Area code points, or invalid UTF-8 sequences always fall back to hex)
 - **Uint8Array** values render as `0x`-prefixed hex
 
 ```bash
@@ -596,6 +617,40 @@ For manual override, use `--ext` with a JSON object:
 dot tx System.remark 0xdeadbeef --from alice --ext '{"MyExtension":{"value":"..."}}'
 ```
 
+#### Transaction options
+
+Override low-level transaction parameters. Useful for rapid-fire submission (custom nonce), priority fees (tip), or controlling transaction lifetime (mortality).
+
+| Flag | Value | Description |
+|------|-------|-------------|
+| `--nonce <n>` | non-negative integer | Override the auto-detected nonce |
+| `--tip <amount>` | non-negative integer (planck) | Priority tip for the transaction pool |
+| `--mortality <spec>` | `immortal` or period (min 4) | Transaction mortality window |
+| `--at <block>` | `best`, `finalized`, or 0x-prefixed block hash | Block state to validate against |
+
+```bash
+# Fire-and-forget: submit two txs in rapid succession with manual nonces
+dot tx System.remark 0xdead --from alice --nonce 0 --wait broadcast
+dot tx System.remark 0xbeef --from alice --nonce 1 --wait broadcast
+
+# Add a priority tip (in planck)
+dot tx Balances.transferKeepAlive 5FHneW46... 1000000000000 --from alice --tip 1000000
+
+# Submit an immortal transaction (no expiry)
+dot tx System.remark 0xdead --from alice --mortality immortal
+
+# Set a custom mortality period (rounds up to nearest power of two)
+dot tx System.remark 0xdead --from alice --mortality 128
+
+# Validate against the best (not finalized) block
+dot tx System.remark 0xdead --from alice --at best
+
+# Combine: rapid-fire with tip and broadcast-only
+dot tx System.remark 0xdead --from alice --nonce 5 --tip 500000 --wait broadcast
+```
+
+When set, nonce / tip / mortality / at are shown in both `--dry-run` and submission output. These flags are silently ignored with `--encode`, `--yaml`, and `--json` (which return before signing).
+
 ### File-based commands
 
 Run any `dot` command from a YAML or JSON file. Especially useful for complex calls like XCM messages that are hard to construct inline.

package/dist/cli.mjs

@@ -387,14 +387,35 @@ var init_accounts = __esm(() => {
   DEV_NAMES = ["alice", "bob", "charlie", "dave", "eve", "ferdie"];
 });
 
+// src/utils/binary-display.ts
+function isReadableText(text) {
+  for (let i = 0;i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code <= 31 && code !== 9 && code !== 10 && code !== 13)
+      return false;
+    if (code === 127)
+      return false;
+    if (code >= 128 && code <= 159)
+      return false;
+    if (code === 65533)
+      return false;
+    if (code >= 57344 && code <= 63743)
+      return false;
+  }
+  return true;
+}
+function binaryToDisplay(value) {
+  const text = value.asText();
+  return isReadableText(text) ? text : value.asHex();
+}
+
 // src/core/output.ts
 import { Binary } from "polkadot-api";
 function replacer(_key, value) {
   if (typeof value === "bigint")
     return value.toString();
   if (value instanceof Binary) {
-    const text = value.asText();
-    return text.includes("�") ? value.asHex() : text;
+    return binaryToDisplay(value);
   }
   if (value instanceof Uint8Array)
     return `0x${Buffer.from(value).toString("hex")}`;
@@ -2151,14 +2172,24 @@ var init_complete = __esm(() => {
     "inspect"
   ];
   GLOBAL_OPTIONS = ["--chain", "--rpc", "--light-client", "--output", "--help", "--version"];
-  TX_OPTIONS = ["--from", "--dry-run", "--encode", "--ext", "--wait"];
+  TX_OPTIONS = [
+    "--from",
+    "--dry-run",
+    "--encode",
+    "--ext",
+    "--wait",
+    "--nonce",
+    "--tip",
+    "--mortality",
+    "--at"
+  ];
   QUERY_OPTIONS = ["--limit"];
 });
 
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.8.1";
+var version = "1.10.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -3927,14 +3958,15 @@ async function handleQuery(target, keys, opts) {
     ];
     const parsedKeys = await parseStorageKeys(meta, palletInfo.name, storageItem, effectiveKeys);
     const format = opts.output ?? "pretty";
-    if (storageItem.type === "map" && parsedKeys.length === 0) {
-      if (!opts.dump) {
+    const expectedLen = storageItem.type === "map" && storageItem.keyTypeId != null ? meta.builder.buildStorage(palletInfo.name, storageItem.name).len : 0;
+    if (storageItem.type === "map" && parsedKeys.length < expectedLen) {
+      if (parsedKeys.length === 0 && !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 entries = await storageApi.getEntries(...parsedKeys);
       const limit = Number(opts.limit);
       const truncated = limit > 0 && entries.length > limit;
       const display = truncated ? entries.slice(0, limit) : entries;
@@ -3978,18 +4010,18 @@ async function parseStorageKeys(meta, palletName2, storageItem, args) {
     throw new Error(`${palletName2}.${storageItem.name} key expects ${typeDesc}
 ` + `  Pass 1 argument. Got ${args.length}.`);
   }
-  if (args.length !== len) {
+  if (args.length > len) {
     let typeDesc;
     if (keyEntry.type === "tuple") {
       typeDesc = keyEntry.value.map((e) => describeType(meta.lookup, e.id)).join(", ");
     } else {
       typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
     }
-    throw new Error(`${palletName2}.${storageItem.name} expects ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
+    throw new Error(`${palletName2}.${storageItem.name} expects at most ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
   }
   if (keyEntry.type === "tuple") {
     const entries = keyEntry.value;
-    return Promise.all(entries.map((entry, i) => parseTypedArg(meta, entry, args[i])));
+    return Promise.all(entries.slice(0, args.length).map((entry, i) => parseTypedArg(meta, entry, args[i])));
   }
   return Promise.all(args.map((arg) => parseTypedArg(meta, keyEntry, arg)));
 }
@@ -4021,6 +4053,50 @@ function parseWaitLevel(raw) {
       throw new CliError(`Invalid --wait value "${raw}". Valid: broadcast, best-block, best, finalized`);
   }
 }
+function parseNonceOption(raw) {
+  if (raw === undefined)
+    return;
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 0) {
+    throw new CliError(`Invalid --nonce value "${raw}". Must be a non-negative integer.`);
+  }
+  return n;
+}
+function parseTipOption(raw) {
+  if (raw === undefined)
+    return;
+  try {
+    const t = BigInt(raw);
+    if (t < 0n) {
+      throw new CliError(`Invalid --tip value "${raw}". Must be a non-negative integer.`);
+    }
+    return t;
+  } catch (err) {
+    if (err instanceof CliError)
+      throw err;
+    throw new CliError(`Invalid --tip value "${raw}". Must be a non-negative integer.`);
+  }
+}
+function parseMortalityOption(raw) {
+  if (raw === undefined)
+    return;
+  if (raw === "immortal")
+    return { mortal: false };
+  const n = Number(raw);
+  if (!Number.isInteger(n) || n < 4) {
+    throw new CliError(`Invalid --mortality value "${raw}". Use "immortal" or a period number (minimum 4).`);
+  }
+  return { mortal: true, period: n };
+}
+function parseAtOption(raw) {
+  if (raw === undefined)
+    return;
+  if (raw === "best" || raw === "finalized")
+    return raw;
+  if (/^0x[0-9a-fA-F]{64}$/.test(raw))
+    return raw;
+  throw new CliError(`Invalid --at value "${raw}". Use "best", "finalized", or a 0x-prefixed 32-byte block hash.`);
+}
 async function handleTx(target, args, opts) {
   if (!target) {
     const config2 = await loadConfig();
@@ -4109,10 +4185,25 @@ async function handleTx(target, args, opts) {
     }
     let unsafeApi;
     let txOptions;
+    const nonce = parseNonceOption(opts.nonce);
+    const tip = parseTipOption(opts.tip);
+    const mortality = parseMortalityOption(opts.mortality);
+    const at = parseAtOption(opts.at);
     if (!decodeOnly) {
       const userExtOverrides = parseExtOption(opts.ext);
       const customSignedExtensions = buildCustomSignedExtensions(meta, userExtOverrides);
-      txOptions = Object.keys(customSignedExtensions).length > 0 ? { customSignedExtensions } : undefined;
+      const built = {};
+      if (Object.keys(customSignedExtensions).length > 0)
+        built.customSignedExtensions = customSignedExtensions;
+      if (nonce !== undefined)
+        built.nonce = nonce;
+      if (tip !== undefined)
+        built.tip = tip;
+      if (mortality !== undefined)
+        built.mortality = mortality;
+      if (at !== undefined)
+        built.at = at;
+      txOptions = Object.keys(built).length > 0 ? built : undefined;
       unsafeApi = clientHandle?.client.getUnsafeApi();
     }
     let tx;
@@ -4167,6 +4258,14 @@ async function handleTx(target, args, opts) {
       console.log(`  ${BOLD}From:${RESET}   ${opts.from} (${signerAddress})`);
       console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
       console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
+      if (nonce !== undefined)
+        console.log(`  ${BOLD}Nonce:${RESET} ${nonce}`);
+      if (tip !== undefined)
+        console.log(`  ${BOLD}Tip:${RESET}   ${tip}`);
+      if (mortality !== undefined)
+        console.log(`  ${BOLD}Mortality:${RESET} ${mortality.mortal ? `mortal (period ${mortality.period})` : "immortal"}`);
+      if (at !== undefined)
+        console.log(`  ${BOLD}At:${RESET}    ${at}`);
       try {
         const fees = await tx.getEstimatedFees(signer?.publicKey, txOptions);
         console.log(`  ${BOLD}Estimated fees:${RESET} ${fees}`);
@@ -4182,6 +4281,14 @@ async function handleTx(target, args, opts) {
     console.log(`  ${BOLD}Chain:${RESET}  ${chainName}`);
     console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
     console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
+    if (nonce !== undefined)
+      console.log(`  ${BOLD}Nonce:${RESET} ${nonce}`);
+    if (tip !== undefined)
+      console.log(`  ${BOLD}Tip:${RESET}   ${tip}`);
+    if (mortality !== undefined)
+      console.log(`  ${BOLD}Mortality:${RESET} ${mortality.mortal ? `mortal (period ${mortality.period})` : "immortal"}`);
+    if (at !== undefined)
+      console.log(`  ${BOLD}At:${RESET}    ${at}`);
     console.log(`  ${BOLD}Tx:${RESET}     ${result.txHash}`);
     if (result.type === "broadcasted") {
       console.log(`  ${BOLD}Status:${RESET} ${GREEN}broadcasted${RESET}`);
@@ -4452,8 +4559,7 @@ function formatEventValue(v) {
   if (v === null || v === undefined)
     return "null";
   if (v instanceof Binary3) {
-    const text = v.asText();
-    return text.includes("�") ? v.asHex() : text;
+    return binaryToDisplay(v);
   }
   return JSON.stringify(v, (_k, val) => typeof val === "bigint" ? val.toString() : val);
 }
@@ -5400,7 +5506,7 @@ if (process.argv[2] === "__complete") {
     default: "finalized"
   }).option("--limit <n>", "Max entries to return for map queries (0 = unlimited)", {
     default: 100
-  }).option("--dump", "Dump all entries of a storage map (without specifying a key)").option("--var <kv>", "Template variable for file input (KEY=VALUE, repeatable)").action(async (dotpath, args, opts) => {
+  }).option("--dump", "Dump all entries of a storage map (without specifying a key)").option("--var <kv>", "Template variable for file input (KEY=VALUE, repeatable)").option("--nonce <n>", "Custom nonce for manual tx sequencing (for tx)").option("--tip <amount>", "Tip to prioritize transaction (for tx)").option("--mortality <spec>", '"immortal" or period number (for tx)').option("--at <block>", 'Block hash, "best", or "finalized" to validate against (for tx)').action(async (dotpath, args, opts) => {
     if (!dotpath) {
       printHelp();
       return;
@@ -5422,6 +5528,10 @@ if (process.argv[2] === "__complete") {
             json: opts.json,
             ext: opts.ext,
             wait: opts.wait,
+            nonce: opts.nonce,
+            tip: opts.tip,
+            mortality: opts.mortality,
+            at: opts.at,
             parsedArgs: cmd.args
           });
           break;
@@ -5473,31 +5583,28 @@ if (process.argv[2] === "__complete") {
       case "query":
         await handleQuery(target, args, { ...handlerOpts, limit: opts.limit, dump: opts.dump });
         break;
-      case "tx":
+      case "tx": {
+        const txOpts = {
+          ...handlerOpts,
+          from: opts.from,
+          dryRun: opts.dryRun,
+          encode: opts.encode,
+          yaml: opts.yaml,
+          json: opts.json,
+          ext: opts.ext,
+          wait: opts.wait,
+          nonce: opts.nonce,
+          tip: opts.tip,
+          mortality: opts.mortality,
+          at: opts.at
+        };
         if (parsed.pallet && /^0x[0-9a-fA-F]+$/.test(parsed.pallet)) {
-          await handleTx(parsed.pallet, args, {
-            ...handlerOpts,
-            from: opts.from,
-            dryRun: opts.dryRun,
-            encode: opts.encode,
-            yaml: opts.yaml,
-            json: opts.json,
-            ext: opts.ext,
-            wait: opts.wait
-          });
+          await handleTx(parsed.pallet, args, txOpts);
         } else {
-          await handleTx(target, args, {
-            ...handlerOpts,
-            from: opts.from,
-            dryRun: opts.dryRun,
-            encode: opts.encode,
-            yaml: opts.yaml,
-            json: opts.json,
-            ext: opts.ext,
-            wait: opts.wait
-          });
+          await handleTx(target, args, txOpts);
         }
         break;
+      }
       case "const":
         await handleConst(target, handlerOpts);
         break;

package/package.json

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