polkadot-cli 1.9.0 → 1.10.0

package/README.md

@@ -617,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

@@ -2172,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.9.0";
+var version = "1.10.0";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -4043,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();
@@ -4131,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;
@@ -4189,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}`);
@@ -4204,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}`);
@@ -5421,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;
@@ -5443,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;
@@ -5494,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.9.0",
+  "version": "1.10.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {