polkadot-cli 1.7.0 → 1.8.1

package/README.md

@@ -21,6 +21,7 @@ Ships with Polkadot and all system parachains preconfigured with multiple fallba
 - ✅ Runtime API calls — `dot apis.Core.version`
 - ✅ Batteries included — all system parachains and testnets already setup to be used
 - ✅ File-based commands — run any command from a YAML/JSON file with variable substitution
+- ✅ Parachain sovereign accounts — derive child and sibling addresses from a parachain ID
 
 ### Preconfigured chains
 
@@ -496,6 +497,28 @@ dot tx Balances.transfer_keep_alive 5FHneW46... 1000000000000 --encode
 dot tx Sudo.sudo $(dot tx System.remark 0xcafe --encode) --from alice
 ```
 
+#### Decode call data to YAML / JSON
+
+Decode a hex-encoded call into a YAML or JSON file that is compatible with [file-based commands](#file-based-commands). This is useful for inspecting opaque call data, sharing human-readable transaction definitions, or editing parameters before re-submitting. Works offline from cached metadata and does not require `--from`.
+
+```bash
+# Decode a raw hex call to YAML
+dot tx.0x0001076465616462656566 --yaml
+
+# Decode a raw hex call to JSON
+dot tx.0x0001076465616462656566 --json
+
+# Encode a named call and output as YAML
+dot tx.System.remark 0xdeadbeef --yaml
+
+# Round-trip: encode to hex, decode to YAML, re-encode from file
+dot tx.System.remark 0xdeadbeef --encode           # 0x0001076465616462656566
+dot tx.0x0001076465616462656566 --yaml > remark.yaml
+dot ./remark.yaml --encode                          # same hex
+```
+
+`--yaml` / `--json` are mutually exclusive with each other and with `--encode` and `--dry-run`.
+
 Both dry-run and submission display the encoded call hex and a decoded human-readable form:
 
 ```
@@ -750,7 +773,15 @@ tx:
       value: ${AMOUNT}
 ```
 
-All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--output`, etc. behave identically to inline commands.
+Hex values passed via `--var` are preserved as-is, including leading zeros. This is important for encoded call data in XCM `Transact` instructions or similar byte-array fields:
+
+```bash
+# Encode a remark, then embed it in an XCM Transact via --var
+CALL=$(dot tx.System.remark 0xdead --encode)
+dot ./xcm-transact.yaml --var CALL=$CALL --encode
+```
+
+All existing flags work with file input — `--chain` overrides the file's `chain:` field, `--from`, `--dry-run`, `--encode`, `--yaml`, `--json`, `--output`, etc. behave identically to inline commands.
 
 ### Compute hashes
 
@@ -775,6 +806,32 @@ dot hash blake2b256 0xdeadbeef --output json
 
 Run `dot hash` with no arguments to see all available algorithms.
 
+### Parachain sovereign accounts
+
+Derive the sovereign account addresses for a parachain. These are deterministic accounts derived from a parachain ID — no chain connection required.
+
+- **Child** accounts represent a parachain on the relay chain (prefix `"para"`)
+- **Sibling** accounts represent a parachain on another parachain (prefix `"sibl"`)
+
+```bash
+# Show both child and sibling accounts
+dot parachain 1000
+
+# Show only the child (relay chain) account
+dot parachain 2004 --type child
+
+# Show only the sibling (parachain-to-parachain) account
+dot parachain 2004 --type sibling
+
+# Use Polkadot SS58 prefix (default: 42)
+dot parachain 1000 --prefix 0
+
+# JSON output
+dot parachain 1000 --output json
+```
+
+Run `dot parachain` with no arguments to see usage and examples.
+
 ### Getting help
 
 Every command supports `--help` to show its detailed usage, available actions, and examples:

package/dist/cli.mjs

@@ -966,6 +966,7 @@ function parseValue(arg) {
 // src/commands/tx.ts
 import { getViewBuilder } from "@polkadot-api/view-builder";
 import { Binary as Binary2 } from "polkadot-api";
+import { stringify as stringifyYaml } from "yaml";
 async function parseStructArgs(meta, fields, args, callLabel) {
   const fieldNames = Object.keys(fields);
   if (args.length !== fieldNames.length) {
@@ -1967,6 +1968,12 @@ async function generateCompletions(currentWord, precedingWords) {
   if (firstArg === "hash") {
     return filterPrefix(getAlgorithmNames(), currentWord);
   }
+  if (firstArg === "parachain") {
+    if (prevWord === "--type") {
+      return filterPrefix(["child", "sibling"], currentWord);
+    }
+    return [];
+  }
   return completeDotpath(currentWord, config, knownChains, precedingWords);
 }
 function detectCategory(words, _knownChains) {
@@ -2130,7 +2137,7 @@ var init_complete = __esm(() => {
     apis: "apis",
     api: "apis"
   };
-  NAMED_COMMANDS = ["chain", "account", "inspect", "hash", "completions"];
+  NAMED_COMMANDS = ["chain", "account", "inspect", "hash", "parachain", "completions"];
   CHAIN_SUBCOMMANDS = ["add", "remove", "update", "list", "default"];
   ACCOUNT_SUBCOMMANDS = [
     "add",
@@ -2151,7 +2158,7 @@ var init_complete = __esm(() => {
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "1.7.0";
+var version = "1.8.1";
 
 // src/commands/account.ts
 init_accounts_store();
@@ -3433,6 +3440,7 @@ async function showItemHelp2(category, target, opts) {
 init_hash();
 init_output();
 init_errors();
+import { readFile as readFile3 } from "node:fs/promises";
 async function resolveInput(data, opts) {
   const sources = [data !== undefined, !!opts.file, !!opts.stdin].filter(Boolean).length;
   if (sources > 1) {
@@ -3442,26 +3450,15 @@ async function resolveInput(data, opts) {
     throw new CliError("No input provided. Pass data as argument, or use --file or --stdin");
   }
   if (opts.file) {
-    const buf = await Bun.file(opts.file).arrayBuffer();
+    const buf = await readFile3(opts.file);
     return new Uint8Array(buf);
   }
   if (opts.stdin) {
-    const reader = Bun.stdin.stream().getReader();
     const chunks = [];
-    while (true) {
-      const { done, value } = await reader.read();
-      if (done)
-        break;
-      chunks.push(value);
-    }
-    const totalLen = chunks.reduce((sum, c) => sum + c.length, 0);
-    const result = new Uint8Array(totalLen);
-    let offset = 0;
-    for (const chunk of chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk);
     }
-    return result;
+    return new Uint8Array(Buffer.concat(chunks));
   }
   return parseInputData(data);
 }
@@ -3765,6 +3762,97 @@ function registerInspectCommand(cli) {
   });
 }
 
+// src/commands/parachain.ts
+init_accounts();
+init_output();
+
+// src/core/parachain.ts
+var SOVEREIGN_ACCOUNT_TYPES = ["child", "sibling"];
+var PREFIXES = {
+  child: new Uint8Array([112, 97, 114, 97]),
+  sibling: new Uint8Array([115, 105, 98, 108])
+};
+function deriveSovereignAccount(paraId, type) {
+  const result = new Uint8Array(32);
+  result.set(PREFIXES[type], 0);
+  new DataView(result.buffer).setUint32(4, paraId, true);
+  return result;
+}
+function isValidParaId(value) {
+  return Number.isInteger(value) && value >= 0 && value <= 4294967295;
+}
+
+// src/commands/parachain.ts
+init_errors();
+function printParachainHelp() {
+  console.log(`${BOLD}Usage:${RESET} dot parachain <paraId> [options]
+`);
+  console.log(`${BOLD}Description:${RESET}`);
+  console.log(`  Derive sovereign account addresses for a parachain.
+`);
+  console.log(`  ${DIM}Child accounts represent a parachain on the relay chain.${RESET}`);
+  console.log(`  ${DIM}Sibling accounts represent a parachain on another parachain.${RESET}
+`);
+  console.log(`${BOLD}Options:${RESET}`);
+  console.log(`  ${CYAN}--type <child|sibling>${RESET}  ${DIM}Account type (default: both)${RESET}`);
+  console.log(`  ${CYAN}--prefix <N>${RESET}             ${DIM}SS58 prefix (default: 42)${RESET}`);
+  console.log(`  ${CYAN}--output json${RESET}            ${DIM}Output as JSON${RESET}`);
+  console.log(`
+${BOLD}Examples:${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 1000${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 2004 --prefix 0${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 1000 --type sibling${RESET}`);
+  console.log(`  ${DIM}$ dot parachain 2000 --output json${RESET}`);
+}
+function validateType(type) {
+  const lower = type.toLowerCase();
+  if (lower === "child" || lower === "sibling")
+    return lower;
+  throw new CliError(`Unknown account type "${type}". Valid types: child, sibling.`);
+}
+function registerParachainCommand(cli) {
+  cli.command("parachain [paraId]", "Derive parachain sovereign accounts").option("--type <type>", "Account type: child, sibling (default: both)").option("--prefix <number>", "SS58 prefix for address encoding (default: 42)").action(async (paraIdStr, opts) => {
+    if (!paraIdStr) {
+      printParachainHelp();
+      return;
+    }
+    const paraId = Number(paraIdStr);
+    if (!isValidParaId(paraId)) {
+      throw new CliError(`Invalid parachain ID "${paraIdStr}". Must be a non-negative integer (0 to 4294967295).`);
+    }
+    const prefix = opts.prefix != null ? Number(opts.prefix) : 42;
+    if (Number.isNaN(prefix) || prefix < 0) {
+      throw new CliError(`Invalid prefix "${opts.prefix}". Must be a non-negative integer.`);
+    }
+    const types = opts.type ? [validateType(opts.type)] : SOVEREIGN_ACCOUNT_TYPES;
+    const format = opts.output ?? "pretty";
+    if (format === "json") {
+      const result = { paraId, prefix };
+      for (const type of types) {
+        const accountId = deriveSovereignAccount(paraId, type);
+        result[type] = {
+          publicKey: publicKeyToHex(accountId),
+          ss58: toSs58(accountId, prefix)
+        };
+      }
+      console.log(formatJson(result));
+    } else {
+      printHeading(`Parachain ${paraId} — Sovereign Accounts`);
+      for (const type of types) {
+        const accountId = deriveSovereignAccount(paraId, type);
+        const hex = publicKeyToHex(accountId);
+        const ss58 = toSs58(accountId, prefix);
+        const label = type.charAt(0).toUpperCase() + type.slice(1);
+        console.log(`  ${BOLD}${label}:${RESET}`);
+        console.log(`    ${BOLD}Public Key:${RESET}  ${hex}`);
+        console.log(`    ${BOLD}SS58:${RESET}        ${ss58}`);
+        console.log(`    ${BOLD}Prefix:${RESET}      ${prefix}`);
+        console.log();
+      }
+    }
+  });
+}
+
 // src/commands/query.ts
 init_store();
 init_client();
@@ -3918,6 +4006,7 @@ init_errors();
 init_focused_inspect();
 import { getViewBuilder as getViewBuilder2 } from "@polkadot-api/view-builder";
 import { Binary as Binary3 } from "polkadot-api";
+import { stringify as stringifyYaml2 } from "yaml";
 function parseWaitLevel(raw) {
   switch (raw) {
     case "broadcast":
@@ -3968,7 +4057,7 @@ async function handleTx(target, args, opts) {
     console.log();
     return;
   }
-  if (!opts.from && !opts.encode) {
+  if (!opts.from && !opts.encode && !opts.yaml && !opts.json) {
     if (isRawCall) {
       throw new Error("--from is required (or use --encode to output hex without signing)");
     }
@@ -3981,6 +4070,15 @@ async function handleTx(target, args, opts) {
   if (opts.encode && isRawCall) {
     throw new Error("--encode cannot be used with raw call hex (already encoded)");
   }
+  if ((opts.yaml || opts.json) && opts.encode) {
+    throw new Error("--yaml/--json and --encode are mutually exclusive");
+  }
+  if ((opts.yaml || opts.json) && opts.dryRun) {
+    throw new Error("--yaml/--json and --dry-run are mutually exclusive");
+  }
+  if (opts.yaml && opts.json) {
+    throw new Error("--yaml and --json are mutually exclusive");
+  }
   const config = await loadConfig();
   const effectiveChain = opts.chain;
   let pallet;
@@ -3991,9 +4089,10 @@ async function handleTx(target, args, opts) {
     callName = target.slice(dotIdx + 1);
   }
   const { name: chainName, chain: chainConfig } = resolveChain(config, effectiveChain);
-  const signer = opts.encode ? undefined : await resolveAccountSigner(opts.from);
+  const decodeOnly = opts.encode || opts.yaml || opts.json;
+  const signer = decodeOnly ? undefined : await resolveAccountSigner(opts.from);
   let clientHandle;
-  if (!opts.encode) {
+  if (!decodeOnly) {
     clientHandle = await createChainClient(chainName, chainConfig, opts.rpc);
   }
   try {
@@ -4010,7 +4109,7 @@ async function handleTx(target, args, opts) {
     }
     let unsafeApi;
     let txOptions;
-    if (!opts.encode) {
+    if (!decodeOnly) {
       const userExtOverrides = parseExtOption(opts.ext);
       const customSignedExtensions = buildCustomSignedExtensions(meta, userExtOverrides);
       txOptions = Object.keys(customSignedExtensions).length > 0 ? { customSignedExtensions } : undefined;
@@ -4023,9 +4122,14 @@ async function handleTx(target, args, opts) {
         throw new Error(`Extra arguments are not allowed when submitting a raw call hex.
 ` + "Usage: dot tx 0x<call_hex> --from <account>");
       }
+      callHex = target;
+      if (opts.yaml || opts.json) {
+        const fileObj = decodeCallToFileFormat(meta, callHex, chainName);
+        outputFileFormat(fileObj, !!opts.yaml);
+        return;
+      }
       const callBinary = Binary3.fromHex(target);
       tx = await unsafeApi.txFromCallData(callBinary);
-      callHex = target;
     } else {
       const palletNames = getPalletNames(meta);
       const palletInfo = findPallet(meta, pallet);
@@ -4039,11 +4143,17 @@ async function handleTx(target, args, opts) {
       }
       const effectiveArgs = opts.parsedArgs !== undefined ? fileArgsToStrings(opts.parsedArgs) : args;
       const callData = await parseCallArgs(meta, palletInfo.name, callInfo.name, effectiveArgs);
-      if (opts.encode) {
+      if (opts.encode || opts.yaml || opts.json) {
         const { codec, location } = meta.builder.buildCall(palletInfo.name, callInfo.name);
         const encodedArgs = codec.enc(callData);
         const fullCall = new Uint8Array([location[0], location[1], ...encodedArgs]);
-        console.log(Binary3.fromBytes(fullCall).asHex());
+        const hex = Binary3.fromBytes(fullCall).asHex();
+        if (opts.encode) {
+          console.log(hex);
+          return;
+        }
+        const fileObj = decodeCallToFileFormat(meta, hex, chainName);
+        outputFileFormat(fileObj, !!opts.yaml);
         return;
       }
       tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
@@ -4164,6 +4274,58 @@ function decodeCallFallback(meta, callHex) {
   const argsStr = formatRawDecoded(args);
   return `${palletName2}.${callName} ${argsStr}`;
 }
+function decodeCallToFileFormat(meta, callHex, chainName) {
+  const callTypeId = meta.lookup.call;
+  if (callTypeId == null)
+    throw new Error("No RuntimeCall type ID in metadata");
+  const codec = meta.builder.buildDefinition(callTypeId);
+  const decoded = codec.dec(Binary3.fromHex(callHex).asBytes());
+  const palletName2 = decoded.type;
+  const call = decoded.value;
+  const callName = call.type;
+  const args = call.value;
+  return {
+    chain: chainName,
+    tx: {
+      [palletName2]: {
+        [callName]: sanitizeForSerialization(args) ?? null
+      }
+    }
+  };
+}
+function sanitizeForSerialization(value) {
+  if (value === undefined || value === null)
+    return null;
+  if (value instanceof Binary3)
+    return value.asHex();
+  if (typeof value === "bigint") {
+    if (value >= Number.MIN_SAFE_INTEGER && value <= Number.MAX_SAFE_INTEGER) {
+      return Number(value);
+    }
+    return value.toString();
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map(sanitizeForSerialization);
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [k, v] of Object.entries(value)) {
+      result[k] = sanitizeForSerialization(v);
+    }
+    return result;
+  }
+  return String(value);
+}
+function outputFileFormat(obj, asYaml) {
+  if (asYaml) {
+    process.stdout.write(stringifyYaml2(obj));
+  } else {
+    console.log(JSON.stringify(obj, null, 2));
+  }
+}
 function formatRawDecoded(value) {
   if (value === undefined || value === null)
     return "null";
@@ -4786,7 +4948,7 @@ function watchTransaction(observable, level) {
 
 // src/config/store.ts
 init_types();
-import { access as access3, mkdir as mkdir3, readFile as readFile3, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
+import { access as access3, mkdir as mkdir3, readFile as readFile4, rm as rm2, writeFile as writeFile3 } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import { join as join3 } from "node:path";
 var DOT_DIR2 = join3(homedir2(), ".polkadot");
@@ -4806,7 +4968,7 @@ async function fileExists3(path) {
 async function loadConfig2() {
   await ensureDir3(DOT_DIR2);
   if (await fileExists3(CONFIG_PATH2)) {
-    const saved = JSON.parse(await readFile3(CONFIG_PATH2, "utf-8"));
+    const saved = JSON.parse(await readFile4(CONFIG_PATH2, "utf-8"));
     return {
       ...saved,
       chains: { ...DEFAULT_CONFIG.chains, ...saved.chains }
@@ -4823,6 +4985,7 @@ async function saveConfig2(config) {
 
 // src/core/file-loader.ts
 init_errors();
+import { access as access4, readFile as readFile5 } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";
 var CATEGORIES = ["tx", "query", "const", "apis"];
 var FILE_EXTENSIONS = [".json", ".yaml", ".yml"];
@@ -4870,16 +5033,24 @@ function substituteVars(text, vars) {
       return envVal;
     if (defaultValue !== undefined)
       return defaultValue;
-    throw new CliError(`Undefined variable "\${${varName}}" in file. ` + `Provide it via --var ${varName}=VALUE, as an environment variable, ` + `or add a default with \${${varName}:-default}.`);
+    throw new CliError(`Undefined variable "\${${varName}}" in file.
+
+` + `  Provide it using one of:
+` + `    --var ${varName}=VALUE
+` + `    ${varName}=VALUE dot ...    (environment variable)
+` + `    \${${varName}:-default}     (inline default in file)`);
   });
 }
+function quoteYamlHexValues(text) {
+  return text.replace(/^(\s*(?:[^:]+:\s+|-\s+))(0x[0-9a-fA-F]+)\s*$/gm, '$1"$2"');
+}
 async function loadCommandFile(filePath, cliVars) {
-  const file = Bun.file(filePath);
-  const exists = await file.exists();
-  if (!exists) {
+  try {
+    await access4(filePath);
+  } catch {
     throw new CliError(`File not found: ${filePath}`);
   }
-  const rawText = await file.text();
+  const rawText = await readFile5(filePath, "utf-8");
   if (!rawText.trim()) {
     throw new CliError(`File is empty: ${filePath}`);
   }
@@ -4898,9 +5069,10 @@ async function loadCommandFile(filePath, cliVars) {
   } catch {}
   const mergedVars = { ...fileVars, ...cliVars };
   const substituted = substituteVars(rawText, mergedVars);
+  const textToParse = isJson ? substituted : quoteYamlHexValues(substituted);
   let parsed;
   try {
-    parsed = isJson ? JSON.parse(substituted) : parseYaml(substituted);
+    parsed = isJson ? JSON.parse(textToParse) : parseYaml(textToParse);
   } catch (err) {
     const format = isJson ? "JSON" : "YAML";
     const msg = err instanceof Error ? err.message : String(err);
@@ -5191,12 +5363,15 @@ if (process.argv[2] === "__complete") {
     console.log("  dot apis.Core.version                    Call a runtime API");
     console.log("  dot polkadot.query.System.Number        With chain prefix");
     console.log("  dot ./transfer.yaml --from alice        Run from file");
+    console.log("  dot tx.0x1f0003... --yaml               Decode hex call to YAML");
+    console.log("  dot tx.System.remark 0xdead --json      Encode & output as JSON file format");
     console.log();
     console.log("Commands:");
     console.log("  inspect [target]   Inspect chain metadata (alias: explore)");
     console.log("  chain              Manage chain configurations");
     console.log("  account            Manage accounts");
     console.log("  hash               Hash utilities");
+    console.log("  parachain          Derive parachain sovereign accounts");
     console.log("  completions <sh>   Generate shell completions (zsh, bash, fish)");
     console.log();
     console.log("Global options:");
@@ -5219,8 +5394,9 @@ if (process.argv[2] === "__complete") {
   registerInspectCommand(cli);
   registerAccountCommands(cli);
   registerHashCommand(cli);
+  registerParachainCommand(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("-w, --wait <level>", "Resolve at: broadcast, best-block (or best), finalized (for tx)", {
+  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("--yaml", "Decode call to YAML file format (for tx)").option("--json", "Decode call to JSON file format (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
@@ -5242,6 +5418,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
+            yaml: opts.yaml,
+            json: opts.json,
             ext: opts.ext,
             wait: opts.wait,
             parsedArgs: cmd.args
@@ -5302,6 +5480,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
+            yaml: opts.yaml,
+            json: opts.json,
             ext: opts.ext,
             wait: opts.wait
           });
@@ -5311,6 +5491,8 @@ if (process.argv[2] === "__complete") {
             from: opts.from,
             dryRun: opts.dryRun,
             encode: opts.encode,
+            yaml: opts.yaml,
+            json: opts.json,
             ext: opts.ext,
             wait: opts.wait
           });

package/package.json

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