polkadot-cli 0.6.1 → 0.7.0

package/README.md

@@ -22,7 +22,8 @@ dot chain add kusama --rpc wss://kusama-rpc.polkadot.io
 dot chain add westend --light-client
 
 # List configured chains
-dot chain list
+dot chains              # shorthand
+dot chain list          # equivalent
 
 # Re-fetch metadata after a runtime upgrade
 dot chain update          # updates default chain
@@ -43,7 +44,8 @@ Dev accounts (Alice, Bob, Charlie, Dave, Eve, Ferdie) are always available for t
 
 ```bash
 # List all accounts (dev + stored)
-dot account list
+dot accounts            # shorthand
+dot account list        # equivalent
 
 # Create a new account (generates a mnemonic)
 dot account create my-validator
@@ -144,10 +146,20 @@ Both dry-run and submission display the encoded call hex and a decoded human-rea
   Call:   0x0001076465616462656566
   Decode: System.remark(remark: 0xdeadbeef)
   Tx:     0xabc123...
-  Block:  #12345678 (0xdef...)
   Status: ok
 ```
 
+#### Exit codes
+
+The CLI exits with code **1** when a finalized transaction has a dispatch error (e.g. insufficient balance, bad origin). The full transaction output (events, explorer links) is still printed before the error so you can debug the failure. Module errors are formatted as `PalletName.ErrorVariant` (e.g. `Balances.InsufficientBalance`).
+
+```bash
+dot tx Balances.transferKeepAlive 5FHneW46... 999999999999999999 --from alice
+# ... events and explorer links ...
+# Error: Transaction dispatch error: Balances.InsufficientBalance
+echo $?  # 1
+```
+
 #### Custom signed extensions
 
 Chains with non-standard signed extensions (e.g. `people-preview`) are auto-handled:
@@ -210,6 +222,27 @@ polkadot-cli aims to be the single tool for day-to-day chain interaction: storag
 
 Outside Polkadot, the closest comparable in terms of interactive UX is [near-cli-rs](https://github.com/near/near-cli-rs) (NEAR).
 
+## Update notifications
+
+After each command, the CLI checks whether a newer version is available on npm and displays a notification:
+
+```
+╭───────────────────────────────────────────────╮
+│                                               │
+│   Update available! 0.6.2 → 0.7.0            │
+│   Run npm i -g polkadot-cli to update         │
+│                                               │
+╰───────────────────────────────────────────────╯
+```
+
+The version check runs in the background on startup and caches the result for 24 hours in `~/.polkadot/update-check.json`. It never blocks the CLI.
+
+The notification is automatically suppressed when:
+
+- `DOT_NO_UPDATE_CHECK=1` is set
+- `CI` environment variable is set (any value)
+- stdout is not a TTY (e.g. piped output)
+
 ## Configuration
 
 Config and metadata caches live in `~/.polkadot/`:
@@ -218,6 +251,7 @@ Config and metadata caches live in `~/.polkadot/`:
 ~/.polkadot/
 ├── config.json          # chains and default chain
 ├── accounts.json        # stored accounts (⚠️ secrets are NOT encrypted — see below)
+├── update-check.json    # cached update check result
 └── chains/
     └── polkadot/
         └── metadata.bin # cached SCALE-encoded metadata

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.6.1";
+var version = "0.7.0";
 
 // src/config/accounts-store.ts
 import { access as access2, mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
@@ -216,6 +216,7 @@ var isTTY = process.stdout.isTTY ?? false;
 var RESET = isTTY ? "\x1B[0m" : "";
 var CYAN = isTTY ? "\x1B[36m" : "";
 var GREEN = isTTY ? "\x1B[32m" : "";
+var RED = isTTY ? "\x1B[31m" : "";
 var YELLOW = isTTY ? "\x1B[33m" : "";
 var MAGENTA = isTTY ? "\x1B[35m" : "";
 var DIM = isTTY ? "\x1B[2m" : "";
@@ -316,10 +317,9 @@ ${YELLOW}Note: Secrets are stored unencrypted in ~/.polkadot/accounts.json.
       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)").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, list, remove)").alias("accounts").option("--secret <value>", "Secret key (mnemonic or hex seed) for import").action(async (action, name, opts) => {
     if (!action) {
-      console.log(ACCOUNT_HELP);
-      return;
+      return accountList();
     }
     switch (action) {
       case "create":
@@ -696,10 +696,9 @@ ${BOLD}Examples:${RESET}
   $ dot chain remove kusama
 `.trimStart();
 function registerChainCommands(cli) {
-  cli.command("chain [action] [name]", "Manage chains (add, remove, update, list, default)").action(async (action, name, opts) => {
+  cli.command("chain [action] [name]", "Manage chains (add, remove, update, list, default)").alias("chains").action(async (action, name, opts) => {
     if (!action) {
-      console.log(CHAIN_HELP);
-      return;
+      return chainList();
     }
     switch (action) {
       case "add":
@@ -1145,6 +1144,254 @@ function parseValue(arg) {
   return arg;
 }
 
+// src/commands/tx.ts
+import { getViewBuilder } from "@polkadot-api/view-builder";
+import { Binary } from "polkadot-api";
+
+// 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 parseStructArgs(meta, fields, args, callLabel) {
+  const fieldNames = Object.keys(fields);
+  if (args.length !== fieldNames.length) {
+    const expected = fieldNames.map((name) => `${name}: ${describeType(meta.lookup, fields[name].id)}`).join(", ");
+    throw new Error(`${callLabel} takes ${fieldNames.length} argument(s): ${expected}
+` + `  Got ${args.length} argument(s).`);
+  }
+  const result = {};
+  for (let i = 0;i < fieldNames.length; i++) {
+    const name = fieldNames[i];
+    const entry = fields[name];
+    result[name] = parseTypedArg(meta, entry, args[i]);
+  }
+  return result;
+}
+function normalizeValue(lookup, entry, value) {
+  let resolved = entry;
+  while (resolved.type === "lookupEntry") {
+    resolved = resolved.value;
+  }
+  switch (resolved.type) {
+    case "enum": {
+      if (value !== null && typeof value === "object" && !Array.isArray(value) && "type" in value) {
+        const enumValue = value;
+        const variant = resolved.value[enumValue.type];
+        if (variant) {
+          let innerEntry = variant;
+          while (innerEntry.type === "lookupEntry") {
+            innerEntry = innerEntry.value;
+          }
+          let normalizedInner = enumValue.value;
+          if (innerEntry.type !== "array" && innerEntry.type !== "sequence" && innerEntry.type !== "void" && Array.isArray(normalizedInner) && normalizedInner.length === 1) {
+            normalizedInner = normalizedInner[0];
+          }
+          if (normalizedInner !== undefined && innerEntry.type !== "void") {
+            normalizedInner = normalizeValue(lookup, innerEntry, normalizedInner);
+          }
+          return { type: enumValue.type, value: normalizedInner };
+        }
+      }
+      return value;
+    }
+    case "struct": {
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const fields = resolved.value;
+        const result = {};
+        for (const [key, val] of Object.entries(value)) {
+          if (key in fields) {
+            result[key] = normalizeValue(lookup, fields[key], val);
+          } else {
+            result[key] = val;
+          }
+        }
+        return result;
+      }
+      return value;
+    }
+    case "array":
+    case "sequence": {
+      let innerResolved = resolved.value;
+      while (innerResolved.type === "lookupEntry") {
+        innerResolved = innerResolved.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);
+      }
+      if (Array.isArray(value)) {
+        const innerEntry = resolved.value;
+        return value.map((item) => normalizeValue(lookup, innerEntry, item));
+      }
+      return value;
+    }
+    case "tuple": {
+      if (Array.isArray(value)) {
+        const entries = resolved.value;
+        return value.map((item, i) => i < entries.length ? normalizeValue(lookup, entries[i], item) : item);
+      }
+      return value;
+    }
+    case "option": {
+      if (value !== null && value !== undefined) {
+        return normalizeValue(lookup, resolved.value, value);
+      }
+      return;
+    }
+    case "primitive": {
+      if (typeof value === "string") {
+        const prim = resolved.value;
+        switch (prim) {
+          case "bool":
+            return value === "true";
+          case "u64":
+          case "u128":
+          case "u256":
+          case "i64":
+          case "i128":
+          case "i256":
+            return BigInt(value);
+          case "u8":
+          case "u16":
+          case "u32":
+          case "i8":
+          case "i16":
+          case "i32":
+            return parseInt(value, 10);
+        }
+      }
+      return value;
+    }
+    case "compact": {
+      if (typeof value === "string") {
+        return resolved.isBig ? BigInt(value) : parseInt(value, 10);
+      }
+      return value;
+    }
+    default:
+      return value;
+  }
+}
+function parseTypedArg(meta, entry, arg) {
+  switch (entry.type) {
+    case "primitive":
+      return parsePrimitive(entry.value, arg);
+    case "compact":
+      return entry.isBig ? BigInt(arg) : parseInt(arg, 10);
+    case "AccountId32":
+    case "AccountId20":
+      return arg;
+    case "option": {
+      if (arg === "null" || arg === "undefined" || arg === "none") {
+        return;
+      }
+      return parseTypedArg(meta, entry.value, 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());
+      }
+      if (arg.startsWith("{")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      const variants = Object.keys(entry.value);
+      if (variants.includes("Id")) {
+        const idVariant = entry.value.Id;
+        const innerType = idVariant.type === "lookupEntry" ? idVariant.value : idVariant;
+        if (innerType.type === "AccountId32" && !arg.startsWith("{")) {
+          return { type: "Id", value: arg };
+        }
+      }
+      const matched = variants.find((v) => v.toLowerCase() === arg.toLowerCase());
+      if (matched) {
+        const variant = entry.value[matched];
+        if (variant.type === "void") {
+          return { type: matched };
+        }
+      }
+      return parseValue(arg);
+    }
+    case "sequence":
+    case "array": {
+      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);
+      }
+      if (arg.startsWith("[")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      if (/^0x[0-9a-fA-F]*$/.test(arg))
+        return Binary.fromHex(arg);
+      return parseValue(arg);
+    }
+    case "struct":
+      if (arg.startsWith("{")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      return parseValue(arg);
+    case "tuple":
+      if (arg.startsWith("[")) {
+        try {
+          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+        } catch {}
+      }
+      return parseValue(arg);
+    default:
+      return parseValue(arg);
+  }
+}
+function parsePrimitive(prim, arg) {
+  switch (prim) {
+    case "bool":
+      return arg === "true";
+    case "char":
+    case "str":
+      return arg;
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i8":
+    case "i16":
+    case "i32":
+      return parseInt(arg, 10);
+    case "u64":
+    case "u128":
+    case "u256":
+    case "i64":
+    case "i128":
+    case "i256":
+      return BigInt(arg);
+    default:
+      return parseValue(arg);
+  }
+}
+var PAPI_BUILTIN_EXTENSIONS = new Set([
+  "CheckNonZeroSender",
+  "CheckSpecVersion",
+  "CheckTxVersion",
+  "CheckGenesis",
+  "CheckMortality",
+  "CheckNonce",
+  "CheckWeight",
+  "ChargeTransactionPayment",
+  "ChargeAssetTxPayment",
+  "CheckMetadataHash",
+  "StorageWeightReclaim",
+  "PrevalidateAttests"
+]);
+var NO_DEFAULT = Symbol("no-default");
+
 // src/commands/query.ts
 var DEFAULT_LIMIT = 100;
 function registerQueryCommand(cli) {
@@ -1181,8 +1428,14 @@ function registerQueryCommand(cli) {
       }
       const unsafeApi = clientHandle.client.getUnsafeApi();
       const storageApi = unsafeApi.query[palletInfo.name][storageItem.name];
-      const parsedKeys = keys.map(parseValue);
+      const parsedKeys = parseStorageKeys(meta, palletInfo.name, storageItem, keys);
       const format = opts.output ?? "pretty";
+      if (format === "json") {
+        console.error(`chain: ${chainName}`);
+      } else {
+        console.log(`${DIM}chain: ${chainName}${RESET}
+`);
+      }
       if (storageItem.type === "map" && parsedKeys.length === 0) {
         const entries = await storageApi.getEntries();
         const limit = Number(opts.limit);
@@ -1205,16 +1458,46 @@ ${DIM}Showing ${limit} of ${entries.length} entries. Use --limit 0 for all.${RES
     }
   });
 }
+function parseStorageKeys(meta, palletName, storageItem, args) {
+  if (storageItem.type === "plain" || storageItem.keyTypeId == null) {
+    return args.map(parseValue);
+  }
+  if (args.length === 0)
+    return [];
+  const storageEntry = meta.builder.buildStorage(palletName, storageItem.name);
+  const len = storageEntry.len;
+  const keyEntry = meta.lookup(storageItem.keyTypeId);
+  if (len === 1) {
+    if (args.length === 1) {
+      return [parseTypedArg(meta, keyEntry, args[0])];
+    }
+    if (keyEntry.type === "struct") {
+      const label = `${palletName}.${storageItem.name} key`;
+      return [parseStructArgs(meta, keyEntry.value, args, label)];
+    }
+    const typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
+    throw new Error(`${palletName}.${storageItem.name} key expects ${typeDesc}
+` + `  Pass 1 argument. Got ${args.length}.`);
+  }
+  if (args.length !== len) {
+    let typeDesc;
+    if (keyEntry.type === "tuple") {
+      typeDesc = keyEntry.value.map((e) => describeType(meta.lookup, e.id)).join(", ");
+    } else {
+      typeDesc = describeType(meta.lookup, storageItem.keyTypeId);
+    }
+    throw new Error(`${palletName}.${storageItem.name} expects ${len} key arg(s): (${typeDesc}). Got ${args.length}.`);
+  }
+  if (keyEntry.type === "tuple") {
+    const entries = keyEntry.value;
+    return entries.map((entry, i) => parseTypedArg(meta, entry, args[i]));
+  }
+  return args.map((arg) => parseTypedArg(meta, keyEntry, arg));
+}
 
 // src/commands/tx.ts
-import { getViewBuilder } from "@polkadot-api/view-builder";
-import { Binary } from "polkadot-api";
-
-// 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
+import { getViewBuilder as getViewBuilder2 } from "@polkadot-api/view-builder";
+import { Binary as Binary2 } 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) {
@@ -1271,7 +1554,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 = Binary.fromHex(target);
+        const callBinary = Binary2.fromHex(target);
         tx = await unsafeApi.txFromCallData(callBinary);
         callHex = target;
       } else {
@@ -1291,7 +1574,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(Binary.fromBytes(fullCall).asHex());
+          console.log(Binary2.fromBytes(fullCall).asHex());
           return;
         }
         tx = unsafeApi.tx[palletInfo.name][callInfo.name](callData);
@@ -1320,12 +1603,13 @@ function registerTxCommand(cli) {
       console.log(`  ${BOLD}Call:${RESET}   ${callHex}`);
       console.log(`  ${BOLD}Decode:${RESET} ${decodedStr}`);
       console.log(`  ${BOLD}Tx:${RESET}     ${result.txHash}`);
-      console.log(`  ${BOLD}Block:${RESET}  #${result.block.number} (${result.block.hash})`);
+      let dispatchErrorMsg;
       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)}` : ""}`);
+        dispatchErrorMsg = formatDispatchError(result.dispatchError);
+        console.log(`  ${BOLD}Status:${RESET} ${RED}dispatch error${RESET}`);
+        console.log(`  ${BOLD}Error:${RESET}  ${dispatchErrorMsg}`);
       }
       if (result.events && result.events.length > 0) {
         console.log(`  ${BOLD}Events:${RESET}`);
@@ -1348,14 +1632,34 @@ function registerTxCommand(cli) {
         console.log(`    ${DIM}PAPI${RESET}        ${papiLink(rpcUrl, blockHash)}`);
       }
       console.log();
+      if (!result.ok) {
+        throw new CliError(`Transaction dispatch error: ${dispatchErrorMsg}`);
+      }
     } finally {
       clientHandle?.destroy();
     }
   });
 }
+function formatDispatchError(err) {
+  if (err.type === "Module" && err.value && typeof err.value === "object") {
+    const mod = err.value;
+    if (mod.type) {
+      const inner = mod.value;
+      if (inner && typeof inner === "object" && inner.type) {
+        return `${mod.type}.${inner.type}`;
+      }
+      return mod.type;
+    }
+  }
+  if (err.value !== undefined && err.value !== null) {
+    const val = typeof err.value === "string" ? err.value : JSON.stringify(err.value);
+    return `${err.type}: ${val}`;
+  }
+  return err.type;
+}
 function decodeCall(meta, callHex) {
   try {
-    const viewBuilder = getViewBuilder(meta.lookup);
+    const viewBuilder = getViewBuilder2(meta.lookup);
     const decoded = viewBuilder.callDecoder(callHex);
     const palletName = decoded.pallet.value.name;
     const callName = decoded.call.value.name;
@@ -1472,30 +1776,30 @@ function parseCallArgs(meta, palletName, callName, args) {
     return;
   }
   if (variant.type === "struct") {
-    return parseStructArgs(meta, variant.value, args, `${palletName}.${callName}`);
+    return parseStructArgs2(meta, variant.value, args, `${palletName}.${callName}`);
   }
   if (variant.type === "lookupEntry") {
     const inner = variant.value;
     if (inner.type === "struct") {
-      return parseStructArgs(meta, inner.value, args, `${palletName}.${callName}`);
+      return parseStructArgs2(meta, inner.value, args, `${palletName}.${callName}`);
     }
     if (inner.type === "void")
       return;
     if (args.length !== 1) {
       throw new Error(`${palletName}.${callName} takes 1 argument (${describeType(meta.lookup, inner.id)}), but ${args.length} provided.`);
     }
-    return parseTypedArg(meta, inner, args[0]);
+    return parseTypedArg2(meta, inner, args[0]);
   }
   if (variant.type === "tuple") {
     const entries = variant.value;
     if (args.length !== entries.length) {
       throw new Error(`${palletName}.${callName} takes ${entries.length} arguments, but ${args.length} provided.`);
     }
-    return entries.map((entry, i) => parseTypedArg(meta, entry, args[i]));
+    return entries.map((entry, i) => parseTypedArg2(meta, entry, args[i]));
   }
   return args.length === 0 ? undefined : args.map(parseValue);
 }
-function parseStructArgs(meta, fields, args, callLabel) {
+function parseStructArgs2(meta, fields, args, callLabel) {
   const fieldNames = Object.keys(fields);
   if (args.length !== fieldNames.length) {
     const expected = fieldNames.map((name) => `${name}: ${describeType(meta.lookup, fields[name].id)}`).join(", ");
@@ -1506,11 +1810,11 @@ function parseStructArgs(meta, fields, args, callLabel) {
   for (let i = 0;i < fieldNames.length; i++) {
     const name = fieldNames[i];
     const entry = fields[name];
-    result[name] = parseTypedArg(meta, entry, args[i]);
+    result[name] = parseTypedArg2(meta, entry, args[i]);
   }
   return result;
 }
-function normalizeValue(lookup, entry, value) {
+function normalizeValue2(lookup, entry, value) {
   let resolved = entry;
   while (resolved.type === "lookupEntry") {
     resolved = resolved.value;
@@ -1530,7 +1834,7 @@ function normalizeValue(lookup, entry, value) {
             normalizedInner = normalizedInner[0];
           }
           if (normalizedInner !== undefined && innerEntry.type !== "void") {
-            normalizedInner = normalizeValue(lookup, innerEntry, normalizedInner);
+            normalizedInner = normalizeValue2(lookup, innerEntry, normalizedInner);
           }
           return { type: enumValue.type, value: normalizedInner };
         }
@@ -1543,7 +1847,7 @@ function normalizeValue(lookup, entry, value) {
         const result = {};
         for (const [key, val] of Object.entries(value)) {
           if (key in fields) {
-            result[key] = normalizeValue(lookup, fields[key], val);
+            result[key] = normalizeValue2(lookup, fields[key], val);
           } else {
             result[key] = val;
           }
@@ -1560,25 +1864,25 @@ 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;
-        return value.map((item) => normalizeValue(lookup, innerEntry, item));
+        return value.map((item) => normalizeValue2(lookup, innerEntry, item));
       }
       return value;
     }
     case "tuple": {
       if (Array.isArray(value)) {
         const entries = resolved.value;
-        return value.map((item, i) => i < entries.length ? normalizeValue(lookup, entries[i], item) : item);
+        return value.map((item, i) => i < entries.length ? normalizeValue2(lookup, entries[i], item) : item);
       }
       return value;
     }
     case "option": {
       if (value !== null && value !== undefined) {
-        return normalizeValue(lookup, resolved.value, value);
+        return normalizeValue2(lookup, resolved.value, value);
       }
       return;
     }
@@ -1616,10 +1920,10 @@ function normalizeValue(lookup, entry, value) {
       return value;
   }
 }
-function parseTypedArg(meta, entry, arg) {
+function parseTypedArg2(meta, entry, arg) {
   switch (entry.type) {
     case "primitive":
-      return parsePrimitive(entry.value, arg);
+      return parsePrimitive2(entry.value, arg);
     case "compact":
       return entry.isBig ? BigInt(arg) : parseInt(arg, 10);
     case "AccountId32":
@@ -1629,16 +1933,16 @@ function parseTypedArg(meta, entry, arg) {
       if (arg === "null" || arg === "undefined" || arg === "none") {
         return;
       }
-      return parseTypedArg(meta, entry.value, arg);
+      return parseTypedArg2(meta, entry.value, 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 {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       const variants = Object.keys(entry.value);
@@ -1663,29 +1967,29 @@ 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 {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       if (/^0x[0-9a-fA-F]*$/.test(arg))
-        return Binary.fromHex(arg);
+        return Binary2.fromHex(arg);
       return parseValue(arg);
     }
     case "struct":
       if (arg.startsWith("{")) {
         try {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       return parseValue(arg);
     case "tuple":
       if (arg.startsWith("[")) {
         try {
-          return normalizeValue(meta.lookup, entry, JSON.parse(arg));
+          return normalizeValue2(meta.lookup, entry, JSON.parse(arg));
         } catch {}
       }
       return parseValue(arg);
@@ -1693,7 +1997,7 @@ function parseTypedArg(meta, entry, arg) {
       return parseValue(arg);
   }
 }
-function parsePrimitive(prim, arg) {
+function parsePrimitive2(prim, arg) {
   switch (prim) {
     case "bool":
       return arg === "true";
@@ -1718,7 +2022,7 @@ function parsePrimitive(prim, arg) {
       return parseValue(arg);
   }
 }
-var PAPI_BUILTIN_EXTENSIONS = new Set([
+var PAPI_BUILTIN_EXTENSIONS2 = new Set([
   "CheckNonZeroSender",
   "CheckSpecVersion",
   "CheckTxVersion",
@@ -1748,12 +2052,12 @@ function parseExtOption(ext) {
 ` + `Expected format: '{"ExtName":{"value":...}}'`);
   }
 }
-var NO_DEFAULT = Symbol("no-default");
+var NO_DEFAULT2 = 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))
+    if (PAPI_BUILTIN_EXTENSIONS2.has(ext.identifier))
       continue;
     if (ext.identifier in userOverrides) {
       result[ext.identifier] = userOverrides[ext.identifier];
@@ -1763,10 +2067,10 @@ function buildCustomSignedExtensions(meta, userOverrides) {
     const addEntry = meta.lookup(ext.additionalSigned);
     const value = autoDefaultForType(valueEntry);
     const add = autoDefaultForType(addEntry);
-    if (value !== NO_DEFAULT || add !== NO_DEFAULT) {
+    if (value !== NO_DEFAULT2 || add !== NO_DEFAULT2) {
       result[ext.identifier] = {
-        ...value !== NO_DEFAULT ? { value } : {},
-        ...add !== NO_DEFAULT ? { additionalSigned: add } : {}
+        ...value !== NO_DEFAULT2 ? { value } : {},
+        ...add !== NO_DEFAULT2 ? { additionalSigned: add } : {}
       };
     }
   }
@@ -1783,7 +2087,7 @@ function autoDefaultForType(entry) {
       return { type: "Disabled", value: undefined };
     }
   }
-  return NO_DEFAULT;
+  return NO_DEFAULT2;
 }
 function watchTransaction(observable) {
   const spinner = new Spinner;
@@ -1810,7 +2114,7 @@ function watchTransaction(observable) {
             }
             break;
           case "finalized":
-            spinner.stop();
+            spinner.succeed(`Finalized in block #${event.block.number}`);
             resolve(event);
             break;
         }
@@ -1823,6 +2127,110 @@ function watchTransaction(observable) {
   });
 }
 
+// src/core/update-notifier.ts
+import { readFileSync } from "node:fs";
+import { mkdir as mkdir3, writeFile as writeFile3 } from "node:fs/promises";
+import { join as join3 } from "node:path";
+var CACHE_FILE = "update-check.json";
+var STALE_MS = 24 * 60 * 60 * 1000;
+var FETCH_TIMEOUT_MS = 5000;
+var REGISTRY_URL = "https://registry.npmjs.org/polkadot-cli/latest";
+function parseSemver(v) {
+  const clean = v.replace(/^v/, "").split("-")[0] ?? v;
+  const parts = clean.split(".").map(Number);
+  return [parts[0] ?? 0, parts[1] ?? 0, parts[2] ?? 0];
+}
+function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  for (let i = 0;i < 3; i++) {
+    const left = pa[i] ?? 0;
+    const right = pb[i] ?? 0;
+    if (left < right)
+      return -1;
+    if (left > right)
+      return 1;
+  }
+  return 0;
+}
+function isNewerVersion(current, latest) {
+  return compareSemver(current, latest) < 0;
+}
+function buildNotificationBox(current, latest) {
+  const YELLOW2 = "\x1B[33m";
+  const GREEN2 = "\x1B[32m";
+  const CYAN2 = "\x1B[36m";
+  const RESET2 = "\x1B[0m";
+  const BOLD2 = "\x1B[1m";
+  const line1 = `Update available! ${YELLOW2}${current}${RESET2} → ${GREEN2}${BOLD2}${latest}${RESET2}`;
+  const line2 = `Run ${CYAN2}npm i -g polkadot-cli${RESET2} to update`;
+  const visibleLine1 = `Update available! ${current} → ${latest}`;
+  const visibleLine2 = `Run npm i -g polkadot-cli to update`;
+  const innerWidth = Math.max(visibleLine1.length, visibleLine2.length) + 4;
+  const pad1 = " ".repeat(innerWidth - visibleLine1.length - 4);
+  const pad2 = " ".repeat(innerWidth - visibleLine2.length - 4);
+  const empty = " ".repeat(innerWidth);
+  const top = `╭${"─".repeat(innerWidth)}╮`;
+  const bot = `╰${"─".repeat(innerWidth)}╯`;
+  return [
+    top,
+    `│${empty}│`,
+    `│  ${line1}${pad1}  │`,
+    `│  ${line2}${pad2}  │`,
+    `│${empty}│`,
+    bot
+  ].join(`
+`);
+}
+function getCachePath() {
+  return join3(getConfigDir(), CACHE_FILE);
+}
+function readCache() {
+  try {
+    const data = readFileSync(getCachePath(), "utf-8");
+    return JSON.parse(data);
+  } catch {
+    return null;
+  }
+}
+async function writeCache(cache) {
+  try {
+    await mkdir3(getConfigDir(), { recursive: true });
+    await writeFile3(getCachePath(), `${JSON.stringify(cache)}
+`);
+  } catch {}
+}
+function startBackgroundCheck(_currentVersion) {
+  const cache = readCache();
+  const now = Date.now();
+  if (cache && now - cache.lastCheck < STALE_MS) {
+    return;
+  }
+  fetch(REGISTRY_URL, {
+    signal: AbortSignal.timeout(FETCH_TIMEOUT_MS)
+  }).then((res) => res.json()).then((data) => {
+    const latestVersion = data.version;
+    if (typeof latestVersion === "string") {
+      writeCache({ lastCheck: now, latestVersion });
+    }
+  }).catch(() => {});
+}
+function getUpdateNotification(currentVersion) {
+  if (process.env.DOT_NO_UPDATE_CHECK === "1")
+    return null;
+  if (process.env.CI)
+    return null;
+  if (!process.stderr.isTTY)
+    return null;
+  const cache = readCache();
+  if (!cache)
+    return null;
+  if (isNewerVersion(currentVersion, cache.latestVersion)) {
+    return buildNotificationBox(currentVersion, cache.latestVersion);
+  }
+  return null;
+}
+
 // src/utils/errors.ts
 class CliError2 extends Error {
   constructor(message) {
@@ -1832,6 +2240,7 @@ class CliError2 extends Error {
 }
 
 // src/cli.ts
+startBackgroundCheck(version);
 var cli = cac("dot");
 cli.option("--chain <name>", "Target chain (default from config)");
 cli.option("--rpc <url>", "Override RPC endpoint for this call");
@@ -1848,6 +2257,13 @@ registerTxCommand(cli);
 registerHashCommand(cli);
 cli.help();
 cli.version(version);
+function showUpdateAndExit(code) {
+  const note = getUpdateNotification(version);
+  if (note)
+    process.stderr.write(`${note}
+`);
+  process.exit(code);
+}
 function handleError(err) {
   if (err instanceof CliError2) {
     console.error(`Error: ${err.message}`);
@@ -1856,16 +2272,19 @@ function handleError(err) {
   } else {
     console.error("An unexpected error occurred:", err);
   }
-  process.exit(1);
+  showUpdateAndExit(1);
 }
 try {
   cli.parse(process.argv, { run: false });
-  if (!cli.matchedCommandName && !cli.options.help && !cli.options.version) {
+  if (cli.options.version || cli.options.help) {
+    showUpdateAndExit(0);
+  } else if (!cli.matchedCommandName) {
     cli.outputHelp();
+    showUpdateAndExit(0);
   } else {
     const result = cli.runMatchedCommand();
     if (result && typeof result.then === "function") {
-      result.then(() => process.exit(0), handleError);
+      result.then(() => showUpdateAndExit(0), handleError);
     }
   }
 } catch (err) {

package/package.json

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