polkadot-cli 0.4.0 → 0.5.0

package/README.md

@@ -1,6 +1,6 @@
 # polkadot-cli
 
-A command-line tool for interacting with Polkadot-ecosystem chains. Query storage, look up constants, inspect metadata, manage accounts, and submit extrinsics — all from your terminal.
+A command-line tool for interacting with Polkadot-ecosystem chains. Manage chains and accounts, query storage, look up constants, inspect metadata, and submit extrinsics — all from your terminal.
 
 Ships with Polkadot as the default chain. Add any Substrate-based chain by pointing to its RPC endpoint.
 
@@ -14,6 +14,48 @@ This installs the `dot` command globally.
 
 ## Usage
 
+### Manage chains
+
+```bash
+# Add a chain
+dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
+dot chain add westend --light-client
+
+# List configured chains
+dot chain list
+
+# Re-fetch metadata after a runtime upgrade
+dot chain update          # updates default chain
+dot chain update kusama   # updates a specific chain
+
+# Set default chain
+dot chain default kusama
+
+# Remove a chain
+dot chain remove westend
+```
+
+### Manage accounts
+
+Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
+
+```bash
+# List all accounts (dev + stored)
+dot account list
+
+# Create a new account (generates a mnemonic)
+dot account create my-validator
+
+# Import from a BIP39 mnemonic
+dot account import treasury --secret "word1 word2 ... word12"
+
+# Import from a hex seed
+dot account import raw-key --secret 0xabcdef...
+
+# Remove an account
+dot account remove my-validator
+```
+
 ### Query storage
 
 ```bash
@@ -52,30 +94,9 @@ dot inspect System
 dot inspect System.Account
 ```
 
-### Manage accounts
-
-Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
-
-```bash
-# List all accounts (dev + stored)
-dot account list
-
-# Create a new account (generates a mnemonic)
-dot account create my-validator
-
-# Import from a BIP39 mnemonic
-dot account import treasury --secret "word1 word2 ... word12"
-
-# Import from a hex seed
-dot account import raw-key --secret 0xabcdef...
-
-# Remove an account
-dot account remove my-validator
-```
-
 ### Submit extrinsics
 
-Build, sign, and submit transactions. Arguments are parsed from metadata — the CLI knows the expected types for each call.
+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.
 
 ```bash
 # Simple remark
@@ -87,29 +108,35 @@ dot tx Balances.transferKeepAlive 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694
 # Estimate fees without submitting
 dot tx Balances.transferKeepAlive 5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty 1000000000000 --from alice --dry-run
 
+# Submit a raw SCALE-encoded call (e.g. from a multisig proposal or another tool)
+dot tx 0x0503008eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48 --from alice
+
 # Batch multiple transfers with Utility.batchAll
 dot tx Utility.batchAll '[{"type":"Balances","value":{"type":"transfer_keep_alive","value":{"dest":"5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty","value":1000000000000}}},{"type":"Balances","value":{"type":"transfer_keep_alive","value":{"dest":"5FLSigC9HGRKVhB9FiEo4Y3koPsNmBmLJbpXg2mp1hXcS59Y","value":2000000000000}}}]' --from alice
 ```
 
-### Manage chains
+Both dry-run and submission display the encoded call hex and a decoded human-readable form:
 
-```bash
-# Add a chain
-dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
-dot chain add westend --light-client
+```
+  Call:   0x0001076465616462656566
+  Decode: System.remark(remark: 0xdeadbeef)
+  Tx:     0xabc123...
+  Block:  #12345678 (0xdef...)
+  Status: ok
+```
 
-# List configured chains
-dot chain list
+#### Custom signed extensions
 
-# Re-fetch metadata after a runtime upgrade
-dot chain update          # updates default chain
-dot chain update kusama   # updates a specific chain
+Chains with non-standard signed extensions (e.g. `people-preview`) are auto-handled:
 
-# Set default chain
-dot chain default kusama
+- `void` → empty bytes
+- `Option<T>` → `None`
+- enum with `Disabled` variant → `Disabled`
 
-# Remove a chain
-dot chain remove westend
+For manual override, use `--ext` with a JSON object:
+
+```bash
+dot tx System.remark 0xdeadbeef --from alice --ext '{"MyExtension":{"value":"..."}}'
 ```
 
 ### Global options

package/dist/cli.mjs

@@ -1,21 +1,5 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
-var __create = Object.create;
-var __getProtoOf = Object.getPrototypeOf;
-var __defProp = Object.defineProperty;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __toESM = (mod, isNodeMode, target) => {
-  target = mod != null ? __create(__getProtoOf(mod)) : {};
-  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
-  for (let key of __getOwnPropNames(mod))
-    if (!__hasOwnProp.call(to, key))
-      __defProp(to, key, {
-        get: () => mod[key],
-        enumerable: true
-      });
-  return to;
-};
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/cli.ts
@@ -388,6 +372,38 @@ function printDocs(docs) {
     console.log(`  ${DIM}${text}${RESET}`);
   }
 }
+var CHECK_MARK = "✓";
+var SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+class Spinner {
+  timer = null;
+  frame = 0;
+  start(msg) {
+    this.stop();
+    if (!isTTY) {
+      console.log(msg);
+      return;
+    }
+    process.stdout.write(`${SPINNER_FRAMES[0]} ${msg}`);
+    this.timer = setInterval(() => {
+      this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+      process.stdout.write(`\r\x1B[K${SPINNER_FRAMES[this.frame]} ${msg}`);
+    }, 80);
+  }
+  stop() {
+    if (this.timer !== null) {
+      clearInterval(this.timer);
+      this.timer = null;
+      this.frame = 0;
+      if (isTTY)
+        process.stdout.write("\r\x1B[K");
+    }
+  }
+  succeed(msg) {
+    this.stop();
+    console.log(`${GREEN}${CHECK_MARK}${RESET} ${msg}`);
+  }
+}
 
 // src/commands/chain.ts
 var CHAIN_HELP = `
@@ -1069,6 +1085,12 @@ async function accountRemove(name) {
 // src/commands/tx.ts
 import { Binary } from "polkadot-api";
 import { getViewBuilder } from "@polkadot-api/view-builder";
+
+// src/core/explorers.ts
+var pjsAppsLink = (rpc, hash) => `https://polkadot.js.org/apps/?rpc=${encodeURIComponent(rpc)}#/explorer/query/${hash}`;
+var papiLink = (rpc, hash) => `https://dev.papi.how/explorer/${hash}#networkId=custom&endpoint=${encodeURIComponent(rpc)}`;
+
+// src/commands/tx.ts
 function registerTxCommand(cli) {
   cli.command("tx [target] [...args]", "Submit an extrinsic (e.g. Balances.transferKeepAlive <dest> <amount>)").option("--from <name>", "Account to sign with (required)").option("--dry-run", "Estimate fees without submitting").option("--ext <json>", `Custom signed extension values as JSON, e.g. '{"ExtName":{"value":...}}'`).action(async (target, args, opts) => {
     if (!target || !opts.from) {
@@ -1133,20 +1155,17 @@ function registerTxCommand(cli) {
         }
         return;
       }
-      console.log("Signing and submitting...");
-      const result = await tx.signAndSubmit(signer, txOptions);
+      const result = await watchTransaction(tx.signSubmitAndWatch(signer, txOptions));
       console.log();
       console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
       console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
       console.log(`  ${BOLD}Tx:${RESET}     ${result.txHash}`);
-      if (result.block) {
-        console.log(`  ${BOLD}Block:${RESET}  #${result.block.number} (${result.block.hash})`);
-      }
-      if (result.dispatchError) {
+      console.log(`  ${BOLD}Block:${RESET}  #${result.block.number} (${result.block.hash})`);
+      if (result.ok) {
+        console.log(`  ${BOLD}Status:${RESET} ${GREEN}ok${RESET}`);
+      } else {
         console.log(`  ${BOLD}Status:${RESET} ${YELLOW}dispatch error${RESET}`);
         console.log(`  ${BOLD}Error:${RESET}  ${result.dispatchError.type}${result.dispatchError.value ? ": " + JSON.stringify(result.dispatchError.value) : ""}`);
-      } else {
-        console.log(`  ${BOLD}Status:${RESET} ${GREEN}ok${RESET}`);
       }
       if (result.events && result.events.length > 0) {
         console.log(`  ${BOLD}Events:${RESET}`);
@@ -1161,6 +1180,13 @@ function registerTxCommand(cli) {
           }
         }
       }
+      const rpcUrl = opts.rpc ?? chainConfig.rpc;
+      if (rpcUrl) {
+        const blockHash = result.block.hash;
+        console.log(`  ${BOLD}Explorer:${RESET}`);
+        console.log(`    ${DIM}PolkadotJS${RESET}  ${pjsAppsLink(rpcUrl, blockHash)}`);
+        console.log(`    ${DIM}PAPI${RESET}        ${papiLink(rpcUrl, blockHash)}`);
+      }
       console.log();
     } finally {
       clientHandle.destroy();
@@ -1489,6 +1515,43 @@ function autoDefaultForType(entry) {
   }
   return NO_DEFAULT;
 }
+function watchTransaction(observable) {
+  const spinner = new Spinner;
+  return new Promise((resolve, reject) => {
+    spinner.start("Signing...");
+    observable.subscribe({
+      next(event) {
+        switch (event.type) {
+          case "signed":
+            spinner.succeed("Signed");
+            console.log(`  ${BOLD}Tx:${RESET}     ${event.txHash}`);
+            spinner.start("Broadcasting...");
+            break;
+          case "broadcasted":
+            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...");
+            } else {
+              spinner.start("In best block...");
+            }
+            break;
+          case "finalized":
+            spinner.stop();
+            resolve(event);
+            break;
+        }
+      },
+      error(err) {
+        spinner.stop();
+        reject(err);
+      }
+    });
+  });
+}
 
 // src/utils/errors.ts
 class CliError2 extends Error {
@@ -1497,6 +1560,8 @@ class CliError2 extends Error {
     this.name = "CliError";
   }
 }
+// package.json
+var version = "0.5.0";
 
 // src/cli.ts
 var cli = cac("dot");
@@ -1513,7 +1578,7 @@ registerConstCommand(cli);
 registerAccountCommands(cli);
 registerTxCommand(cli);
 cli.help();
-cli.version("0.3.0");
+cli.version(version);
 function handleError(err) {
   if (err instanceof CliError2) {
     console.error(`Error: ${err.message}`);
@@ -1524,11 +1589,15 @@ function handleError(err) {
   }
   process.exit(1);
 }
-process.on("unhandledRejection", handleError);
 try {
-  cli.parse();
+  cli.parse(process.argv, { run: false });
   if (!cli.matchedCommandName && !cli.options.help && !cli.options.version) {
     cli.outputHelp();
+  } else {
+    const result = cli.runMatchedCommand();
+    if (result && typeof result.then === "function") {
+      result.then(() => process.exit(0), handleError);
+    }
   }
 } catch (err) {
   handleError(err);

package/package.json

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