polkadot-cli 0.8.1 → 0.10.0

package/README.md

@@ -42,7 +42,7 @@ dot chain remove westend
 
 Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for testnets. Create or import your own accounts for any chain.
 
-> **Security warning:** Account secrets (mnemonics and seeds) are currently stored **unencrypted** in `~/.polkadot/accounts.json`. Do not use this for high-value accounts on mainnet. Encrypted storage is planned for a future release.
+> **Security warning:** Account secrets (mnemonics and seeds) are currently stored **unencrypted** in `~/.polkadot/accounts.json`. Do not use this for high-value accounts on mainnet. Encrypted storage is planned for a future release. Use `--env` to keep secrets off disk entirely.
 
 ```bash
 # List all accounts (dev + stored)
@@ -55,10 +55,26 @@ dot account create my-validator
 # Import from a BIP39 mnemonic
 dot account import treasury --secret "word1 word2 ... word12"
 
+# Add an env-var-backed account (secret stays off disk)
+dot account add ci-signer --env MY_SECRET
+
+# Use it — the env var is read at signing time
+MY_SECRET="word1 word2 ..." dot tx System.remark 0xdead --from ci-signer
+
 # Remove an account
 dot account remove my-validator
 ```
 
+#### Env-var-backed accounts
+
+For CI/CD and security-conscious workflows, store a reference to an environment variable instead of the secret itself:
+
+```bash
+dot account add ci-signer --env MY_SECRET
+```
+
+The secret is never written to disk. At signing time, the CLI reads `$MY_SECRET` and derives the keypair. If the variable is not set, the CLI errors with a clear message. `account list` shows an `(env: MY_SECRET)` badge and resolves the address live when the variable is available.
+
 **Supported secret formats for import:**
 
 | Format | Example | Status |
@@ -102,6 +118,20 @@ dot query System.Number --output json | jq '.+1'
 dot query kusama.System.Account 5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY
 ```
 
+#### 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
+- **Uint8Array** values render as `0x`-prefixed hex
+
+```bash
+# Token metadata — symbol and name display as text, not {}
+dot query assethub-paseo.Assets.Metadata 50000413
+# { "deposit": "6693666000", "name": "Paseo Token", "symbol": "PAS", ... }
+```
+
 ### Look up constants
 
 ```bash
@@ -153,6 +183,27 @@ dot tx 0x0503008eaf04151687736326c9fea17e25fc5287613693c912909cb226aa4794f26a48
 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
 ```
 
+#### Enum shorthand
+
+Enum arguments accept a concise `Variant(value)` syntax instead of verbose JSON:
+
+```bash
+# Instead of: '{"type":"system","value":{"type":"Authorized"}}'
+dot tx Utility.dispatch_as 'system(Authorized)' $(dot tx System.remark 0xcafe --encode) --from alice
+
+# Nested enums work too
+dot tx Utility.dispatch_as 'system(Signed(5FHneW46...))' <call> --from alice
+
+# Void variants — empty parens or just the name
+dot tx ... 'Root()' ...
+dot tx ... 'Root' ...
+
+# JSON inside parens for struct values
+dot tx ... 'AccountId32({"id":"0xd435..."})' ...
+```
+
+Variant matching is case-insensitive (`system` resolves to `system`, `authorized` to `Authorized`). All existing formats (JSON objects, hex, SS58 addresses) continue to work unchanged.
+
 #### Encode call data
 
 Encode a call to hex without signing or submitting. Useful for preparing calls to pass to `Sudo.sudo`, multisig proposals, or governance. Works offline from cached metadata and does not require `--from`.

package/dist/cli.mjs

@@ -5,7 +5,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 // src/cli.ts
 import cac from "cac";
 // package.json
-var version = "0.8.1";
+var version = "0.10.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -120,6 +120,11 @@ function findAccount(file, name) {
   return file.accounts.find((a) => a.name.toLowerCase() === name.toLowerCase());
 }
 
+// src/config/accounts-types.ts
+function isEnvSecret(secret) {
+  return typeof secret === "object" && secret !== null && "env" in secret;
+}
+
 // src/core/accounts.ts
 import { sr25519CreateDerive } from "@polkadot-labs/hdkd";
 import {
@@ -195,6 +200,27 @@ function toSs58(publicKey, prefix = 42) {
   }
   return ss58Address(publicKey, prefix);
 }
+function resolveSecret(secret) {
+  if (isEnvSecret(secret)) {
+    const value = process.env[secret.env];
+    if (!value) {
+      throw new Error(`Environment variable "${secret.env}" is not set. Set it before signing.`);
+    }
+    return value;
+  }
+  return secret;
+}
+function tryDerivePublicKey(envVarName) {
+  const value = process.env[envVarName];
+  if (!value)
+    return null;
+  try {
+    const { publicKey } = importAccount(value);
+    return publicKeyToHex(publicKey);
+  } catch {
+    return null;
+  }
+}
 async function resolveAccountSigner(name) {
   if (isDevAccount(name)) {
     const keypair2 = getDevKeypair(name);
@@ -206,12 +232,14 @@ async function resolveAccountSigner(name) {
     const available = [...DEV_NAMES, ...accountsFile.accounts.map((a) => a.name)];
     throw new Error(`Unknown account "${name}". Available accounts: ${available.join(", ")}`);
   }
-  const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(account.secret);
-  const keypair = isHexSeed ? deriveFromHexSeed(account.secret, account.derivationPath) : deriveFromMnemonic(account.secret, account.derivationPath);
+  const secret = resolveSecret(account.secret);
+  const isHexSeed = /^0x[0-9a-fA-F]{64}$/.test(secret);
+  const keypair = isHexSeed ? deriveFromHexSeed(secret, account.derivationPath) : deriveFromMnemonic(secret, account.derivationPath);
   return getPolkadotSigner(keypair.publicKey, "Sr25519", keypair.sign);
 }
 
 // src/core/output.ts
+import { Binary } from "polkadot-api";
 var isTTY = process.stdout.isTTY ?? false;
 var RESET = isTTY ? "\x1B[0m" : "";
 var CYAN = isTTY ? "\x1B[36m" : "";
@@ -224,6 +252,10 @@ var BOLD = isTTY ? "\x1B[1m" : "";
 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;
+  }
   if (value instanceof Uint8Array)
     return `0x${Buffer.from(value).toString("hex")}`;
   return value;
@@ -304,20 +336,23 @@ var ACCOUNT_HELP = `
 ${BOLD}Usage:${RESET}
   $ dot account create <name>                Create a new account
   $ dot account import <name> --secret <s>   Import from BIP39 mnemonic
+  $ dot account add <name> --env <VAR>       Add account backed by env variable
   $ dot account list                         List all accounts
   $ dot account remove <name>                Remove a stored account
 
 ${BOLD}Examples:${RESET}
   $ dot account create my-validator
   $ dot account import treasury --secret "word1 word2 ... word12"
+  $ dot account add ci-signer --env MY_SECRET
   $ dot account list
   $ dot account remove my-validator
 
 ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
+      Use --env to keep secrets off disk entirely.
       Hex seed import (0x...) is not supported via CLI.${RESET}
 `.trimStart();
 function registerAccountCommands(cli) {
-  cli.command("account [action] [name]", "Manage local accounts (create, import, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").action(async (action, name, opts) => {
+  cli.command("account [action] [name]", "Manage local accounts (create, import, add, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").option("--env <varName>", "Environment variable name holding the secret").action(async (action, name, opts) => {
     if (!action) {
       return accountList();
     }
@@ -326,6 +361,8 @@ function registerAccountCommands(cli) {
         return accountCreate(name);
       case "import":
         return accountImport(name, opts);
+      case "add":
+        return accountAdd(name, opts);
       case "list":
         return accountList();
       case "remove":
@@ -405,6 +442,44 @@ async function accountImport(name, opts) {
   console.log(`  ${BOLD}Address:${RESET} ${address}`);
   console.log();
 }
+async function accountAdd(name, opts) {
+  if (!name) {
+    console.error(`Account name is required.
+`);
+    console.error("Usage: dot account add <name> --env <VAR>");
+    process.exit(1);
+  }
+  if (!opts.env) {
+    console.error(`--env is required.
+`);
+    console.error("Usage: dot account add <name> --env <VAR>");
+    process.exit(1);
+  }
+  if (isDevAccount(name)) {
+    throw new Error(`"${name}" is a built-in dev account and cannot be used as a custom account name.`);
+  }
+  const accountsFile = await loadAccounts();
+  if (findAccount(accountsFile, name)) {
+    throw new Error(`Account "${name}" already exists.`);
+  }
+  const publicKey = tryDerivePublicKey(opts.env) ?? "";
+  accountsFile.accounts.push({
+    name,
+    secret: { env: opts.env },
+    publicKey,
+    derivationPath: ""
+  });
+  await saveAccounts(accountsFile);
+  printHeading("Account Added");
+  console.log(`  ${BOLD}Name:${RESET}  ${name}`);
+  console.log(`  ${BOLD}Env:${RESET}   ${opts.env}`);
+  if (publicKey) {
+    console.log(`  ${BOLD}Address:${RESET} ${toSs58(publicKey)}`);
+  } else {
+    console.log(`  ${YELLOW}Address will resolve when $${opts.env} is set.${RESET}`);
+  }
+  console.log();
+}
 async function accountList() {
   printHeading("Dev Accounts");
   for (const name of DEV_NAMES) {
@@ -416,8 +491,19 @@ async function accountList() {
   if (accountsFile.accounts.length > 0) {
     printHeading("Stored Accounts");
     for (const account of accountsFile.accounts) {
-      const address = toSs58(account.publicKey);
-      printItem(account.name, address);
+      let displayName = account.name;
+      let address;
+      if (isEnvSecret(account.secret)) {
+        displayName += ` (env: ${account.secret.env})`;
+        let pubKey = account.publicKey;
+        if (!pubKey) {
+          pubKey = tryDerivePublicKey(account.secret.env) ?? "";
+        }
+        address = pubKey ? toSs58(pubKey) : "n/a";
+      } else {
+        address = toSs58(account.publicKey);
+      }
+      printItem(displayName, address);
     }
   } else {
     printHeading("Stored Accounts");
@@ -1201,7 +1287,7 @@ function parseValue(arg) {
 
 // src/commands/tx.ts
 import { getViewBuilder } from "@polkadot-api/view-builder";
-import { Binary } from "polkadot-api";
+import { Binary as Binary2 } from "polkadot-api";
 
 // src/core/explorers.ts
 var pjsAppsLink = (rpc, hash) => `https://polkadot.js.org/apps/?rpc=${encodeURIComponent(rpc)}#/explorer/query/${hash}`;
@@ -1273,8 +1359,8 @@ function normalizeValue(lookup, entry, value) {
       }
       if (innerResolved.type === "primitive" && innerResolved.value === "u8" && typeof value === "string") {
         if (/^0x[0-9a-fA-F]*$/.test(value))
-          return Binary.fromHex(value);
-        return Binary.fromText(value);
+          return Binary2.fromHex(value);
+        return Binary2.fromText(value);
       }
       if (Array.isArray(value)) {
         const innerEntry = resolved.value;
@@ -1329,7 +1415,20 @@ function normalizeValue(lookup, entry, value) {
       return value;
   }
 }
+function parseEnumShorthand(arg) {
+  if (arg.startsWith("{") || arg.startsWith("[") || arg.startsWith("0x"))
+    return null;
+  const firstParen = arg.indexOf("(");
+  if (firstParen === -1 || !arg.endsWith(")"))
+    return null;
+  const variant = arg.slice(0, firstParen);
+  if (!/^[a-zA-Z_]\w*$/.test(variant))
+    return null;
+  return { variant, inner: arg.slice(firstParen + 1, -1) };
+}
 function parseTypedArg(meta, entry, arg) {
+  if (entry.type === "lookupEntry")
+    return parseTypedArg(meta, entry.value, arg);
   switch (entry.type) {
     case "primitive":
       return parsePrimitive(entry.value, arg);
@@ -1347,7 +1446,7 @@ function parseTypedArg(meta, entry, arg) {
     case "enum": {
       if (/^0x[0-9a-fA-F]+$/.test(arg) && meta.lookup.call != null && entry.id === meta.lookup.call) {
         const callCodec = meta.builder.buildDefinition(meta.lookup.call);
-        return callCodec.dec(Binary.fromHex(arg).asBytes());
+        return callCodec.dec(Binary2.fromHex(arg).asBytes());
       }
       if (arg.startsWith("{")) {
         try {
@@ -1355,6 +1454,19 @@ function parseTypedArg(meta, entry, arg) {
         } catch {}
       }
       const variants = Object.keys(entry.value);
+      const shorthand = parseEnumShorthand(arg);
+      if (shorthand) {
+        const matched2 = variants.find((v) => v.toLowerCase() === shorthand.variant.toLowerCase());
+        if (matched2) {
+          const variantDef = entry.value[matched2];
+          const resolvedDef = variantDef.type === "lookupEntry" ? variantDef.value : variantDef;
+          if (resolvedDef.type === "void" || shorthand.inner === "") {
+            return { type: matched2 };
+          }
+          const innerValue = parseTypedArg(meta, variantDef, shorthand.inner);
+          return normalizeValue(meta.lookup, entry, { type: matched2, value: innerValue });
+        }
+      }
       if (variants.includes("Id")) {
         const idVariant = entry.value.Id;
         const innerType = idVariant.type === "lookupEntry" ? idVariant.value : idVariant;
@@ -1376,8 +1488,8 @@ function parseTypedArg(meta, entry, arg) {
       const inner = entry.value;
       if (inner.type === "primitive" && inner.value === "u8") {
         if (/^0x[0-9a-fA-F]*$/.test(arg))
-          return Binary.fromHex(arg);
-        return Binary.fromText(arg);
+          return Binary2.fromHex(arg);
+        return Binary2.fromText(arg);
       }
       if (arg.startsWith("[")) {
         try {
@@ -1385,7 +1497,7 @@ function parseTypedArg(meta, entry, arg) {
         } catch {}
       }
       if (/^0x[0-9a-fA-F]*$/.test(arg))
-        return Binary.fromHex(arg);
+        return Binary2.fromHex(arg);
       return parseValue(arg);
     }
     case "struct":
@@ -1551,7 +1663,7 @@ function parseStorageKeys(meta, palletName, storageItem, args) {
 
 // src/commands/tx.ts
 import { getViewBuilder as getViewBuilder2 } from "@polkadot-api/view-builder";
-import { Binary as Binary2 } from "polkadot-api";
+import { Binary as Binary3 } from "polkadot-api";
 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("--encode", "Encode call to hex without signing or submitting").option("--ext <json>", `Custom signed extension values as JSON, e.g. '{"ExtName":{"value":...}}'`).action(async (target, args, opts) => {
     if (!target) {
@@ -1616,7 +1728,7 @@ function registerTxCommand(cli) {
           throw new Error(`Extra arguments are not allowed when submitting a raw call hex.
 ` + "Usage: dot tx 0x<call_hex> --from <account>");
         }
-        const callBinary = Binary2.fromHex(target);
+        const callBinary = Binary3.fromHex(target);
         tx = await unsafeApi.txFromCallData(callBinary);
         callHex = target;
       } else {
@@ -1637,7 +1749,7 @@ function registerTxCommand(cli) {
           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(Binary2.fromBytes(fullCall).asHex());
+          console.log(Binary3.fromBytes(fullCall).asHex());
           return;
         }
         tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
@@ -1820,6 +1932,10 @@ function formatEventValue(v) {
     return v.toString();
   if (v === null || v === undefined)
     return "null";
+  if (v instanceof Binary3) {
+    const text = v.asText();
+    return text.includes("�") ? v.asHex() : text;
+  }
   return JSON.stringify(v, (_k, val) => typeof val === "bigint" ? val.toString() : val);
 }
 function parseCallArgs(meta, palletName, callName, args) {
@@ -1927,8 +2043,8 @@ function normalizeValue2(lookup, entry, value) {
       }
       if (innerResolved.type === "primitive" && innerResolved.value === "u8" && typeof value === "string") {
         if (/^0x[0-9a-fA-F]*$/.test(value))
-          return Binary2.fromHex(value);
-        return Binary2.fromText(value);
+          return Binary3.fromHex(value);
+        return Binary3.fromText(value);
       }
       if (Array.isArray(value)) {
         const innerEntry = resolved.value;
@@ -1983,7 +2099,20 @@ function normalizeValue2(lookup, entry, value) {
       return value;
   }
 }
+function parseEnumShorthand2(arg) {
+  if (arg.startsWith("{") || arg.startsWith("[") || arg.startsWith("0x"))
+    return null;
+  const firstParen = arg.indexOf("(");
+  if (firstParen === -1 || !arg.endsWith(")"))
+    return null;
+  const variant = arg.slice(0, firstParen);
+  if (!/^[a-zA-Z_]\w*$/.test(variant))
+    return null;
+  return { variant, inner: arg.slice(firstParen + 1, -1) };
+}
 function parseTypedArg2(meta, entry, arg) {
+  if (entry.type === "lookupEntry")
+    return parseTypedArg2(meta, entry.value, arg);
   switch (entry.type) {
     case "primitive":
       return parsePrimitive2(entry.value, arg);
@@ -2001,7 +2130,7 @@ function parseTypedArg2(meta, entry, arg) {
     case "enum": {
       if (/^0x[0-9a-fA-F]+$/.test(arg) && meta.lookup.call != null && entry.id === meta.lookup.call) {
         const callCodec = meta.builder.buildDefinition(meta.lookup.call);
-        return callCodec.dec(Binary2.fromHex(arg).asBytes());
+        return callCodec.dec(Binary3.fromHex(arg).asBytes());
       }
       if (arg.startsWith("{")) {
         try {
@@ -2009,6 +2138,19 @@ function parseTypedArg2(meta, entry, arg) {
         } catch {}
       }
       const variants = Object.keys(entry.value);
+      const shorthand = parseEnumShorthand2(arg);
+      if (shorthand) {
+        const matched2 = variants.find((v) => v.toLowerCase() === shorthand.variant.toLowerCase());
+        if (matched2) {
+          const variantDef = entry.value[matched2];
+          const resolvedDef = variantDef.type === "lookupEntry" ? variantDef.value : variantDef;
+          if (resolvedDef.type === "void" || shorthand.inner === "") {
+            return { type: matched2 };
+          }
+          const innerValue = parseTypedArg2(meta, variantDef, shorthand.inner);
+          return normalizeValue2(meta.lookup, entry, { type: matched2, value: innerValue });
+        }
+      }
       if (variants.includes("Id")) {
         const idVariant = entry.value.Id;
         const innerType = idVariant.type === "lookupEntry" ? idVariant.value : idVariant;
@@ -2030,8 +2172,8 @@ function parseTypedArg2(meta, entry, arg) {
       const inner = entry.value;
       if (inner.type === "primitive" && inner.value === "u8") {
         if (/^0x[0-9a-fA-F]*$/.test(arg))
-          return Binary2.fromHex(arg);
-        return Binary2.fromText(arg);
+          return Binary3.fromHex(arg);
+        return Binary3.fromText(arg);
       }
       if (arg.startsWith("[")) {
         try {
@@ -2039,7 +2181,7 @@ function parseTypedArg2(meta, entry, arg) {
         } catch {}
       }
       if (/^0x[0-9a-fA-F]*$/.test(arg))
-        return Binary2.fromHex(arg);
+        return Binary3.fromHex(arg);
       return parseValue(arg);
     }
     case "struct":

package/package.json

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