polkadot-cli 0.2.1 → 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
@@ -275,6 +259,13 @@ function findPallet(meta, palletName) {
   const pallets = listPallets(meta);
   return pallets.find((p) => p.name.toLowerCase() === palletName.toLowerCase());
 }
+function getSignedExtensions(meta) {
+  const byVersion = meta.unified.extrinsic.signedExtensions;
+  const versionKeys = Object.keys(byVersion);
+  if (versionKeys.length === 0)
+    return [];
+  return byVersion[Number(versionKeys[0])] ?? [];
+}
 function getPalletNames(meta) {
   return meta.unified.pallets.map((p) => p.name);
 }
@@ -381,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 = `
@@ -1061,41 +1084,70 @@ 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").action(async (target, args, opts) => {
+  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) {
-      console.log("Usage: dot tx <Pallet.Call> [...args] --from <account> [--dry-run]");
+      console.log("Usage: dot tx <Pallet.Call|0xCallHex> [...args] --from <account> [--dry-run]");
       console.log("");
       console.log("Examples:");
       console.log("  $ dot tx Balances.transferKeepAlive 5FHn... 1000000000000 --from alice");
       console.log("  $ dot tx System.remark 0xdeadbeef --from alice --dry-run");
+      console.log("  $ dot tx 0x0001076465616462656566 --from alice");
       return;
     }
+    const isRawCall = /^0x[0-9a-fA-F]+$/.test(target);
     const config = await loadConfig();
     const { name: chainName, chain: chainConfig } = resolveChain(config, opts.chain);
-    const { pallet, item: callName } = parseTarget(target);
     const signer = await resolveAccountSigner(opts.from);
     const clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
     try {
       const meta = await getOrFetchMetadata(chainName, clientHandle);
-      const palletNames = getPalletNames(meta);
-      const palletInfo = findPallet(meta, pallet);
-      if (!palletInfo) {
-        throw new Error(suggestMessage("pallet", pallet, palletNames));
-      }
-      const callInfo = palletInfo.calls.find((c) => c.name.toLowerCase() === callName.toLowerCase());
-      if (!callInfo) {
-        const callNames = palletInfo.calls.map((c) => c.name);
-        throw new Error(suggestMessage(`call in ${palletInfo.name}`, callName, callNames));
-      }
-      const callData = parseCallArgs(meta, palletInfo.name, callInfo.name, args);
+      const userExtOverrides = parseExtOption(opts.ext);
+      const customSignedExtensions = buildCustomSignedExtensions(meta, userExtOverrides);
+      const txOptions = Object.keys(customSignedExtensions).length > 0 ? { customSignedExtensions } : undefined;
       const unsafeApi = clientHandle.client.getUnsafeApi();
-      const tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
+      let tx;
+      let callHex;
+      if (isRawCall) {
+        if (args.length > 0) {
+          throw new Error(`Extra arguments are not allowed when submitting a raw call hex.
+` + "Usage: dot tx 0x<call_hex> --from <account>");
+        }
+        const callBinary = Binary.fromHex(target);
+        tx = await unsafeApi.txFromCallData(callBinary);
+        callHex = target;
+      } else {
+        const { pallet, item: callName } = parseTarget(target);
+        const palletNames = getPalletNames(meta);
+        const palletInfo = findPallet(meta, pallet);
+        if (!palletInfo) {
+          throw new Error(suggestMessage("pallet", pallet, palletNames));
+        }
+        const callInfo = palletInfo.calls.find((c) => c.name.toLowerCase() === callName.toLowerCase());
+        if (!callInfo) {
+          const callNames = palletInfo.calls.map((c) => c.name);
+          throw new Error(suggestMessage(`call in ${palletInfo.name}`, callName, callNames));
+        }
+        const callData = parseCallArgs(meta, palletInfo.name, callInfo.name, args);
+        tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
+        const encodedCall = await tx.getEncodedData();
+        callHex = encodedCall.asHex();
+      }
+      const decodedStr = decodeCall(meta, callHex);
       if (opts.dryRun) {
         const signerAddress = toSs58(signer.publicKey);
-        console.log(`  ${BOLD}From:${RESET} ${opts.from} (${signerAddress})`);
+        console.log(`  ${BOLD}From:${RESET}   ${opts.from} (${signerAddress})`);
+        console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
+        console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
         try {
-          const fees = await tx.getEstimatedFees(signer.publicKey);
+          const fees = await tx.getEstimatedFees(signer.publicKey, txOptions);
           console.log(`  ${BOLD}Estimated fees:${RESET} ${fees}`);
         } catch (err) {
           console.log(`  ${BOLD}Estimated fees:${RESET} ${YELLOW}unable to estimate${RESET}`);
@@ -1103,18 +1155,17 @@ function registerTxCommand(cli) {
         }
         return;
       }
-      console.log("Signing and submitting...");
-      const result = await tx.signAndSubmit(signer);
+      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}`);
@@ -1129,12 +1180,108 @@ 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();
     }
   });
 }
+function decodeCall(meta, callHex) {
+  try {
+    const viewBuilder = getViewBuilder(meta.lookup);
+    const decoded = viewBuilder.callDecoder(callHex);
+    const palletName = decoded.pallet.value.name;
+    const callName = decoded.call.value.name;
+    const argsStr = formatDecodedArgs(decoded.args.value);
+    return `${palletName}.${callName}${argsStr}`;
+  } catch {
+    return "(unable to decode)";
+  }
+}
+function formatDecodedArgs(decoded) {
+  return formatDecoded(decoded);
+}
+function formatDecoded(d) {
+  switch (d.codec) {
+    case "_void":
+      return "";
+    case "bool":
+      return d.value.toString();
+    case "str":
+    case "char":
+      return d.value;
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i8":
+    case "i16":
+    case "i32":
+    case "compactNumber":
+      return d.value.toString();
+    case "u64":
+    case "u128":
+    case "u256":
+    case "i64":
+    case "i128":
+    case "i256":
+    case "compactBn":
+      return d.value.toString();
+    case "bitSequence":
+      return `0x${Buffer.from(d.value.bytes).toString("hex")}`;
+    case "AccountId":
+      return d.value.address;
+    case "ethAccount":
+      return d.value;
+    case "Bytes":
+      return d.value;
+    case "BytesArray":
+      return d.value;
+    case "Enum": {
+      const inner = formatDecoded(d.value.value);
+      if (!inner)
+        return d.value.type;
+      return `${d.value.type}(${inner})`;
+    }
+    case "Struct": {
+      const entries = Object.entries(d.value);
+      if (entries.length === 0)
+        return " {}";
+      const fields = entries.map(([k, v]) => `${k}: ${formatDecoded(v)}`).join(", ");
+      return ` { ${fields} }`;
+    }
+    case "Tuple": {
+      const items = d.value.map(formatDecoded).join(", ");
+      return `(${items})`;
+    }
+    case "Option": {
+      if (d.value.codec === "_void")
+        return "None";
+      return formatDecoded(d.value);
+    }
+    case "Result": {
+      if (d.value.success) {
+        return `Ok(${formatDecoded(d.value.value)})`;
+      }
+      return `Err(${formatDecoded(d.value.value)})`;
+    }
+    case "Sequence":
+    case "Array": {
+      const items = d.value.map(formatDecoded);
+      if (items.length === 0)
+        return "[]";
+      return `[${items.join(", ")}]`;
+    }
+    default:
+      return String(d.value ?? "");
+  }
+}
 function formatEventValue(v) {
   if (typeof v === "bigint")
     return v.toString();
@@ -1301,6 +1448,110 @@ function parsePrimitive(prim, arg) {
       return parseValue(arg);
   }
 }
+var PAPI_BUILTIN_EXTENSIONS = new Set([
+  "CheckNonZeroSender",
+  "CheckSpecVersion",
+  "CheckTxVersion",
+  "CheckGenesis",
+  "CheckMortality",
+  "CheckNonce",
+  "CheckWeight",
+  "ChargeTransactionPayment",
+  "ChargeAssetTxPayment",
+  "CheckMetadataHash",
+  "StorageWeightReclaim",
+  "PrevalidateAttests"
+]);
+function parseExtOption(ext) {
+  if (!ext)
+    return {};
+  try {
+    const parsed = JSON.parse(ext);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(`--ext must be a JSON object, e.g. '{"ExtName":{"value":...}}'`);
+    }
+    return parsed;
+  } catch (err) {
+    if (err.message?.startsWith("--ext"))
+      throw err;
+    throw new Error(`Failed to parse --ext JSON: ${err.message}
+` + `Expected format: '{"ExtName":{"value":...}}'`);
+  }
+}
+var NO_DEFAULT = Symbol("no-default");
+function buildCustomSignedExtensions(meta, userOverrides) {
+  const result = {};
+  const extensions = getSignedExtensions(meta);
+  for (const ext of extensions) {
+    if (PAPI_BUILTIN_EXTENSIONS.has(ext.identifier))
+      continue;
+    if (ext.identifier in userOverrides) {
+      result[ext.identifier] = userOverrides[ext.identifier];
+      continue;
+    }
+    const valueEntry = meta.lookup(ext.type);
+    const addEntry = meta.lookup(ext.additionalSigned);
+    const value = autoDefaultForType(valueEntry);
+    const add = autoDefaultForType(addEntry);
+    if (value !== NO_DEFAULT || add !== NO_DEFAULT) {
+      result[ext.identifier] = {
+        ...value !== NO_DEFAULT ? { value } : {},
+        ...add !== NO_DEFAULT ? { additionalSigned: add } : {}
+      };
+    }
+  }
+  return result;
+}
+function autoDefaultForType(entry) {
+  if (entry.type === "void")
+    return new Uint8Array([]);
+  if (entry.type === "option")
+    return;
+  if (entry.type === "enum") {
+    const variants = entry.value;
+    if ("Disabled" in variants) {
+      return { type: "Disabled", value: undefined };
+    }
+  }
+  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 {
@@ -1309,6 +1560,8 @@ class CliError2 extends Error {
     this.name = "CliError";
   }
 }
+// package.json
+var version = "0.5.0";
 
 // src/cli.ts
 var cli = cac("dot");
@@ -1325,7 +1578,7 @@ registerConstCommand(cli);
 registerAccountCommands(cli);
 registerTxCommand(cli);
 cli.help();
-cli.version("0.2.1");
+cli.version(version);
 function handleError(err) {
   if (err instanceof CliError2) {
     console.error(`Error: ${err.message}`);
@@ -1336,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.2.1",
+  "version": "0.5.0",
   "description": "CLI tool for querying Polkadot-ecosystem on-chain state",
   "type": "module",
   "bin": {